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PREFACE 


About  This  Reference 


This  multivolume  work  defines  the  complete  C  application  programming 
interface  (API)  for  the  QuickTime  system  software.  It's  Apple's  official  guide  to 
the  more  than  2000  function  calls  that  QuickTime  applications  can  make.  The 
printed  edition  consists  of  four  volumes  internally  cross-referenced  by  page 
numbers.  The  online  edition  consists  of  a  single  Adobe  PDF  file  with  live 
internal  links  and  the  same  content  in  a  set  of  linked  HTML  pages  posted  to  the 
QuickTime  Developer  Documentation  website. 

Note 

The  pages  in  the  printed  and  PDF  versions  of  this  reference 
are  numbered  the  same  and  run  sequentially  from  the  start 
of  Volume  I  to  the  end  of  Volume  V.  Every  page  citation  is 
preceded  by  its  volume  number  so  you  know  which  book 
to  open  in  the  printed  version.  ♦ 

QuickTime  is  a  system-level  software  package  that  computer  users  store  on 
their  Windows  and  Macintosh  systems.  It  lets  the  host  computer  play  and 
stream  movies,  synthesize  music,  display  virtual  reality  environments,  and 
generate  animated  graphics.  Your  code  can  invoke  QuickTime's  capabilities 
through  the  API  described  in  this  document. 

This  reference  assumes  that  you  are  familiar  with  programming  techniques 
and  with  the  C  programming  language.  For  a  more  general  overview  of  the 
QuickTime  API  see  Discovering  QuickTime,  available  in  computer  bookstores. 

For  further  technical  information  about  using  the  QuickTime  API,  see  the  books 
and  websites  cited  in  the  bibliography  (V-3053).  It  lists  a  number  of 
introductory  and  advanced  programming  guides  designed  to  help  you  exploit 
all  the  capabilities  of  this  powerful  software. 


Content  Summary 


Volumes  I  through  III  of  this  reference  list  the  QuickTime  API  functions 
alphabetically,  describing  how  each  one  works.  Where  constants  are  passed 
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directly  to  a  function,  they  are  explained  in  the  function's  description.  Many 
function  descriptions  are  illustrated  with  code  snippets.  Callbacks  are  listed 
alphabetically  at  the  end  of  Volume  III. 

Volume  IV  describes  the  data  types  that  the  QuickTime  API  uses — structs, 
atoms,  and  defined  types.  It  also  documents  certain  global  constants  not 
covered  in  Volumes  I— III. 

Volume  V  contains  a  programming  summary  designed  to  help  you  understand 
how  the  QuickTime  API  is  used  to  perform  actual  tasks.  Also  included  are 
alphabetical  cross-indexes  of  data  types  and  constants,  plus  an  index  of 
functions  arranged  by  their  order  in  the  QuickTime  header  files.  A  preface  at  the 
beginning  of  Volume  V  tells  you  more  about  these  access  aids. 

At  the  end  of  Volume  V  are  a  bibliography,  a  glossary,  and  a  history  of  the 
revisions  to  this  reference. 

A  table  of  contents  that  covers  all  five  volumes  is  included  at  the  beginning  of 
Volume  I. 


Documentation  Principles 


The  technical  documentation  sections  of  this  reference  follow  certain  guiding 

principles: 

■  Multiple  publication:  Every  release  of  this  reference  is  published 
simultaneously  in  paper,  PDF,  and  HTML.  The  paper  version  includes  a  CD 
that  contains  the  PDF  and  HTML  versions.  The  content,  references,  and  links 
are  the  same  in  all  these  formats,  so  that  information  found  in  one  medium 
can  easily  be  located  in  another. 

■  Quick  access:  This  reference  is  designed  for  quick  access  to  information. 
Functions,  callbacks,  structs,  and  atoms  are  listed  alphabetically  by  name  in 
Volumes  I  through  IV.  Constants  and  data  types  are  grouped  logically,  but 
are  also  indexed  alphabetically  at  the  end  of  Volume  IV.  All  cross-references 
cite  volume  and  page  numbers  for  users  of  the  paper  version  but  also  appear 
as  software  links  in  the  PDF  and  HTML  versions. 

■  Explanatory  closure:  All  API  elements  mentioned  in  this  reference,  including 
all  parameter  and  field  types,  are  linked  to  their  documentation  at  other 
locations.  The  chain  of  explanations  is  carried  down  to  the  level  of  C  reserved 
types  (Boolean,  short,  long,  etc.). 
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■  Document  history:  Volume  IV  contains  a  full  history  of  revisions  to  this 
reference,  both  by  date  and  by  API  element. 

■  Links  to  programming  guides:  This  reference  is  designed  to  be  used  in 
conjunction  with  the  Apple  "Inside  QuickTime"  programming  guides 
described  in  the  bibliography  (V-3053).  Future  Inside  QuickTime  books  will 
cite  this  reference  for  programming  details. 


Typical  Function  Description 


A  typical  function  description  in  Volumes  I— III  looks  like  this: 


GetTimeBaseStatus 


Determines  when  the  current  time  of  a  time  base  would  fall  outside  of  the  range  of 
values  specified  by  the  time  base's  start  and  stop  times. 

long  GetTimeBaseStatus  ( 

TimeBase  tb,  //  IV-2425 

TimeRecord  *unpinnedTime  );  //  I V- 2209 

tb 

The  time  base  for  this  operation.  Your  application  obtains  this  time  base 
identifier  from  the  NewTimeBase  (11—1172)  function. 

unpinnedTime  I _ I  ^ 

A  pointer  to  a  time  structure  that  is  to  receive  the  current  time  of  the  time  base. 
Note  that  this  time  value  may  be  outside  the  range  of  values  specified  by  the 
start  and  stop  times  of  the  time  base. 

function  result  See  below. 

Function  Result  Constants 

timeBaseBeforeStartTime 

Returned  if  the  time  value  in  the  time  structure  referred  to  by  the  unpinnedTime 
parameter  lies  before  the  start  time  of  the  time  base. 

timeBaseAfterStopTime 

Returned  if  the  time  value  in  the  time  structure  referred  to  by  the  unpi  nnedT i  me 
parameter  lies  after  the  stop  time  of  the  time  base. 


Discussion 

The  status  information  returned  by  this  function  allows  you  to  determine  when  the 
current  time  of  a  time  base  would  fall  outside  of  the  range  of  values  specified  by  the 
start  and  stop  times  of  the  time  base.  This  can  happen  when  a  time  base  relies  on  a 
master  time  base  or  when  its  time  has  reached  the  stop  time. 


C  Interface  File 

Movies. h 

Related  Java  Methods 

qui cktime. std . cl ocks .TimeBase. get Status! ) 

See  Also 

See  GetTimeBaseFl  ags  (1-465). 


J —  Abstract 
1 —  Declaration 


—  Term  defined  in  glossary 

—  Parameter  descriptions 


—  Constant  descriptions 


—  Discussion 


—  Other  information 
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Function  descriptions  provide  you  with  the  following  programming 
information: 

■  The  abstract  describes  briefly  what  the  function  does  or  how  you  use  it. 

Some  Apple  programming  guides  repeat  these  abstracts  to  jog  your  memory 
about  a  function's  role  in  the  API.  You  could  think  of  a  function's  abstract  as 
its  natural-language  declaration. 

■  The  declaration  schematizes  the  way  you  call  the  function  in  your  code.  The 
parameter  and  result  types  in  each  function  declaration  are  linked  to  their 
data  type  descriptions  in  Volume  IV  by  page  numbers  written  as  comments. 

■  The  parameter  descriptions  tell  you  what  kind  of  information  is  passed  into 
or  out  of  the  function. 

■  Constants  that  are  passed  are  usually  defined  in  one  or  more  constant 
descriptions  sections  following  the  parameter  descriptions.  When  a 
parameter  description  mentions  a  function  or  data  type  described  elsewhere 
in  this  book,  it  cites  the  appropriate  page  number. 

■  The  discussion  tells  you  in  detail  what  the  function  does  and  how  you  use  it. 
Discussion  sections  often  include  code  snippets  that  illustrate  how  and  why 
you  call  the  function  from  your  code. 

■  Several  sections  of  other  information  help  you  understand  how  to  use  the 
function  in  your  programming.  This  information  is  labeled  with  these 
headings: 

□  The  special  considerations  section  warns  you  about  system  factors,  such 
as  interrupts  and  prior  calls,  that  may  affect  how  the  function  works. 

□  The  version  notes  section  summarizes  the  function's  history  in  the 
QuickTime  API  and  warn  you  of  any  QuickTime  versions  that  do  not 
support  it.  Functions  introduced  before  QuickTime  3  are  marked 
"Introduced  in  QuickTime  3  or  earlier." 

□  The  Programming  info  section  gives  you  the  name  of  the  header  file 
where  the  function  is  declared  and  refers  you  to  the  Programming 
Summary  section  that  discusses  how  the  function  is  used. 

□  If  you  are  a  Java  programmer,  the  related  Java  methods  section  helps  you 
understand  how  QuickTime  for  Java  uses  the  function. 

□  The  see  also  section  points  you  to  further  sources  of  information  about  the 
function  and  about  related  API  elements  in  this  and  other  books. 

The  chapters  that  document  data  structures,  atoms,  and  callbacks  follow  a 
similar  plan. 
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AbortPrePrerollMovie 


AbortPrePrerollMovie 


Terminates  the  operation  of  PrePrerol  1  Movi  e  (11-1141). 

void  AbortPrePrerollMovie  ( 

Movie  m, 

OSErr  err  ); 


m 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

err 

See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  normally  call  this  function  only  if  you  have  previously  called  PrePrerol  1  Movie 
(11-1141)  asynchronously  and  the  user  quits  your  application. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Enhancing  Movie  Playback  Performance"  (V-2722) 

Related  Java  Methods 

qui cktime . std .movi es . Movi e . abort PrePrerol 1 ( ) 


See  Also 


See  PrePrerol  1  Movi e  (11-1141). 


AddCallBackT  oT  imeBase 

Places  a  callback  event  into  the  list  of  scheduled  callback  events. 

OSErr  AddCall BackToTimeBase  ( 

QTCallBack  cb  ); 
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cb 

Specifies  the  callback  event  for  the  operation.  Your  clock  component  obtains 
this  value  from  the  parameters  passed  to  ClockCallMeWhen  (1-91). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

If  your  component  calls  this  function,  the  Movie  Toolbox  notifies  it  of  time,  rate,  or 
stop  and  start  changes  via  Cl  ockRateChanged  (1-97)  and  Cl  ockT i  meChanged  (1-100). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Movie  Toolbox  Clock  Support  Functions"  (V-2869) 

See  Also 

See  Cl  ockNewCal  1  Back  (1-96)  and  Cl  ockCal  1  MeWhen  (1-91). 


AddClonedT  rackT  oMo  vie 


Constructs  a  clone  of  an  existing  track  in  a  movie. 

OSErr  AddClonedTrackToMovie  ( 

Track  sourceTrack, 

Movie  desti nati onMovi e , 

long  flags, 

T rack  *newT rack  ) ; 

sourceT  rack 

Indicates  the  track  to  be  cloned.  Your  application  obtains  this  track  identifier 
from  such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497).  This 
is  the  source  of  the  sample  table  once  the  cloned  track  is  constructed. 

desti nati onMovi e 

Indicates  the  movie  where  the  cloned  track  should  be  created.  Your  application 
obtains  this  identifier  from  such  functions  as  NewMovi  e  (11-1069), 

NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e  (11-1084).  Currently,  this 
must  be  the  movie  that  contains  the  source  track. 
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fl  ags 

Flags  (see  below)  that  determine  how  cloning  should  be  performed.  You 
currently  must  pass  kQTCl  oneShareSampl  es. 
newT  rack 

The  address  of  storage  where  a  reference  to  the  newly  constructed  track  is 
returned.  If  the  function  fails,  this  storage  is  set  to  N I L. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

flags  Constants 

kQTCl oneShareSampl es 

Indicates  that  you  want  to  share  the  sample  table  between  the  source  and  clone 
tracks.  If  you  don't  pass  this  flag,  currently,  the  AddClonedTrackToMovie  call  will 
fail. 

kQTCl oneDontCopyEdi  ts 

By  default,  the  edit  list  is  copied  from  the  source  track  to  the  cloned  track.  Use 
this  flag  to  leave  the  clone  track's  edit  list  empty. 

Special  Considerations 

Most  QuickTime  developers  should  never  need  to  call  this  function. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

See  Also 

This  function  is  similar  to  Ad d Empty T rackToMovi  e  (1-23),  in  that  it  helps  you  create  a 
new  track  and  media  compatible  with  a  specified  track. 


AddEmptyT  rackT  oMovie 


Duplicates  a  track  from  a  movie  into  the  same  movie  or  into  another  movie. 
OSErr  AddEmptyTrackToMovie  ( 


T  rack 

srcTrack, 

Movi  e 

dstMovi e , 

Hand! e 

dataRef , 

OSType 

dataRefType 

T  rack 

*dstTrack  ) 
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srcT  rack 

The  source  track  for  this  operation.  Your  application  obtains  this  track  identifier 
from  such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi eT rack  (1-497). 
dstMovi e 

The  destination  movie  for  this  operation.  This  can  be  the  same  movie  as  the 
source  track  or  a  different  movie. 

dataRef 

A  handle  to  the  data  reference.  The  type  of  information  stored  in  the  handle 
depends  upon  the  data  reference  type  specified  by  dataRefType. 
dataRefType 

The  type  of  data  reference;  see  "Data  References"  (IV-2661).  If  the  data 
reference  is  an  alias,  you  must  set  the  parameter  to  rAl  i  asType,  indicating  that 
the  reference  is  an  alias. 
dstT  rack 

The  newly  created  track's  identifier  is  returned  in  this  parameter.  If 
AddEmptyT rackToMovi e  fails,  the  resulting  track  identifier  is  set  to  NIL. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

This  function  returns  a  newly  created,  empty  track.  The  newly  created  track  has  the 
same  media  type  and  track  settings  as  the  specified  track.  However,  no  data  is 
copied  from  the  source  track  to  the  new  track.  To  copy  data  from  the  source  track  to 
the  new  track,  use  InsertT  rackSegment  (11-764)  after  calling  AddEmptyT  rackToMovi  e. 

Version  Notes 

This  function  has  been  available  since  QuickTime  2.0. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Editing  Tracks"  (V-2750) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . add  Empty T rack( ) 


AddFilePreview 

Adds  a  preview  to  a  file. 
OSErr  AddFilePreview  ( 
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short  resRefNum, 

OSType  previewType, 

Handle  previewData  ); 

resRefNum 

The  resource  file  for  this  operation.  You  must  have  opened  this  resource  file 
with  write  permission.  If  there  is  a  preview  in  the  specified  file,  the  Movie 
Toolbox  replaces  that  preview  with  a  new  one. 
previ ewType 

The  resource  type  to  be  assigned  to  the  preview.  This  type  should  correspond 
to  the  type  of  data  stored  in  the  preview.  For  example,  if  you  have  created  a 
QuickDraw  picture  that  you  want  to  use  as  a  preview  for  a  file,  you  should  set 
the  previ  ewType  parameter  to  '  PICT' . 

previ ewData 

A  handle  to  the  preview  data.  For  example,  if  the  preview  data  is  a  picture,  you 
would  provide  a  picture  handle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  must  have  created  the  preview  data  yourself.  If  the  specified  file  already  has  a 
preview  defined,  the  AddFi  1  ePrevi  ew  function  replaces  it  with  the  new  preview. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Creating  File  Previews"  (V-2757) 


AddlmageDescriptionExtension 


Adds  an  extension  to  an  ImageDescri  pti  on  (IV-2285)  structure. 

OSErr  AddlmageDescriptionExtension  ( 

ImageDescri pti onHandl e  desc. 

Handle  extension, 

long  idType  ); 


desc 

A  handle  to  the  ImageDescri  pti  on  (IV-2285)  structure  to  add  the  extension  to. 
extensi on 

The  handle  containing  the  extension  data. 
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i dType 

A  four-byte  signature  identifying  the  type  of  data  being  added  to  the 
ImageDescri pti on. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  allows  the  application  to  add  custom  data  to  an 

ImageDescri  pti  onHandle.  This  data  could  be  specific  to  the  compressor  component 

referenced  by  the  ImageDescri  pti  on  (IV-2285)  structure. 

Special  Considerations 

The  Image  Compression  Manager  makes  a  copy  of  the  data  referred  to  by  the 
extension  parameter.  Thus,  your  application  should  dispose  its  copy  of  the  data 
when  it  is  no  longer  needed. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Image  Descriptions"  (V-2790) 


AddMediaDataRef 


Adds  a  data  reference  to  a  media. 

OSErr  AddMediaDataRef  ( 

Media  theMedia, 

short  *index, 

Handle  dataRef, 

OSType  dataRefType  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetT rackMedi  a  (1-535). 

i  ndex 

A  pointer  to  a  short  integer.  The  Movie  Toolbox  returns  the  index  value  that  is 
assigned  to  the  new  data  reference.  Your  application  can  use  this  index  to 
identify  the  reference  to  other  Movie  Toolbox  functions,  such  as 
GetMedi  aDataRef  (1-427).  If  the  Movie  Toolbox  cannot  add  the  data  reference  to 
the  media,  it  sets  the  returned  index  value  to  0. 
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dataRef 

The  data  reference.  This  parameter  contains  a  handle  to  the  information  that 
identifies  the  file  that  contains  this  media's  data.  The  type  of  information  stored 
in  that  handle  depends  upon  the  value  of  the  dataRefType  parameter. 
dataRefType 

The  type  of  data  reference.  If  the  data  reference  is  an  alias,  you  must  set  this 
parameter  to  rAl  i  asType. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Data  References"  (V-2740) 

Related  Java  Methods 

qui cktime . std .movi es .medi a.Media.addDataRef() 


See  Also 

See  Inside  Macintosh:  Files  (listed  in  the  bibliography)  for  more  information  about 
aliases  and  the  Alias  Manager. 


AddMediaSample 


Adds  sample  data  and  a  description  to  a  media. 

OSErr  AddMediaSample  ( 

Medi  a 
Handl e 
1  ong 

unsigned  long 
T i meVal ue 

Samp! eDescri pti onHandl e 
1  ong 
short 
T i meVal ue 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 


theMedi a , 
dataln, 
i nOf f set , 
size, 

durati onPerSampl e , 
sampl eDescri pti onH  , 
numberOf Sampl es , 
sampl  eFl  ags , 
*sampleTime  ); 
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dataln 

A  handle  to  the  sample  data.  The  AddMediaSample  function  adds  this  data  to  the 
media  specified  by  the  parameter  theMedia.You  specify  the  number  of  bytes  of 
sample  data  with  the  size  parameter.  You  can  use  the  inOffset  parameter  to 
specify  a  byte  offset  into  the  data  referred  to  by  this  handle, 
i nOffset 

Specifies  an  offset  into  the  data  referred  to  by  the  handle  contained  in  the  dataln 
parameter.  Set  this  parameter  to  0  if  there  is  no  offset. 

si  ze 

The  number  of  bytes  of  sample  data  to  be  added  to  the  media.  This  parameter 
indicates  the  total  number  of  bytes  in  the  sample  data  to  be  added  to  the  media, 
not  the  number  of  bytes  per  sample.  Use  the  numberOfSampl  es  parameter  to 
indicate  the  number  of  samples  that  are  contained  in  the  sample  data, 
durati onPerSampl e 

The  duration  of  each  sample  to  be  added.  You  must  specify  this  parameter  in 
the  media's  time  scale.  For  example,  if  you  are  adding  sound  that  was  sampled 
at  22  kHz  to  a  media  that  contains  a  sound  track  with  the  same  time  scale,  you 
would  set  durati  onPerSampl  e  to  1.  Similarly,  if  you  are  adding  video  that  was 
recorded  at  10  frames  per  second  to  a  video  media  that  has  a  time  scale  of  600, 
you  would  set  this  parameter  to  60  to  add  a  single  sample. 

sampl eDescri pti onH 

A  handle  to  a  Sampl  eDescri  pti  on  (IV-2414)  structure.  Some  media  structures 
may  require  sample  descriptions.  There  are  different  descriptions  for  different 
types  of  samples.  For  example,  a  media  that  contains  compressed  video 
requires  that  you  supply  anlmageDescription  (IV-2285)  structure.  A  media  that 
contains  sound  requires  that  you  supply  a  SoundDescri  pti  on  (IV-2449) 
structure.  If  the  media  does  not  require  a  Sampl  eDescri  pti  on  structure,  set  this 
parameter  to  NIL. 

numberOfSampl es 

The  number  of  samples  contained  in  the  sample  data  to  be  added  to  the  media. 
The  Movie  Toolbox  considers  the  value  of  this  parameter  as  well  as  the  value  of 
the  size  parameter  when  it  determines  the  size  of  each  sample  that  it  adds  to 
the  media.  You  should  set  the  value  of  this  parameter  so  that  the  resulting 
sample  size  represents  a  reasonable  compromise  between  total  data  retrieval 
time  and  the  overhead  associated  with  input  and  output  (1/ O).  You  should  also 
consider  the  speed  of  the  data  storage  device;  CD-ROM  devices  are  much 
slower  than  hard  disks,  for  example,  and  should  therefore  have  a  smaller 
sample  size.  For  a  video  media,  set  a  sample  size  that  corresponds  to  the  size  of 
a  frame.  For  a  sound  media,  choose  a  number  of  samples  that  corresponds  to 
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between  0.5  and  1.0  seconds  of  sound.  In  general,  you  should  not  create  groups 
of  sound  samples  that  are  less  than  2  KB  in  size  or  greater  than  15  KB.  Typically, 
a  sample  size  of  about  8  KB  is  reasonable  for  most  storage  devices. 

sampl  e FI  ags 

Contains  flags  (see  below)  that  control  the  add  operation.  Set  unused  flags  to  0. 
sampl eTime 

A  pointer  to  a  time  value.  After  adding  the  sample  data  to  the  media,  the 
AddMedi  aSampl  e  function  returns  the  time  where  the  sample  was  inserted  in  the 
time  value  referred  to  by  this  parameter.  If  you  don't  want  to  receive  this 
information,  set  this  parameter  to  NIL. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

sampleFlags  Constants 

medi aSampl eNotSync 

Indicates  that  the  sample  to  be  added  is  not  a  sync  sample.  Set  this  flag  to  1  if 
the  sample  is  not  a  sync  sample.  Set  this  flag  to  0  if  the  sample  is  a  sync  sample. 

Discussion 

Your  application  specifies  the  sample  and  the  media  for  the  operation. 

AddMedi  aSampl  e  updates  the  media  so  that  it  contains  the  sample  data.  One  call  to 
this  function  can  add  several  samples  to  a  media;  however,  all  the  samples  must  be 
the  same  size.  Samples  are  always  appended  to  the  end  of  the  media.  Furthermore, 
the  media  duration  is  extended  each  time  a  sample  is  added. 

//  AddMediaSample  coding  example 

//  See  “Discovering  QuickTime,”  page  250 


#define  kSoundSampl eDurati on  1 
#define  kSyncSample  0 

#define  kTrackStart  0 

#define  kMediaStart  0 

#def i ne  kFixl  0x00010000 


void  CreateMySoundTrack  (Movie  movie) 

{ 

Track  track; 

Media  media; 

Handle  hSound  =  NIL; 

SoundDescri pti onHandl e  hSoundDesc  =  NIL; 

long  IDataOffset; 
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long  IDataSize; 

long  INumSamples; 


hSound  =  GetResourcetsoundListRsrc,  128); 
if  (hSound  ==  NIL) 
return ; 

hSoundDesc  =  (SoundDescriptionHandle)NewHandle(4) ; 

CreateMySoundDescripti on (hSound, 

hSoundDesc , 

&1 DataOffset , 

&1 NumSampl es , 

&1 DataSi ze ) ; 

track  =  NewMovi eTracktmovi e  ,  0,  0,  k  Fu 1 1 Vol ume ) ; 
media  =  NewTrackMedi a ( track ,  SoundMedi aType , 

FixRound((**hSoundDesc). sample Rate), 
NIL,  0)  ; 


BeginMediaEdits(media) ; 

AddMedi aSampl e(medi a  , 

hSound , 

IDataOffset,  //  offset  in  data 

1 DataSi ze , 

kSoundSampl eDurati on ,  //  duration  of  each  soun 

//  sample 

(SampleDescriptionHandle)hSoundDesc, 

1 NumSampl es , 

kSyncSample,  //  self-contained  samples 

NIL)  ; 

EndMediaEdits(media) ; 

Insert Med ialntoTrackttrack, 

kTrackStart,  //  track  start  time 

kMediaStart,  //  media  start  time 

GetMediaDuration(media) , 
kFixl) ; 
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} 


if  (hSoundDesc  !=  NIL) 

DisposeHandle((Handle)hSoundDesc); 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Adding  Samples  to  Media  Structures"  (V-2752) 

Related  Java  Methods 

qui ckti me . std .movi es .medi a . Medi a.addSamplel) 


See  Also 

See  AddMedi  aSampl  eReference  (1-31)  and  AddMedi  aSampl  eReferences  (1-33). 


AddMediaSampleReference 


Works  with  samples  that  have  already  been  added  to  a  movie  data  file. 


OSErr  AddMediaSampleReference 
Medi  a 
1  ong 

unsigned  long 
T i meVal ue 

Sampl  eDescri pti onHandl e 
1  ong 
short 
T i meVal ue 


( 

theMedi a , 
dataOf f set , 
size, 

durati onPerSampl e , 
sampl eDescri pti onH  , 
numberOf Sampl es , 
sampl  eFl  ags , 
*sampleTime  ); 


theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 
dataOf f set 

The  offset  into  the  movie  data  file.  This  parameter  is  used  differently  by  each 
data  handler.  For  example,  for  the  standard  HFS  data  handler,  this  parameter 
specifies  the  offset  into  the  file.  This  parameter  contains  either  data  you  add 
yourself  or  the  data  offset  returned  by  GetMedi  aSampl  eReference  (1-447). 

si  ze 

The  number  of  bytes  of  sample  data  to  be  identified  by  the  reference.  This 
parameter  indicates  the  total  number  of  bytes  in  the  sample  data,  not  the 
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number  of  bytes  per  sample.  Use  numberOfSamples  to  indicate  the  number  of 
samples  that  are  contained  in  the  reference. 

durati onPerSampl e 

The  duration  of  each  sample  in  the  reference.  You  must  specify  this  parameter 
in  the  media's  time  scale.  For  example,  if  you  are  referring  to  sound  that  was 
sampled  at  22  kHz  in  a  media  that  contains  a  sound  track  with  the  same  time 
scale,  to  add  a  reference  to  a  single  sample  you  would  set  durati  onPerSampl  e  to 
1.  Similarly,  if  you  are  referring  to  video  that  was  recorded  at  10  frames  per 
second  in  a  video  media  that  has  a  time  scale  of  60,  you  would  set  this 
parameter  to  6  to  add  a  reference  to  a  single  sample. 

sampl eDescri pti onH 

A  handle  to  a  Sampl  eDescri  pti  on  (IV-2414)  structure.  Some  media  structures 
may  require  sample  descriptions.  There  are  different  descriptions  for  different 
types  of  samples.  For  example,  a  media  that  contains  compressed  video 
requires  that  you  supply  anlmageDescription  (IV-2285)  structure.  A  media  that 
contains  sound  requires  that  you  supply  a  sound  description  structure.  If  the 
media  does  not  require  a  Sampl  eDescri  pti  on  structure,  set  this  parameter  to  NI L. 
numberOfSampl es 

The  number  of  samples  contained  in  the  reference.  For  details,  see 
AddMedi  aSampl  e  (1-27).  If  the  media  does  not  require  a  Sampl  eDescri  pti  on 
structure,  set  this  parameter  to  NI  L. 

sampl eFl ags 

Contains  flags  (see  below)  that  control  the  operation.  Set  unused  flags  to  0. 
sampl eT i me 

A  pointer  to  a  time  value.  After  adding  the  reference  to  the  media,  the 
AddMedi  aSampl  eReference  function  returns  the  time  where  the  reference  was 
inserted  in  the  time  value  referred  to  by  this  parameter.  If  you  don't  want  to 
receive  this  information,  set  this  parameter  to  NIL. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

sampleFlags  Constants 

medi aSampl e Not Sync 

Indicates  that  the  sample  to  be  added  is  not  a  sync  sample.  Set  this  flag  to  1  if 
the  sample  is  not  a  sync  sample.  Set  this  flag  to  0  if  the  sample  is  a  sync  sample. 

Discussion 

This  function  does  not  add  sample  data  to  the  file  or  device  that  contains  a  media. 
Rather,  it  defines  references  to  sample  data  that  you  previously  added  to  a  movie 
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data  file.  Instead  of  actually  writing  out  samples  to  disk,  this  function  writes  out 
references  to  existing  samples,  which  you  specify  in  dataOf  f  set  and  the  size 
parameter.  As  with  AddMedi  aSampl  e  (1-27),  your  application  specifies  the  media  for 
the  operation.  Note  that  one  reference  may  refer  to  more  than  one  sample;  all  the 
samples  described  by  a  reference  must  be  the  same  size.  This  function  does  not 
update  the  movie  data  file  as  part  of  the  add  operation.  Therefore,  your  application 
does  not  have  to  call  Begi  nMedi  aEdi  ts  (1-56)  before  calling  AddMedi  aSampl  e  Reference. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Adding  Samples  to  Media  Structures"  (V-2752) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Medi  a . addSampl eReference( ) 


See  Also 

See  AddMedi  aSampl  e  (1-27)  and  AddMedi  aSampl  eReferences  (1-33). 


AddMediaSampleReferences 


Adds  groups  of  samples  to  a  movie  data  file. 


OSErr  AddMediaSampleReferences 
Medi  a 

Sampl eDescri pti onHandl e 
1  ong 

Sampl eReferencePtr 
T i meVal ue 


( 

theMedi a , 

sampl eDescri pti onH  , 
numberOf Sampl es , 
sampl eRef s , 
*sampleTime  ); 


theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 

sampl eDescri pti onH 

A  handle  to  a  Sampl  eDescri  pti  on  (IV-2414)  structure.  Some  media  structures 
may  require  sample  descriptions.  There  are  different  descriptions  for  different 
types  of  samples.  For  example,  a  media  that  contains  compressed  video 
requires  that  you  supply  an  ImageDescri  pti  on  (IV-2285)  structure.  A  media  that 
contains  sound  requires  that  you  supply  a  sound  description  structure.  If  you 
don't  want  the  SampleDescription  structure,  set  this  parameter  to  NIL. 
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numberOfSampl es 

The  number  of  samples  contained  in  the  reference.  For  details,  see 
AddMedi  aSampl  e  (1-27). 
sampl eRefs 

A  pointer  to  the  number  of  Sampl  e  Reference  Re  cord  structures  specified  in  the 
numberOfSampl  es  parameter. 

sampl eT i me 

A  pointer  to  a  time  value.  After  adding  the  reference  to  the  media,  the 
AddMedi  aSampl  eReferences  function  returns  the  time  where  the  reference  was 
inserted,  using  the  time  scale  referred  to  by  this  parameter.  If  you  don't  want  to 
receive  this  information,  set  this  parameter  to  NIL. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

Using  this  function  instead  of  AddMedi  aSampl  eReference  (1-31)  can  greatly  improve 
the  performance  of  operations  that  involve  adding  a  large  number  of  samples  to  a 
movie  at  one  time.  AddMedi  aSampl  eReferences  provides  no  capabilities  that  weren't 
previously  available  with  AddMedi  aSampl  eReference. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Adding  Samples  to  Media  Structures"  (V-2752) 

Related  Java  Methods 

qui ckti me . std .movi es .medi a . Medi a . addSampl eReference ( ) 


See  Also 

See  AddMedi  aSampl  e  (1-27)  and  AddMedi  aSampl  eReference  (1-31). 


AddMediaSampleReferences64 


Provides  a  64-bit  version  of  AddMedi  aSampl  eReferences  (1-33). 


OSErr  AddMedi aSampl eReferences64  ( 

Media  theMedia, 

SampleDescriptionHandle  sampl eDescriptionH, 
long  numberOfSampl es , 

Sampl eReference64Ptr  sampleRefs, 
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TimeValue  *sampleTime  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 

sampl eDescri pti onH 

A  handle  to  a  Sampl  eDescri  pti  on  (IV-2414)  structure.  Some  media  structures 
may  require  sample  descriptions.  There  are  different  descriptions  for  different 
types  of  samples.  For  example,  a  media  that  contains  compressed  video 
requires  that  you  supply  an  ImageDescri  pti  on  (IV-2285)  structure.  A  media  that 
contains  sound  requires  that  you  supply  a  sound  description  structure.  If  you 
don't  want  the  SampleDescription  structure,  set  this  parameter  to  NIL. 
numberOf Sampl es 

The  number  of  samples  contained  in  the  reference.  For  details,  see 
AddMedi  aSampl  e  (1-27). 
sampl eRef s 

A  pointer  to  the  number  of  Sampl  eReference64Record  structures  specified  in  the 
numberOfSampl  es  parameter. 

sampl eTime 

A  pointer  to  a  time  value.  After  adding  the  reference  to  the  media,  the 
AddMedi  aSampl  eReferences  function  returns  the  time  where  the  reference  was 
inserted,  using  the  time  scale  referred  to  by  this  parameter.  If  you  don't  want  to 
receive  this  information,  set  this  parameter  to  NIL. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

The  only  difference  between  this  function  and  AddMedi  aSampl  eReferences  (1-33)  is 
that  the  sampl  eRef  s  parameter  points  to  Sampl  eReference64 Record  structures  instead 
of  Sampl  eReferenceRecord  structures. 

Special  Considerations 

New  applications  should  use  this  function  instead  of  the  32-bit  version. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 
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See  Also 

See  AddMedi  aSampl  eReferences  (1-33). 


AddMovieExecuteW  ired  ActionsProc 


Lets  you  add  a  callback  to  a  movie  to  execute  wired  actions. 

OSErr  AddMovi eExecuteWi redActi onsProc  ( 

Movie  theMovie, 

Movi  eExecuteWi  redActi  onsLIPP  proc, 

voi  d  *refCon  ) ; 

theMovi e 

A  movie  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e 
(11-1084). 

proc 

A  callback  function,  as  described  in  Movi  eExecuteWi  redActi  onsProc  (III— 2101). 
refCon 

A  reference  constant  to  be  passed  to  your  callback.  Use  this  parameter  to  point 
to  a  data  structure  containing  any  information  your  function  needs. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es .  h 


AddMovieResource 


Adds  a  movie  resource  to  a  specified  resource  file. 


OSErr  AddMovieResource 
Movi  e 
short 
short 

ConstStr255Param 


theMovi e , 
resRef Num , 
*resld , 
resName  ) ; 
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theMovi e 

The  movie  you  wish  to  add  to  the  movie  file.  Your  application  obtains  this 
movie  identifier  from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e 
(11-1080),  and  NewMovi  eFromHandle  (11-1084). 
resRefNum 

Identifies  the  movie  file  to  which  the  resource  is  to  be  added.  Your  application 
obtains  this  value  from  the  OpenMovieFile  (11-1133)  function. 

res  Id 

A  pointer  to  a  field  that  contains  the  resource  ID  number  for  the  new  resource. 
If  the  field  referred  to  by  resld  is  set  to  0,  the  Movie  Toolbox  assigns  a  unique 
resource  ID  number  to  the  new  resource.  The  toolbox  then  returns  the  movie's 
resource  ID  number  in  the  field  referred  to  by  the  resld  parameter. 

AddMovi  eResource  assigns  resource  ID  numbers  sequentially,  starting  at  128.  If 
resld  is  set  to  NIL,  the  Movie  Toolbox  assigns  a  unique  resource  ID  number  to 
the  new  resource  and  does  not  return  that  resource's  ID  value.  Set  resld  to 
movielnDataForkResIDto  add  the  new  resource  to  the  movie  file's  data  fork  (see 
below). 
resName 

Points  to  a  character  string  that  contains  the  name  of  the  movie  resource.  If  you 
set  resName  to  NIL,  the  toolbox  creates  an  unnamed  resource. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

resld  Constants 

movielnDataForkResID 

Adds  a  resource  to  a  movie  file's  data  fork. 

Discussion 

This  function  adds  the  movie  to  the  file,  effectively  saving  any  changes  you  have 
made  to  the  movie.  To  use  this  function  with  single-fork  movie  files,  pass 
movielnDataForkResID  as  the  resld  parameter.  After  updating  the  movie  file, 
AddMovi  eResource  clears  the  movie  changed  flag,  indicating  that  the  movie  has  not 
been  changed. 

//  AddMovieResource  coding  example 
//  See  “Discovering  QuickTime,”  page  243 
void  CreateMyCool Movi e  (void) 

{ 

StandardFi  1  eReply  sfr; 

Movie  movie  =  NIL; 
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FSSpec  fss; 

short  nFileRefNum  =  0; 

short  nResID  =  movielnDataForkResID; 

StandardPutFi 1 e( "\pEnter  movie  file  name:",  "\punti tl ed  .mov" ,  &sfr); 
i f  ( !  sf r . sfGood ) 
return ; 

CreateMovieFile(&sfr.sfFile, 

F0UR„CHAR„C0DE( 'TVOD' ) , 
smCurrentScri pt , 
createMovi eFi 1 eDel eteCurFi 1 e  | 
createMovi eFileDontCreateResFile, 

&nFileRefNum, 

&movi e ) ; 

CreateMyVi deoTracktmovi e ) ;  //  See  next  section 

CreateMySoundTrack(movie) ;  //  See  next  section 

AddMovi eResource(movi e ,  nFileRefNum,  &nResID,  NIL); 
if  (nFileRefNum  !=  0) 

CloseMovieFile(nFileRefNum) ; 

DisposeMovie(movie) ; 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Saving  Movies"  (V-2715) 

Related  Java  Methods 

quicktime.std.movies.Movie.addResourcet) 

AddMovieSelection 

Adds  one  or  more  tracks  to  a  movie. 

void  AddMovieSelection  ( 

Movie  theMovie, 

Movi e  src  ) ; 
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theMovi e 

The  destination  movie  for  this  operation.  Your  application  obtains  this  movie 
identifier  from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi 1 e  (11-1080), 
and  NewMovi  eFromHandl  e  (11-1084). 

src 

The  source  movie  for  this  operation.  AddMovi  eSel  ecti  on  adds  the  tracks  from 
this  movie  to  the  destination  movie.  The  function  adds  these  tracks  at  the  time 
specified  by  the  current  selection  in  the  destination  movie. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Discussion 

This  function  scales  the  source  movie  so  that  it  fits  into  the  destination  selection.  If 
the  current  selection  in  the  destination  movie  has  a  0  duration,  the  Movie  Toolbox 
adds  the  segment  at  the  beginning  of  the  current  selection.  The  entire  source  movie 
is  used  regardless  of  the  selection  in  the  source  movie.  The  Movie  Toolbox  removes 
any  empty  tracks  from  the  destination  movie  after  the  add  operation.  If  you  have 
assigned  a  progress  function  to  the  destination  movie,  the  Movie  Toolbox  calls  that 
progress  function  during  long  add  operations.  Following  is  an  example  of  using  this 
function: 


//  AddMovieSelection  coding  example 
//  See  “Discovering  QuickTime,”  page  363 
Movie  moviel; 

TimeValue  1 01 dDurati on ; 

Movie  movie2; 

long  llndex,  1 Ori gTrackCount , 

Track  track,  trackSprite; 


1 Referencelndex; 


//  get  the  first  track  in  original  movie  and  position  at  the  start 
trackSprite  =  GetMovi elndTracklmovi el ,  1); 

SetMovi eSel ecti onlmovi el ,  0 ,  0) ; 


//  remove  all  tracks  except  video  in  modifier  movie 
for  (llndex  =  1;  llndex  <=  GetMovi eTrackCountlmovi e2 ) ;  llndex++)  { 
Track  track  =  GetMovieIndTrack(movie2,  llndex); 

OSType  dwType; 

GetMedi  aHandlerDescripti on(GetT rackMedi a ( track) , 

&dwType ,  NIL,  NIL); 
if  (dwType  !=  VideoMedi aType)  { 
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DisposeMovieTrackt track) ; 

1  Index-  -  ; 

} 

} 

//  add  the  modifier  track  to  original  movie 
lOldDuration  =  GetMovi eDurati on (movi el ) ; 
AddMovieSelectiontmoviel,  movie2) ; 

D1sposeMovie(movie2) ; 

//  truncate  the  movie  to  the  length  of  the  original  track 
Del eteMovi eSegmenttmovi el,  lOldDuration, 

GetMovieDuration(moviel)  -  lOldDuration); 

//  associate  the  modifier  track  with  the  original  sprite  track 
track  =  GetMovi elndTracktmovi el ,  1 Ori gTrackCount  +  1); 
AddTrackReferencettrackSprite,  track,  kTrackModi f i erReference , 
&1 Referencelndex) ; 


Special  Considerations 

Some  Movie  Toolbox  functions  can  take  a  long  time  to  execute.  For  example,  if  you 
call  FI  attenMovi  e  (1-372)  and  specify  a  large  movie,  the  Movie  Toolbox  must  read 
and  write  all  the  sample  data  for  the  movie.  During  such  operations  you  may  wish 
to  display  some  kind  of  progress  indicator  to  the  user.  A  progress  function  is  an 
application-defined  function  that  you  can  create  to  track  the  progress  of 
time-consuming  activities  and  keep  the  user  informed. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "High-Level  Movie  Editing  Functions"  (V-2746) 

Related  Java  Methods 

quicktime.std.movies.Movie.addSelectiont) 


AddSoundDescriptionExtension 


Adds  an  extension  to  a  SoundDescri  pti  on  (IV-2449)  structure. 

OSErr  AddSoundDescriptionExtension  ( 

SoundDescri pti onHandl e  desc, 
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Handle  extension, 

OSType  idType  ); 

desc 

A  handle  to  the  SoundDescri  pti  on  (IV-2449)  structure  to  add  the  extension  to. 
extensi on 

The  handle  containing  the  extension  data, 
i  dType 

A  four-byte  signature  identifying  the  type  of  data  being  added  to  the 
SoundDescri pti on. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

Two  extensions  are  defined  to  the  SoundDescri  pti  on  record.  The  first  is  the  slope, 
intercept,  m  i  n  C 1  i  p,  and  m  a  x  C 1  i  p  parameters  for  audio,  represented  as  an  atom  of  type 
'flap'  (IV-2537).  The  second  extension  is  the  ability  to  store  data  specific  to  a  given 
audio  codec,  using  a  SoundDescri  pti  onVl  (IV-2451)  structure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Related  Java  Methods 

qui cktime . std .movi es .medi a . SoundDescri pti on . add Extensi on ( ) 


AddTime 


Adds  two  times. 

void  AddTime  ( 

TimeRecord  *dst, 

const  TimeRecord  *src  ); 


A  pointer  to  a  time  structure.  This  time  structure  contains  one  of  the  operands 
for  the  addition.  AddT i  me  returns  the  result  of  the  addition  into  this  time 
structure. 
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src 

A  pointer  to  a  time  structure.  The  Movie  Toolbox  adds  this  value  to  the  time  or 
duration  specified  by  the  dst  parameter. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94). 

Discussion 

You  must  specify  the  input  times  in  time  structures.  The  result  value  is  formatted 
as  a  duration  or  a  time  value,  the  same  as  the  format  of  the  structure  pointed  to  by 
the  dst  parameter. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Times"  (V-2762) 

Related  Java  Methods 

qui cktime. std . cl ocks .TimeRecord . addTimeC ) 


AddT  rackRef  erence 


Adds  a  new  track  reference  to  a  track. 

OSErr  AddTrackReference  ( 

Track  theTrack, 

Track  refTrack, 

OSType  refType, 

1  ong  *addedlndex  ) ; 

theT  rack 

Identifies  the  track  for  this  operation.  Your  application  obtains  this  track 
identifier  from  such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack 
(1-497). 

refT  rack 

The  track  to  be  identified  in  the  track  reference. 
refType 

The  type  of  reference. 
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addedlndex 

A  pointer  to  a  long  integer.  The  toolbox  returns  the  index  value  assigned  to  the 
new  track  reference.  If  you  don't  want  this  information,  set  this  parameter  to 
NIL. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

The  following  code  snippet  shows  how  AddTrackReference  can  be  used  to  add  a 
modifier  track  reference  to  a  sprite  track. 

//  AddTrackReference  coding  example 
//  See  “Discovering  QuickTime,"  page  363 
Movie  moviel; 

TimeValue  1 01 dDurati on  ; 

Movie  movie2; 

long  llndex,  1 Ori gTrackCount ,  1 Referencelndex; 

Track  track,  trackSprite; 

//  get  the  first  track  in  original  movie  and  position  at  the  start 
trackSprite  =  GetMovi elndTracklmovi el ,  1); 

SetMovi eSel ecti onlmovi el ,  0 ,  0) ; 

//  remove  all  tracks  except  video  in  modifier  movie 

for  (llndex  =  1;  llndex  <=  GetMovi eTrackCount(movi e2 ) ;  llndex++)  { 

Track  track  =  GetMovieIndTrack(movie2,  llndex); 

OSType  dwType; 

GetMedi aHandl erDescri pti on(GetT  rackMedi a ( track) , 

&dwType ,  NIL,  NIL); 
if  (dwType  !=  VideoMedi aType)  { 

DisposeMovieTrack( track); 

1  Index- - ; 

} 

} 

//  add  the  modifier  track  to  original  movie 
lOldDuration  =  GetMovi eDurati on(moviel ) ; 

AddMovi eSel ecti on(movi el ,  movi e2 ) ; 

Di sposeMovi e(movi e2 ) ; 
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//  truncate  the  movie  to  the  length  of  the  original  track 
Del eteMovi eSegmenttmovi el,  lOldDuration, 

GetMovieDuration(moviel)  -  lOldDuration); 

//  associate  the  modifier  track  with  the  original  sprite  track 
track  =  GetMovi elndTracktmovi el ,  1 Ori gTrackCount  +  1); 
AddTrackReferencettrackSprite,  track,  kTrackModi f i erReference , 

&1 Referencelndex) ; 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Track  References"  (V-2737) 

Related  Java  Methods 

qu ickti me. std. mo vies. Track. add ReferenceO 

AddUserData 


Adds  an  item  to  a  user  data  list. 

OSErr  AddUserData  ( 

UserData  theUserData, 

Handle  data, 

OSType  udType  ) ; 

theUserData 

The  user  data  list  for  this  operation.  You  obtain  this  item  reference  by  calling 
GetMovi  eUserData  (1-499),  GetTrackUserData  (1-546),  or  GetMedi  a  User  Data 
(1-456). 

data 

A  handle  to  the  data  to  be  added  to  the  user  data  list. 
udType 

The  type  that  is  to  be  assigned  to  the  new  item. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 
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Discussion 

You  specify  the  user  data  list,  the  data  to  be  added,  and  the  data's  type  value. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  User  Data"  (V-2743) 

Related  Java  Methods 

qui  cktime .  std  .movi  es  .medi  a.UserData.addDataO 


AddUserDataT  ext 


Places  language-tagged  text  into  an  item  in  a  user  data  list. 

OSErr  AddUserDataText  ( 

UserData  theUserData, 

Handle  data, 

OSType  udType, 

long  index, 

short  itlRegionTag  ); 

theUserData 

The  user  data  list  for  this  operation.  You  obtain  this  list  reference  by  calling 
GetMovi  eUserData  (1-499),  GetTrackUserData  (1-546),  or  GetMedi  aUserData 
(1-456). 

data 

A  handle  to  the  data  to  be  added  to  the  user  data  list. 
udType 

The  type  that  is  to  be  assigned  to  the  new  item, 
i  ndex 

The  item  to  which  the  text  is  to  be  added.  This  parameter  must  specify  an  item 
in  the  user  data  list  identified  by  theUserData. 
i tl Regi onTag 

The  region  code  of  the  text  to  be  added.  If  there  is  already  text  with  this  region 
code  in  the  item,  the  function  replaces  the  existing  text  with  the  data  specified 
by  the  data  parameter.  See  Inside  Macintosh:  Text  (listed  in  the  bibliography)  for 
more  information  about  language  and  region  codes. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
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(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

You  specify  the  user  data  list  and  item,  the  data  to  be  added,  the  data's  type  value, 
and  the  language  code  of  the  data. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  User  Data"  (V-2743) 

Related  Java  Methods 

qu i c kti me. std. mo vies. media. User Data . addText ( ) 


AlignScreenRect 


Aligns  a  specified  rectangle  to  the  strictest  screen  that  the  rectangle  intersects. 

void  AlignScreenRect  ( 

Rect  *rp, 

ICMA1 i gnmentProcRecordPtr  al i gnmentProc  ); 


rp 

A  pointer  to  a  rectangle  defined  in  global  screen  coordinates, 
al i gnmentProc 

Points  to  your  own  alignment  behavior  function.  Set  this  parameter  to  N I L  to 
use  the  standard  behavior. 

Discussion 

For  a  specification  of  your  alignment  function,  see  ICMA1  i  gnmentProc  (III— 2086). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Aligning  Windows"  (V-2797) 

See  Also 

The  callback  function  My  ICMA1  i  gnmentProc  is  described  in  ICMA1  i  gnmentProc. 
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AlignWindow 


Moves  a  specified  window  to  the  nearest  optimal  alignment  position. 


voi d  A1 i gnWi ndow  ( 

WindowPtr  wp. 

Boolean  front, 

const  Rect  *al i gnmentRect , 

ICMA1 i gnmentProcRecordPtr  al i gnmentProc  ); 


wp 

Points  to  the  window  to  be  aligned, 
front 

The  frontmost  window.  If  the  front  parameter  is  TRUE  and  the  window 
specified  in  the  wp  parameter  isn't  the  active  window,  Al  i  gnWi  ndow  makes  it  the 
active  window. 

al i gnmentRect 

A  pointer  to  a  rectangle  in  window  coordinates  that  allows  you  to  align  the 
window  to  a  rectangle  within  the  window.  Set  this  parameter  to  N I L  to  align 
using  the  bounds  of  the  window, 
al i gnmentProc 

Points  to  a  function  that  allows  you  to  provide  your  own  alignment  behavior. 
Set  this  parameter  to  N I L  to  use  the  standard  behavior. 

Discussion 

For  a  specification  of  your  alignment  function,  see  ICMA1  i  gnmentProc  (III— 2086). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Aligning  Windows"  (V-2797) 

See  Also 

The  callback  function  My ICMA1  i  gnmentProc  is  described  in  ICMA1  i  gnmentProc. 


AudioGetBass 

Deprecated. 

ComponentResul t  AudioGetBass  ( 
Componentlnstance  ac. 
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AudioGetlnfo 


short  whi chChannel  , 

short  *bass  ) ; 


Version  Notes 

This  function  is  listed  for  historical  purposes  only.  It  may  be  unsupported  or 
removed  in  future  versions  of  QuickTime.  Macintosh  Note:  Not  available  in 
CarbonLib,  but  available  when  SoundLib  3.0  or  later  is  installed. 

Programming  Info 

C  interface  file:  Sound .  h 


AudioGetlnfo 


Deprecated. 

ComponentResul t  AudioGetlnfo  ( 
Componentlnstance  ac, 

Audi olnfoPtr  i nfo  ) ; 


Version  Notes 

This  function  is  listed  for  historical  purposes  only.  It  may  be  unsupported  or 
removed  in  future  versions  of  QuickTime.  Macintosh  Note:  Not  available  in 
CarbonLib,  but  available  when  SoundLib  3.0  or  later  is  installed. 

Programming  Info 

C  interface  file:  Sound .  h 


AudioGetMute 


Deprecated. 

ComponentResul t  AudioGetMute  ( 
Componentlnstance  ac, 

short  whi chChannel  , 

short  *mute  ) ; 


Version  Notes 

This  function  is  listed  for  historical  purposes  only.  It  may  be  unsupported  or 
removed  in  future  versions  of  QuickTime.  Macintosh  Note:  Not  available  in 
CarbonLib,  but  available  when  SoundLib  3.0  or  later  is  installed. 

Programming  Info 

C  interface  file:  Sound .  h 
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AudioGetOutputDevice 


Deprecated. 

ComponentResul t  AudioGetOutputDevice  ( 
Componentlnstance  ac. 

Component  *outputDevi ce  ); 


Version  Notes 

This  function  is  listed  for  historical  purposes  only.  It  may  be  unsupported  or 
removed  in  future  versions  of  QuickTime.  Macintosh  Note:  Not  available  in 
CarbonLib,  but  available  when  SoundLib  3.0  or  later  is  installed. 

Programming  Info 

C  interface  file:  Sound .  h 


AudioGetT  reble 


Deprecated. 

ComponentResul t  Audi oGetTrebl e  ( 
Componentlnstance  ac, 

short  whi chChannel , 

short  *Treble  ); 


Version  Notes 

This  function  is  listed  for  historical  purposes  only.  It  may  be  unsupported  or 
removed  in  future  versions  of  QuickTime.  Macintosh  Note:  Not  available  in 
CarbonLib,  but  available  when  SoundLib  3.0  or  later  is  installed. 

Programming  Info 

C  interface  file:  Sound .  h 


AudioGetVolume 


Deprecated. 


ComponentResul t  AudioGetVolume  ( 
Componentlnstance  ac, 

short  whichChannel 

ShortFixed  *volume  ); 
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Version  Notes 

This  function  is  listed  for  historical  purposes  only.  It  may  be  unsupported  or 
removed  in  future  versions  of  QuickTime.  Macintosh  Note:  Not  available  in 
CarbonLib,  but  available  when  SoundLib  3.0  or  later  is  installed. 

Programming  Info 

C  interface  file:  Sound .  h 


AudioMuteOnEvent 


Deprecated. 

ComponentResul t  AudioMuteOnEvent  ( 
Componentlnstance  ac, 

short  muteOnEvent  ) ; 


Version  Notes 

This  function  is  listed  for  historical  purposes  only.  It  may  be  unsupported  or 
removed  in  future  versions  of  QuickTime.  Macintosh  Note:  Not  available  in 
CarbonLib,  but  available  when  SoundLib  3.0  or  later  is  installed. 

Programming  Info 

C  interface  file:  Sound .  h 


AudioSetBass 


Deprecated. 

ComponentResul t  AudioSetBass  ( 
Componentlnstance  ac, 

short  whi chChannel  , 

short  bass  ) ; 


Version  Notes 

This  function  is  listed  for  historical  purposes  only.  It  may  be  unsupported  or 
removed  in  future  versions  of  QuickTime.  Macintosh  Note:  Not  available  in 
CarbonLib,  but  available  when  SoundLib  3.0  or  later  is  installed. 

Programming  Info 

C  interface  file:  Sound .  h 
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AudioSetMute 


Deprecated. 

ComponentResul t  AudioSetMute  ( 
Componentlnstance  ac, 

short  whi chChannel  , 

short  mute  ); 


Version  Notes 

This  function  is  listed  for  historical  purposes  only.  It  may  be  unsupported  or 
removed  in  future  versions  of  QuickTime.  Macintosh  Note:  Not  available  in 
CarbonLib,  but  available  when  SoundLib  3.0  or  later  is  installed. 

Programming  Info 

C  interface  file:  Sound .  h 


AudioSetToDef  aults 

Deprecated. 

ComponentResul t  Audi oSetToDefaul ts  ( 
Componentlnstance  ac  ); 


Version  Notes 

This  function  is  listed  for  historical  purposes  only.  It  may  be  unsupported  or 
removed  in  future  versions  of  QuickTime.  Macintosh  Note:  Not  available  in 
CarbonLib,  but  available  when  SoundLib  3.0  or  later  is  installed. 

Programming  Info 

C  interface  file:  Sound .  h 


AudioSetTreble 


Deprecated. 

ComponentResul t  AudioSetTreble  ( 
Componentlnstance  ac, 

short  whi chChannel , 

short  Treble  ); 
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Version  Notes 

This  function  is  listed  for  historical  purposes  only.  It  may  be  unsupported  or 
removed  in  future  versions  of  QuickTime.  Macintosh  Note:  Not  available  in 
CarbonLib,  but  available  when  SoundLib  3.0  or  later  is  installed. 

Programming  Info 

C  interface  file:  Sound .  h 


AudioSetVolume 


Deprecated. 

ComponentResul t  AudioSetVolume  ( 
Componentlnstance  ac, 

short  whi chChannel  , 

ShortFi xed  vol ume  ) ; 


Version  Notes 

This  function  is  listed  for  historical  purposes  only.  It  may  be  unsupported  or 
removed  in  future  versions  of  QuickTime.  Macintosh  Note:  Not  available  in 
CarbonLib,  but  available  when  SoundLib  3.0  or  later  is  installed. 

Programming  Info 

C  interface  file:  Sound .  h 


B 


BeginFullScreen 


Begins  full-screen  mode  for  a  specified  monitor. 


■r  BeginFul 

IScreen  ( 

Ptr 

*restoreState , 

GDHandl e 

whi chGD , 

short 

*desi redWi dth , 

short 

*desi  redhlei  ght , 

Wi ndowPtr 

*newWi ndow , 

RGBCol or 

*eraseCol or , 

1  ong 

f 1 ags  ) ; 
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restoreState 

On  exit,  a  pointer  to  a  block  of  private  state  data  that  contains  information  on 
how  to  return  from  full-screen  mode.  This  value  is  passed  to  EndFull  Screen 
(1-314)  to  enable  it  to  return  the  monitor  to  its  previous  state, 
whi chGD 

A  handle  to  the  graphics  device  to  put  into  full-screen  mode.  Set  this  parameter 
to  N I L  to  select  the  main  screen. 

desi redWi dth 

On  entry,  a  pointer  to  a  short  integer  that  contains  the  desired  width,  in  pixels, 
of  the  images  to  be  displayed.  On  exit,  that  short  integer  is  set  to  the  actual 
number  of  pixels  that  can  be  displayed  horizontally.  Set  this  parameter  to  0  to 
leave  the  width  of  the  display  unchanged, 
desi redHei ght 

On  entry,  a  pointer  to  a  short  integer  that  contains  the  desired  height,  in  pixels, 
of  the  images  to  be  displayed.  On  exit,  that  short  integer  is  set  to  the  actual 
number  of  pixels  that  can  be  displayed  vertically.  Set  this  parameter  to  0  to 
leave  the  height  of  the  display  unchanged. 
newWi ndow 

On  entry,  a  window-creation  value.  If  this  parameter  is  NIL,  no  window  is 
created  for  you.  If  this  parameter  has  any  other  value,  Begi  nFul  1  Screen  creates 
a  new  window  that  is  large  enough  to  fill  the  entire  screen  and  returns  a  pointer 
to  that  window  in  this  parameter.  You  should  not  dispose  of  that  window 
yourself;  instead,  EndFul  1  Screen  (1-314)  will  do  so. 

eraseCol or 

The  color  to  use  when  erasing  the  full-screen  window  created  by 
Begi  nFul  1  Screen  if  newWi  ndow  is  not  NI L  on  entry.  If  this  parameter  is  NIL, 
BeginFullScreen  uses  black  when  initially  erasing  the  window's  content  area, 
fl  ags 

A  set  of  bit  flags  (see  below)  that  control  certain  aspects  of  the  full-screen  mode. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

flags  Constants 

full  Screen Hi deCursor 

If  this  flag  is  set,  Begi  nFul  1  Screen  hides  the  cursor.  This  is  useful  if  you  are  going 
to  play  a  QuickTime  movie  and  don't  want  the  cursor  to  be  visible  over  the 
movie. 
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fullScreenAl low Events 

If  this  flag  is  set,  your  application  intends  to  allow  other  applications  to  run 
(with  Macintosh,  by  calling  Wai  tNextEvent  to  grant  them  processing  time).  In 
this  case,  BeginFullScreen  does  not  change  the  monitor  resolution,  because 
other  applications  might  depend  on  the  current  resolution, 
full  Screen DontChangeMenuBar 

If  this  flag  is  set,  BeginFul  1  Screen  does  not  hide  the  menu  bar.  This  is  useful  if 
you  want  to  change  the  resolution  of  the  monitor  but  still  need  to  allow  the  user 
to  access  the  menu  bar. 

fullScreenPreflightSize 

If  this  flag  is  set,  BeginFullScreen  doesn't  change  any  monitor  settings,  but 
returns  the  actual  height  and  width  that  it  would  use  if  this  bit  were  not  set.  This 
allows  applications  to  test  for  the  availability  of  a  monitor  setting  without 
having  to  switch  to  it. 

Discussion 

This  function  returns,  in  the  restoreState  parameter,  a  pointer  to  a  block  of  private 
state  information  that  indicates  how  to  return  from  full-screen  mode.  You  pass  that 
pointer  as  a  parameter  to  the  EndFul  1  Screen  (1-314)  function.  The  following  sample 
code  contains  functions  that  illustrate  how  to  play  a  QuickTime  movie  full  screen. 
It  prompts  the  user  for  a  movie,  opens  that  movie,  configures  it  to  play  full  screen, 
associates  a  movie  controller,  and  lets  the  controller  handle  events.  Your  application 
would  call  QTFul  1  Screen_EventFoopActi  on  in  its  event  loop  (on  the  Mac  OS)  or  when 
it  gets  idle  events  (on  Windows). 


enum  { 

fullScreenHi deCursor 
fullScreenAl low Events 
full  Screen DontChangeMenuBar 
fullScreenPreflightSize 


=  IF  «  0. 
=  1L  «  1. 
=  IF  «  2. 
=  IF  «  3 


//  QTFul 1 Screen_Pl ayOnFul 1  Screen 

//  Prompt  the  user  for  a  movie  and  play  it  full  screen. 
OSErr  QTFul 1 Screen_Pl ayOnFul 1  Screen  (void) 

{ 


FSSpec 
Movi  e 
short 

SFTypeLi  st 
StandardFi 1 eReply 


my FSSpec ; 
myMovie  =  NIF; 
myRefNum  =  0; 

myTypeFist  =  (Movi eFi 1 eType ,  0,  0,  0); 
myReply ; 
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1  ong 
OSErr 


myFlags  =  ful 1 ScreenDontChangeMenuBar 

|  f ul 1 ScreenAl 1 owEvents ; 


my Err  =  noErr; 


StandardGetFi 1 ePrevi ew( NI L,  1,  myTypeList,  &myReply); 
if  ( ImyReply.sfGood) 
goto  bail  ; 


//  make  an  FSSpec  record 

FSMakeFSSpec(myRep1y . sf Fi 1 e . vRef Num,  my Reply. sfFile.parlD, 

my Reply.sf File. name,  &my FSSpec) ; 

myErr  =  OpenMovi eFi 1 e(&myFSSpec ,  &myRefNum,  fsRdPerm); 
if  (myErr  !=  noErr) 
goto  bail  ; 


//  now  fetch  the  first  movie  from  the  file 

myErr  =  NewMovi eFromFi 1 e(&myMovi e ,  myRefNum,  NIL,  NIL, 

newMovi eActi ve ,  NIL); 

if  (myErr  !=  noErr) 
goto  bail  ; 


Cl  oseMovi eFi 1 e(myRef Num) ; 


//  set  up  for  full-screen  display 

myErr  =  Begi nFul 1 Screen(&gRestoreState ,  NIL,  0,  0, 

&g Fu 1 1 ScreenWi ndow,  NIL,  myFlags); 


#if  TARGET_0S_WIN32 

//  on  Windows,  set  a  window  procedure  for  the  new  window 
//  and  associate  a  port  with  that  window 

QTMLSetWi ndowWndProc(gFul 1 ScreenWi ndow,  QTFul 1 Screen_Handl eMes sages ) ; 
CreatePortAssoci ati on(GetPortNati veWi ndow(gFul 1 ScreenWi ndow),  NIL,  OL); 
#endi  f 

SetMovi eGWorl d(myMovi e,  (CGrafPtr)gFull ScreenWi ndow, 

GetGWorl dDevi ce( (CGraf Ptr)gFul 1 ScreenWi ndow) ) ; 
SetMovi eBox(myMovi e ,  &g Fu 1 1 ScreenWi ndow->portRect ) ; 

//  create  the  movie  controller 

gMC  =  NewMovi eControl 1 er(myMovi e ,  &g Fu 1 1 ScreenWi ndow->portRect ,  0); 
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Version  Notes 

The  Macintosh  human  interface  guidelines  suggest  that  the  menu  bar  must  always 
be  present,  and  that  information  must  always  appear  in  windows.  However,  many 
multimedia  applications  have  chosen  to  change  the  look  and  feel  of  the  interface 
based  on  their  needs.  The  number  of  details  to  keep  track  of  when  doing  this 
continues  to  increase.  To  help  solve  this  problem,  QuickTime  2.1  added  functions  to 
put  a  graphics  device  into  full  screen  mode.  The  key  elements  to  displaying  full 
screen  movies  are  the  calls  BeginFul  1  Screen  and  EndFul  1  Screen,  introduced  in 
QuickTime  2.5. 

Programming  Info 

C  interface  file:  Movi es .  h 

Programming  summary:  "Using  the  Full  Screen"  (V-2717) 

Related  Java  Methods 

quicktime.std.movies.FullScreen.getMainScreenSizet), 
quicktime.std.movies.FullScreen.getScreenSizet), 
qui cktime. std .movi es . Ful 1  Screen . prefl i ghtSi ze( ) , 
qui ckti me. std .movi es . Ful 1  Screen . begi  n( ) 


See  Also 

See  EndFul  1  Screen  (1-314). 


BeginMediaEdits 

Starts  a  media-editing  session. 

OSErr  BeginMediaEdits  ( 

Medi a  theMedi a  ) ; 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetT rackMedi  a  (1-535). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

Use  EndMedi  a  Ed i  ts  (1-335)  to  end  a  media-editing  session.  You  must  call 
Begi  nMedi  aEdi  ts  before  you  add  samples  to  a  media  with  the  AddMedi  aSampl  e  (1-27) 
function.  You  must  also  call  Begi  nMedi  aEdi  ts  before  calling  InsertTrackSegment 
(11-764)  if  you  wish  InsertT rackSegment  to  copy  media  samples  instead  of  copying 
the  segment  by  reference. 
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//  BeginMediaEdits  coding  example 
//  See  “Discovering  QuickTime,”  page  89 
void  CreateMyVideoTrack  (Movie  movie) 

{ 

Track  track; 

Media  media; 

Rect  rect  =  {0,  0,  100,  320}; 

track  =  NewMovi eTrack(movi e , 

FixRati  o(  rect .  ri  ght ,  1), 

FixRati o( rect . bottom,  1), 
kNoVol ume) ; 

media  =  NewTrackMedia(track, 

Vi deoMedi aType , 

600,  //  video  time  scale 

NIL,  NIL); 

Begi nMedi a  Ed i ts (medi a ) ; 

MyAddVi deoSampl esToMedi a (medi a ,  &rect ) ; 

EndMedi a  Ed i ts (medi a ) ; 

InsertMedi aIntoTrack(track, 

0, 

0, 

GetMedi aDurati on(medi a) , 
kFixl) ; 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 
Programming  summary:  "Adding  Samples  to  Media  Structures"  (V-2752) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Medi a . begi nEdi ts ( ) 

See  Also 

See  InsertTrackSegment  (11-764). 


//  assemble  data 

//  track  start  time 
//  media  start  time 

//  normal  speed 
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CallComponent 


Invokes  a  specified  function  of  your  component  with  the  parameters  originally 
provided  by  the  application  that  called  your  component. 

ComponentResul t  CallComponent  ( 

Componentlnstance  ci  , 

ComponentParameters  *cp  ); 


ci 

A  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

cp 

A  pointer  to  the  ComponentParameters  (IV-2216)  record  that  your  component 
received  from  the  Component  Manager. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 


CallComponentCanDo 


Calls  a  component  directly  to  query  its  capabilities. 

ComponentResul t  CallComponentCanDo  ( 
Componentlnstance  ci  , 
short  ftnNumber  ) ; 


ci 

A  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 
ftnNumber 

A  request  code  value.  See  Inside  Macintosh:  QuickTime  Components  (listed  in  the 
bibliography)  for  information  about  the  request  codes  supported  by  the 


1-58 


Inside  QuickTime:  Functions  A-H 


CallComponentClose 


QuickTime  components  supplied  by  Apple.  For  other  components,  see  their 
developer's  documentation. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 


CallComponentClose 


Calls  a  component  directly  to  terminate  your  application's  access  to  it. 

ComponentResul t  CallComponentClose  ( 

Componentlnstance  ci  , 

Componentlnstance  self  ); 


ci 

A  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

self 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 


CallComponentDispatch 

Replaces  Cal  1  Component  (1-58)  for  Mac  OS  9  and  later. 

ComponentResul t  CallComponentDispatch  ( 
ComponentParameters  *cp  ); 


A  pointer  to  the  ComponentParameters  (IV-2216)  record  that  your  component 
received  from  the  Component  Manager. 
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function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Components .  h 

CallComponentExecuteW  ired  Action 

Undocumented 

ComponentResul t  Cal  1 ComponentExecuteWi redActi on  ( 

Componentlnstance  ci  , 

QTAtomContai ner  actionContainer, 

QTAtom  actionAtom, 

QTCustomActi onTargetPtr  target, 

QTEventRecordPtr  event  ); 

ci 

A  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

acti onContai ner 

A  QT  atom  container  that  contains  the  action  atom, 
acti onAtom 

The  action  atom  for  this  wired  action, 
target 

A  pointer  to  a  QTCustomActi  onTargetRecord  (IV-2351)  structure, 
event 

A  pointer  to  a  QTEventRecord  (IV-2353)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


1-60 


Inside  QuickTime:  Functions  A-H 


CallComponentFunction 


CallComponentFunction 

Invokes  a  specified  function  of  your  component  with  the  parameters  originally 
provided  by  the  application  that  called  your  component. 

long  CallComponentFunction  ( 

ComponentParameters  *params, 

ComponentFuncti onUPP  func  ); 

params 

A  pointer  to  the  ComponentParameters  (IV-2216)  record  that  your  component 
received  from  the  Component  Manager. 

func 

The  address  of  the  function  that  is  to  handle  the  request.  The  Component 
Manager  calls  the  routine  referred  to  by  the  func  parameter  as  a  Pascal  function 
with  the  parameters  that  were  originally  provided  by  the  application.  These 
parameters  are  preceded  by  a  handle  to  the  memory  associated  with  the  current 
connection.  The  routine  referred  to  by  the  func  parameter  must  return  a 
function  result  of  type  ComponentResul  t  (a  long  integer)  indicating  the  success 
or  the  failure  of  the  operation. 

function  result  A  ComponentResul  t  value  that  indicates  the  success  or  the  failure  of 
the  operation. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 


CallComponentFunctionWithStorage 


Invokes  a  specified  function  of  your  component  with  the  parameters  originally 
provided  by  the  application  that  called  your  component  and  provides  a  handle  to 
the  memory  associated  with  the  current  connection. 


long  Cal  1 ComponentFuncti onWi thStorage  ( 
H  a  n  d 1 e  storage, 

ComponentParameters  *params, 

ComponentFuncti onUPP  func  ); 
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storage 

A  handle  to  the  memory  associated  with  the  current  connection.  The 
Component  Manager  provides  this  handle  to  your  component  along  with  the 
request, 
params 

A  pointer  to  the  ComponentParameters  (IV-2216)  record  that  your  component 
received  from  the  Component  Manager. 

f  unc 

The  address  of  the  function  that  is  to  handle  the  request.  The  Component 
Manager  calls  the  routine  referred  to  by  the  tunc  parameter  as  a  Pascal  function 
with  the  parameters  that  were  originally  provided  by  the  application.  These 
parameters  are  preceded  by  a  handle  to  the  memory  associated  with  the  current 
connection.  The  routine  referred  to  by  the  f  unc  parameter  must  return  a 
function  result  of  type  ComponentResul  t  (a  long  integer)  indicating  the  success 
or  the  failure  of  the  operation. 

function  result  A  ComponentResul  t  value  that  indicates  the  success  or  the  failure  of 
the  operation. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 


CallComponentFunctionWithStorageProcInfo 


Invokes  a  specified  function  of  your  component  with  the  parameters  originally 
provided  by  the  application  that  called  it;  used  when  your  component  links  with 
Components  Interfaces  Li b. 


long  Call  Component Functi onWithStorageProcInfo 
Handle  storage, 

ComponentParameters  *params, 

ProcPtr  func, 

ProcInfoType  funcProcInfo  ); 


( 


storage 

A  handle  to  the  memory  associated  with  the  current  connection.  The 
Component  Manager  provides  this  handle  to  your  component  along  with  the 
request. 
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params 

A  pointer  to  the  ComponentParameters  (IV-2216)  record  that  your  component 
received  from  the  Component  Manager. 

f  unc 

The  address  of  the  function  that  is  to  handle  the  request.  The  Component 
Manager  calls  the  routine  referred  to  by  the  f  unc  parameter  as  a  Pascal  function 
with  the  parameters  that  were  originally  provided  by  the  application.  These 
parameters  are  preceded  by  a  handle  to  the  memory  associated  with  the  current 
connection.  The  routine  referred  to  by  the  f  unc  parameter  must  return  a 
function  result  of  type  ComponentResul  t  (a  long  integer)  indicating  the  success 
or  the  failure  of  the  operation.  Note  that  for  PowerPC  code,  the  f  unc  parameter 
should  still  point  to  the  routine  itself,  not  to  a  Routi  neDescri  ptor  or  Universal 
Procedure  Pointer. 
funcProcInfo 

The  procedure  information  for  the  routine  referred  to  by  the  f  unc  parameter. 
See  Inside  Macintosh:  PowerPC  System  Softivare  (listed  in  the  bibliography)  for 
information  on  procedure  information  data. 

function  result  A  ComponentResul  t  value  that  indicates  the  success  or  the  failure  of 
the  operation. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 


CallComponentGetMPWorkFunction 


Undocumented 

ComponentResul t  CallComponentGetMPWorkFunction  ( 
Componentlnstance  ci  , 

ComponentMPWorkFuncti  onllPP  *workFuncti  on  , 

void  **refCon  ); 


A  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
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workFuncti on 

A  ComponentMPWorkFuncti onProc  (III — 2077)  callback. 
refCon 

A  reference  constant  to  be  passed  to  your  callback.  Use  this  parameter  to  point 
to  a  data  structure  containing  any  information  your  function  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 


CallComponentGetPublicResource 

Undocumented 

ComponentResu 
Component 
OSType 
short 
H  a  n  d  1  e 

ci 

A  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
resourceType 

Undocumented 

resourcelD 

A  resource  ID. 
resource 

On  return,  pointer  to  a  handle  to  the  resource. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Components .  h 


It  CallComponentGetPublicResource  ( 
Instance  ci , 

resourceType , 
resourcelD , 

*resource  ) ; 
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CallComponentOpen 


Calls  a  component  directly  to  let  an  application  gain  access  to  its  services. 

ComponentResul t  CallComponentOpen  ( 

Componentlnstance  ci  , 

Componentlnstance  self  ); 


ci 

A  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

self 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 


CallComponentRegister 

Calls  a  component  directly  to  register  it. 

ComponentResul t  CallComponentRegister  ( 

Componentlnstance  ci  ); 

ci 

A  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 
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CallComponentT  arget 


Calls  a  component  directly  to  set  its  target. 

ComponentResul t  CallComponentTarget  ( 
Componentlnstance  ci  , 

Componentlnstance  target  ); 


ci 

A  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

target 

The  component  instance  of  the  component  issuing  the  target  request. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 


CallComponentUnregister 

Calls  a  component  directly  to  unregister  it. 

ComponentResul t  CallComponentUnregister  ( 

Componentlnstance  ci  ); 

ci 

A  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 
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CallComponentV  ersion 

Calls  a  component  directly  to  retrieve  its  version  number. 

ComponentResul t  Cal  1 ComponentVersi on  ( 

Componentlnstance  ci  ); 

ci 

A  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef aul tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 


CallMeWhen 


Schedules  a  callback  event. 


OSErr  CallMeWhen  ( 
QTCal 1  Back 
QTCal 1 BackUPP 
1  ong 
1  ong 
1  ong 
1  ong 


cb , 

cal  1 BackProc , 
refCon , 
paraml , 
param2 , 
param3  ); 


cb 

The  callback  event  for  the  operation.  You  obtain  this  identifier  from 
NewCal  1  Back  (11-1053). 

cal  1 BackProc 

Points  to  your  callback  function,  described  in  QTCal  1  BackProc  (III— 2124). 
refCon 

A  reference  constant  to  be  passed  to  your  callback.  Use  this  parameter  to  point 
to  a  data  structure  containing  any  information  your  function  needs, 
paraml 

Contains  scheduling  information.  The  Movie  Toolbox  interprets  this  parameter 
based  on  the  value  of  the  cbType  parameter  to  NewCal  1  Back  (11-1053).  If  cbType  is 
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set  to  call  BackAtT  i  me,  the  paraml  parameter  contains  flags  (see  below) 
indicating  when  to  invoke  your  callback  function  for  this  callback  event.  If  the 
cbType  parameter  is  set  to  cal  1  BackAtRate,  paraml  contains  flags  (see below) 
indicating  when  to  invoke  your  callback  function  for  this  event.  Be  sure  to  set 
unused  flags  to  0. 

param2 

Contains  scheduling  information.  The  Movie  Toolbox  interprets  this  parameter 
based  on  the  value  of  the  cbType  parameter  to  NewCal  1  Back  (11-1053).  If  cbType  is 
set  to  call  BackAtT  i  me,  the  param2  parameter  contains  the  time  value  at  which 
your  callback  function  is  to  be  invoked  for  this  event.  The  paraml  parameter 
contains  flags  affecting  when  the  Movie  Toolbox  calls  your  function.  If  cbType 
is  set  to  call  BackAtRate,  the  param2  parameter  contains  the  rate  value  at  which 
your  callback  function  is  to  be  invoked  for  this  event.  The  paraml  parameter 
contains  flags  affecting  when  the  Movie  Toolbox  calls  your  function. 

param3 

The  time  scale  in  which  to  interpret  the  time  value  that  is  stored  in  pa  ram3  if 
cbType  is  set  to  call  BackAtT  i  me. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

callBackAtTime  Constants 

triggerTimeFwd 

Indicates  that  your  callback  function  should  be  called  at  the  time  specified  by 
pa  ram2  only  when  time  is  moving  forward  (positive  rate).  The  value  of  this  flag 
is  0x0001. 

triggerTimeBwd 

Indicates  that  your  callback  function  should  be  called  at  the  time  specified  by 
pa  ram2  only  when  time  is  moving  backward  (negative  rate).  The  value  of  this 
flag  is  0x0002. 

triggerTimeEither 

Indicates  that  your  callback  function  should  be  called  at  the  time  specified  by 
pa  ram2  without  regard  to  direction,  but  the  rate  must  be  nonzero.  The  value  of 
this  flag  is  0x0003. 

callBackAtRate  Constants 

tri ggerRateChange 

Indicates  that  your  callback  function  should  be  called  whenever  the  rate 
changes.  The  value  of  this  flag  is  0x0000. 
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tri  ggerRateLT 

Indicates  that  your  callback  function  should  be  called  when  the  rate  changes  to 
a  value  less  than  that  specified  by  pa  ram 2.  The  value  of  this  flag  is  0x0004. 
tri ggerRateGT 

Indicates  that  your  callback  function  should  be  called  when  the  rate  changes  to 
a  value  greater  than  that  specified  by  pa  ram 2.  The  value  of  this  flag  is  0x0008. 

tri ggerRateEqual 

Indicates  that  your  callback  function  should  be  called  when  the  rate  changes  to 
a  value  equal  to  that  specified  by  param2.  The  value  of  this  flag  is  0x0010. 
tri  ggerRateLTE 

Indicates  that  your  callback  function  should  be  called  when  the  rate  changes  to 
a  value  that  is  less  than  or  equal  to  that  specified  by  pa  ram2.  The  value  of  this 
flag  is  0x0014. 
tri ggerRateGTE 

Indicates  that  your  callback  function  should  be  called  when  the  rate  changes  to 
a  value  that  is  greater  than  or  equal  to  that  specified  by  pa  ram2.  The  value  of  this 
flag  is  0x0018. 

tri ggerRateNot Equal 

Indicates  that  your  callback  function  should  be  called  when  the  rate  changes  to 
a  value  that  is  not  equal  to  that  specified  by  pa  ram2.  The  value  of  this  flag  is 
0x0010. 


Discussion 

You  can  call  this  function  from  your  callback  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Time  Base  Callback  Functions"  (V-2763) 

Related  Java  Methods 

qui cktime . std . cl ocks . RateCal IBack.callMeWhenO, 
qui cktime . std . cl ocks . Ti meCal 1  Back. cal  1 MeWhen( ) , 
qui  cktime .  std  .  cl  ocks  .  QTCal  1  Back,  cal  1  MeWhenO  , 
qui  cktime .  std  .  cl  ocks  .  Ti  meJumpCal  IBack.callMeWhenO, 
qui  cktime .  std  .  cl  ocks  .  Ext  remesCal  IBack.callMeWhenO 

See  Also 

For  a  specification  of  your  callback  function,  see  QTCallBackProc  (III— 2124). 


Inside  QuickTime:  Functions  A-H 


1-69 


CancelCallBack 


CancelCallBack 


Cancels  a  callback  event  before  it  executes. 

void  CancelCallBack  ( 

QTCal 1  Back  cb  )  ; 


cb 

The  callback  event  for  this  operation.  You  obtain  this  value  from  NewCal  1  Back 
(11-1053). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Time  Base  Callback  Functions"  (V-2763) 

Related  Java  Methods 

quickti me. std.clocks.QTCallBack. cancel ( ) 

See  Also 

See  NewCal  1  Back  (11-1053). 


CanQuickT  imeOpenDataRef 


Determines  whether  referenced  data  can  be  opened  using  a  graphics  importer  or 
opened  in  place  as  a  movie. 

OSErr  CanQui ckTimeOpenDataRef  ( 


Handl e 

dataRef , 

OSType 

dataRefType , 

Bool ean 

*outCanOpenWithGraphicsImporter 

Bool ean 

*outCanOpenAsMovie, 

Bool ean 

*outPreferGraphicsImporter, 

UInt32 

i  n FI  ags  ) ; 

dataRef 

A  handle  to  the  referenced  data. 
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dataRefType 

The  type  of  data  reference  pointed  to  by  data  Ref;  see  "Data  References" 
(IV-2661). 

outCa nOpen Wi thGraphi cs Importer 

Points  to  a  Boolean  that  will  be  set  to  TRUE  if  the  file  can  be  opened  using  a 
graphics  importer  and  FALSE  otherwise.  If  you  do  not  want  this  information, 
pass  NIL. 

outCanOpenAsMovi e 

Points  toaBoolean  that  will  be  set  to  TRUE  if  the  file  can  be  opened  as  a  movie 
and  FALSE  otherwise.  If  you  do  not  want  this  information,  pass  N I L. 
outPreferGraphi cs Importer 

Points  to  a  boolean  which  will  be  set  to  true  if  the  file  can  be  opened  using  a 
graphics  importer  and  opened  as  a  movie,  but,  other  factors  being  equal, 
QuickTime  prefers  a  graphics  importer.  For  example,  QuickTime  recommends 
using  a  graphics  importer  for  single-frame  GIF  files  and  opening  as  a  movie  for 
multiple-frame  GIF  files.  If  you  do  not  want  this  information,  pass  NIL.  Passing 
a  valid  pointer  disables  the  kQTDontUseDataToFi ndlmporter  and 
kQTDontLookForMovi  elmporterlfGraphicsImporterFound  flags,  if  set. 
i  n FI  ags 

Flags  (see  below)  that  modify  search  behavior.  Pass  0  for  default  behavior. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  Get  Mo  vies  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

nFlags  Constants 

kQTDontUseDataToFi ndlmporter 

Tells  QuickTime  not  to  use  the  data  in  the  file  to  help  in  the  search.  This  will 
speed  up  the  search,  especially  in  cases  where  a  negative  result  is  returned,  but 
it  will  cause  QuickTime  to  report  that  it  cannot  open  files  that  aren't  identified 
by  a  recognized  file  type  or  file  name  suffix. 
kQTDontLookForMovi e Importer  I fGra phi cs Importer Found 

Tells  QuickTime  to  short-circuit  its  search  as  soon  as  it  finds  one  way  to  open 
the  file.  Pass  this  flag  if  you  want  to  know  whether  a  file  can  be  opened  with  a 
graphics  importer  or  as  a  movie,  but  you  don't  care  which. 
kQTAl 1 owOpeni ngSti 1 1 ImagesAsMovi es 

Tells  QuickTime  to  consider  opening  still  images  as  movies.  If  this  flag  is  set,  if 
a  file  can  be  opened  using  a  graphics  importer  QuickTime  will  automatically 
say  it  can  be  opened  as  a  movie. 
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kQTAl lowImportersThatWouldCreateNewFile 

Tells  QuickTime  to  include  importers  which  would  create  new  files.  If  this  flag 
is  clear,  QuickTime  only  includes  importers  which  can  import  in  place  without 
needing  to  create  new  files. 
kQTAl 1 owAggressi velmporters 

Tells  QuickTime  to  include  movie  importers  for  file  types  like  PICT  and  TEXT 
that  aren't  traditionally  thought  of  as  movies.  If  this  flag  is  clear,  QuickTime 
excludes  these  movie  importers. 

Discussion 

This  function  determines  whether  QuickTime  can  open  a  given  area  of  data.  You 
should  pass  N I L  in  parameters  that  do  not  interest  you,  since  that  will  allow 
QuickTime  to  perform  a  faster  determination. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Movi  es .  h 


See  Also 


See  CanQui  ckTi meOpenFi  1  e  (1-72). 


CanQuickTimeOpenFile 


Determines  whether  a  file  can  be  opened  using  a  graphics  importer  or  opened  in 
place  as  a  movie. 

OSErr  CanQuickTimeOpenFile  ( 


FSSpecPtr 

f i 1 eSpec , 

OSType 

f i 1 eType , 

OSType 

f i 1 eNameExtensi on  , 

Bool ean 

*outCanOpenWithGraphicsImporter, 

Bool ean 

*outCanOpenAsMovie, 

Bool ean 

*outPreferGraphicsImporter, 

UInt32 

i  n FI  ags  ) ; 

f i 1 eSpec 

Points  to  an  FSSpec  (IV-2262)  structure  that  identifies  a  file.  To  ask  about  a 
particular  file  type  or  file  name  suffix  in  general,  pass  NIL. 
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f  i  1 eType 

Contains  the  file  type  if  already  known,  or  0  if  not  known.  If  f  1 1  eSpec  is 
provided  and  f  i  1  eType  is  0,  QuickTime  will  determine  the  file  type.  If  you  pass 
NI L  in  fi  1  eSpec  and  0  in  f  i  1  eNameExtensi on,  you  must  pass  a  file  type  here, 
f i 1 eNameExtensi on 

Contains  the  file  name  suffix  if  already  known,  or  0  if  not  known.  The  file  name 
suffix  should  be  encoded  as  an  uppercase  four  character  code  with  trailing 
spaces;  for  instance,  the  suffix  ”.png"  should  be  encoded  as  '  PNG  ' ,  or 
0x504e4720.  If  f  i  1  eSpec  is  provided  and  fi  1  eNameExtensi  on  is  0,  QuickTime  will 
examine  f  i  1  eSpec  to  determine  the  file  name  suffix.  If  you  pass  N I L  in  f  i  1  eSpec 
and  0  in  f  i  1  eType,  you  must  pass  a  file  name  suffix  here. 

outCanOpenWithGraphi cs Importer 

Points  to  a  Boolean  that  will  be  set  to  TRUE  if  the  file  can  be  opened  using  a 
graphics  importer  and  FALSE  otherwise.  If  you  do  not  want  this  information, 
pass  NIL. 

outCanOpenAsMovi e 

Points  toaBoolean  that  will  be  set  to  TRUE  if  the  file  can  be  opened  as  a  movie 
and  FALSE  otherwise.  If  you  do  not  want  this  information,  pass  N I L. 
outPreferGraphi cs Importer 

Points  to  a  boolean  which  will  be  set  to  true  if  the  file  can  be  opened  using  a 
graphics  importer  and  opened  as  a  movie,  but,  other  factors  being  equal, 
QuickTime  prefers  a  graphics  importer.  For  example,  QuickTime  recommends 
using  a  graphics  importer  for  single-frame  GIF  files  and  opening  as  a  movie  for 
multiple-frame  GIF  files.  If  you  do  not  want  this  information,  pass  NIL.  Passing 
a  valid  pointer  disables  the  kQTDontUseDataToFi ndlmporter  and 
kQTDontLookForMovi  elmporterlfGraphicsImporterFound  flags,  if  set. 

i n FI  ags 

Flags  (see  below)  that  modify  search  behavior.  Pass  0  for  default  behavior. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  Get  Mo  vies  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

nFlags  Constants 

kQTDontUseDataToFi ndlmporter 

Tells  QuickTime  not  to  use  the  data  in  the  file  to  help  in  the  search.  This  will 
speed  up  the  search,  especially  in  cases  where  a  negative  result  is  returned,  but 
it  will  cause  QuickTime  to  report  that  it  cannot  open  files  that  aren't  identified 
by  a  recognized  file  type  or  file  name  suffix. 
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kQTDontLookForMovi elmporterlfGraphicsImporterFound 

Tells  QuickTime  to  short-circuit  its  search  as  soon  as  it  finds  one  way  to  open 
the  file.  Pass  this  flag  if  you  want  to  know  whether  a  file  can  be  opened  with  a 
graphics  importer  or  as  a  movie,  but  you  don't  care  which. 
kQTAl 1 owOpeni ngSti 11  Images AsMovi  es 

Tells  QuickTime  to  consider  opening  still  images  as  movies.  If  this  flag  is  set,  if 
a  file  can  be  opened  using  a  graphics  importer  QuickTime  will  automatically 
say  it  can  be  opened  as  a  movie. 

kQTAl lowImportersThatWouldCreateNewFile 

Tells  QuickTime  to  include  importers  which  would  create  new  files.  If  this  flag 
is  clear,  QuickTime  only  includes  importers  which  can  import  in  place  without 
needing  to  create  new  files. 
kQTAl 1 owAggressi velmporters 

Tells  QuickTime  to  include  movie  importers  for  file  types  like  PICT  and  TEXT 
that  aren't  traditionally  thought  of  as  movies.  If  this  flag  is  clear,  QuickTime 
excludes  these  movie  importers. 

Discussion 

This  function  determines  whether  QuickTime  can  open  a  given  file  or,  in  general, 
files  of  a  given  type.  You  should  pass  N I L  in  parameters  that  do  not  interest  you, 
since  that  will  allow  QuickTime  to  perform  a  faster  determination. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Movi  es .  h 


See  Also 


See  CanQui ckTimeOpenDataRef  (1-70). 


CaptureComponent 


Allows  your  component  to  capture  another  component. 

Component  CaptureComponent  ( 

Component  capturedComponent , 

Component  capturi ngComponent  ); 

capturedComponent 

The  identifier  of  the  component  to  be  captured.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 
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capturi ngComponent 

The  identifier  of  your  component.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

function  result  A  new  identifier  that  your  software  can  use  to  refer  to  the  captured 
component,  or  NI L  if  the  component  identified  by  capturedComponent 
is  already  captured. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components  .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 


CDSequenceBusy 


Checks  the  status  of  an  asynchronous  compression  or  decompression  operation. 

OSErr  CDSequenceBusy  ( 

ImageSequence  seqlD  ); 

seqlD 

Contains  the  unique  sequence  identifier  that  was  returned  by 
DecompressSequenceBegi  n  (1-238)  or  CompressSequenceBegi  n  (1-119). 

function  result  If  there  is  no  asynchronous  operation  in  progress,  CDSequenceBusy 
returns  a  0  result  code.  If  there  is  an  asynchronous  operation  in 
progress,  the  result  code  is  1.  Negative  result  codes  indicate  an  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Sequences"  (V-2792) 

Related  Java  Methods 

qui ckti me . std . image . CDSequence . busy ( ) 


See  Also 


See  DecompressSequenceBegi  n  (1-238)  and  CompressSequenceBegi  n  (1-119). 
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CDSequenceChangedSourceData 


Notifies  the  compressor  that  the  image  source  data  has  changed. 

OSErr  CDSequenceChangedSourceData  ( 

ImageSequenceDataSource  sourcelD  ); 

sourcelD 

Contains  the  source  identifier  of  the  data  source. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Use  this  function  to  indicate  that  the  image  has  changed  but  the  data  pointer  to  that 
image  has  not  changed.  For  example,  if  the  data  pointer  points  to  the  base  address 
of  a  Pi  xMap  (IV-2332)  structure,  the  image  in  the  Pi  xMap  can  change,  but  the  data 
pointer  remains  constant. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Sequences"  (V-2792) 

Related  Java  Methods 

quicktime.std.image.IrriageSequenceDataSource.changedSourceDataO 


CDSequenceDisposeDataSource 

Disposes  of  a  data  source. 

OSErr  CDSequenceDisposeDataSource  ( 

ImageSequenceDataSource  sourcelD  ); 

sourcelD 

The  data  source  identifier  that  was  returned  by  the  CDSequenceNewDataSource 
(1-82)  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Use  this  function  to  dispose  of  a  data  source  created  by  the  CDSequenceNewDataSource 
(1-82)  function.  All  data  sources  are  automatically  disposed  when  the  sequence  they 
are  associated  with  is  disposed. 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Sequences"  (V-2792) 

Related  Java  Methods 

qui ckti me . std . image . ImageSequenceDataSource .  di spose( ) 


CDSequenceDisposeMemory 


Disposes  of  memory  allocated  by  the  codec. 

OSErr  CDSequenceDisposeMemory  ( 

ImageSequence  seqlD, 

Ptr  data  ); 

seqlD 

Contains  the  unique  sequence  identifier  that  was  returned  by  the 
DecompressSequenceBegi  n  (1-238)  function. 

data 

Points  to  the  previously  allocated  memory  block. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  call  this  function  to  release  memory  allocated  by  the  CDSequenceNewMemory 
(1-84)  function. 

Special  Considerations 

Do  not  call  CDSequenceDi  sposeMemory  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Sequences"  (V-2792) 


CDSequenceEnd 


Indicates  the  end  of  processing  for  an  image  sequence. 
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OSErr  CDSequenceEnd  ( 

ImageSequence  seqlD  ); 

seqlD 

Contains  the  unique  sequence  identifier  that  was  returned  by 
DecompressSequenceBegi n  (1-238)  or  CompressSequenceBegi n  (1-119). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Sequences"  (V-2792) 

See  Also 

See  DecompressSequenceBegi n  (1-238)  and  CompressSequenceBegi n  (1-119). 


CDSequenceEquivalentlmageDescription 

Reports  whether  two  image  descriptions  are  the  same. 

OSErr  CDSequenceEqui val entlmageDescri pti on  ( 

ImageSequence  seqlD, 

ImageDescri pti onHandl e  newDesc, 

Boolean  *equivalent  ); 

seqlD 

Contains  the  unique  sequence  identifier  that  was  returned  by  the 
DecompressSequenceBegi n  (1-238)  function. 

newDesc 

A  handle  to  the  ImageDescri  pti  on  (IV-2285)  structure  structure  that  describes 
the  compressed  image. 

equi val ent 

A  pointer  to  a  Bool  ean  value.  If  the  ImageDescri  pti  onHandl  e  provided  in  the 
newDesc  parameter  is  equivalent  to  the  ImageDescri  pti  on  (IV-2285)  structure 
currently  in  use  by  the  image  sequence,  this  value  is  set  to  TRUE.  If  the 
ImageDescriptionHandleis  not  equivalent,  and  therefore  a  new  image  sequence 
must  be  created  to  display  an  image  using  the  new  image  description,  this 
value  is  set  to  FALSE. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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Discussion 

This  function  allows  an  application  to  ask  whether  two  image  descriptions  are  the 
same.  If  they  are,  the  decompressor  does  not  have  to  create  a  new  image 
decompression  sequence  to  display  those  images. 

Special  Considerations 

The  Image  Compression  Manager  can  only  implement  part  of  this  function  by  itself. 
There  are  some  fields  in  the  ImageDescri  pti  on  (IV-2285)  structure  that  it  knows  are 
irrelevant  to  the  decompressor.  If  the  Image  Compression  Manager  determines  that 
there  are  differences  in  fields  that  may  be  significant  to  the  codec,  it  calls  the 
function  ImageCodec Is  ImageDescri  pti  onEqui  val  ent  to  ask  the  codec. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Sequences"  (V-2792) 

Related  Java  Methods 

qui ckti me . std . image . CDSeq uence . equi val ent ImageDescri pti on ( ) 


See  Also 

See  I mageCodecIsImageDescri  pti  onEqui  val  ent  (11-725). 


CDSequenceEquivalentlmageDescriptionS 


Undocumented 

OSErr  CDSequenceEqui val entlmageDescri pti onS  ( 

ImageSequence  seqlD, 

ImageDescri pti on Hand! e  newDesc , 

Boolean  *equi val ent , 

Boolean  *canSwitch  ); 

seqlD 

Contains  the  unique  sequence  identifier  that  was  returned  by  the 
DecompressSequenceBegi  n  (1-238)  function. 

newDesc 

A  handle  to  the  ImageDescri  pti  on  (IV-2285)  structure  structure  that  describes 
the  compressed  image. 

equi val ent 

A  pointer  to  a  Bool  ean  value.  If  the  ImageDescri  pti  onHandl  e  provided  in  the 
newDesc  parameter  is  equivalent  to  the  ImageDescri  pti  on  (IV-2285)  structure 
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currently  in  use  by  the  image  sequence,  this  value  is  set  to  TRUE.  If  the 
ImageDescriptionHandleis  not  equivalent,  and  therefore  a  new  image  sequence 
must  be  created  to  display  an  image  using  the  new  image  description,  this 
value  is  set  to  FALSE. 

canSwi tch 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


CDSequenceFlush 

Stops  a  decompression  sequence,  aborting  processing  of  any  queued  frames. 

OSErr  CDSequenceFlush  ( 

ImageSequence  seqlD  ); 

seqlD 

Contains  the  unique  sequence  identifier  that  was  returned  by 
DecompressSequenceBegi n  (1-238). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  used  to  tell  a  decompressor  component  to  stop  processing  of  any 
queued  scheduled  asynchronous  decompression.  This  is  useful  when  several 
frames  have  been  queued  for  decompression  in  the  future  and  the  application  needs 
to  suspend  playback  of  the  sequence. 

For  any  outstanding  frames,  your  application's  completion  routine,  passed  to 
Decomp ressSequenceFrameWhen  (1-245),  will  be  called  with  an  error  result  of  -1, 
indicating  that  the  frame  was  cancelled.  If  any  frames  are  currently  being 
decompressed  and  cannot  be  cancelled,  CDSequenceFl  ush  waits  until  the  frame  has 
finished  decompressing  before  returning. 

Version  Notes 

Introduced  in  QuickTime  2.0. 
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Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Sequences"  (V-2792) 

Related  Java  Methods 

qui ckti me . std . image . DSequence . f 1 ush( ) 


See  Also 

See  DecompressSequenceBegi  n  (1-238). 


CDSequenceGetDataSource 

Gets  a  data  source  for  a  decompression  sequence. 

OSErr  CDSequenceGetDataSource  ( 

ImageSequence  seqlD, 

ImageSequenceDataSource  *sourceID , 

OSType  sourceType, 

long  sourcelnputNumber  ); 

seqlD 

The  image  sequence  that  this  source  is  associated  with. 
sourcelD 

A  pointer  to  the  source  reference  identifying  this  source. 
sourceType 

A  four-character  code  describing  how  the  input  will  be  used.  This  value  is 
passed  by  CDSequenceNewDataSource  (1-82)  when  the  source  is  created. 
sourcelnputNumber 

A  value  passed  by  CDSequenceNewDataSource  (1-82)  when  the  source  is  created. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Related  Java  Methods 

qui ckti me . std . image . ImageSequenceDataSource . ImageSequenceDataSource! ) 
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CDSequencelnvalidate 

Notifies  the  Image  Compression  Manager  that  the  destination  port  for  the  given 
image  decompression  sequence  has  been  invalidated. 

OSErr  CDSequencelnvalidate  ( 

ImageSequence  seqlD, 

RgnHandl e  i nval Rgn  ) ; 

seqlD 

Contains  the  unique  sequence  identifier  that  was  returned  by 
DecompressSequenceBegi n  (1-238). 

i  nval Rgn 

A  handle  to  the  region  specifying  the  invalid  portion  of  the  image. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  call  this  function  to  force  the  Image  Compression  Manager  to  redraw  the  screen 
bits  on  the  next  decompression  operation. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Sequences"  (V-2792) 

Related  Java  Methods 

qu ickti me. std.image.DSequence. invalidate!) 


See  Also 

See  DecompressSequenceBegi n  (1-238). 


CDSequenceNewDataSource 


Creates  a  new  data  source. 

( 

seqlD, 

*sourceID , 
sourceType , 
sourcelnputNumber , 
dataDescri pti on , 
transferProc , 
*refCon  ) ; 


OSErr  CDSequenceNewDataSource 
ImageSequence 
ImageSequence Da taSource 
OSType 
1  ong 
Hand! e 

ICMConvertDataFormatUPP 
voi  d 
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seqlD 

The  unique  sequence  identifier  that  was  returned  by  the 
DecompressSequenceBegi n  (1-238)  function. 
sourcelD 

Returns  the  new  data  source  identifier. 
sourceType 

A  four-character  code  describing  how  the  input  will  be  used.  This  code  is 
usually  derived  from  the  information  returned  by  the  codec.  For  example,  if  a 
mask  plane  was  passed,  this  field  might  contain  'mask'. 
sourcelnputNumber 

More  than  one  instance  of  a  given  source  type  may  exist.  The  first  occurrence 
should  have  a  source  input  number  of  1,  the  second  a  source  input  number  of 
2,  and  so  on. 
dataDescri pti on 

A  handle  to  a  data  structure  describing  the  input  data.  For  compressed  image 
data,  this  is  an  ImageDescri  pti  onHandl  e. 

transferProc 

A  routine  that  allows  the  application  to  transform  the  type  of  the  input  data  to 
the  kind  of  data  preferred  by  the  codec.  The  client  of  the  codec  passes  the  source 
data  in  the  form  most  convenient  for  it.  If  the  codec  needs  the  data  in  another 
form,  it  can  negotiate  with  the  client  or  directly  with  the  Image  Compression 
Manager  to  obtain  the  required  data  format. 
refCon 

A  reference  constant  to  be  passed  to  the  transfer  procedure.  Use  this  parameter 
to  point  to  a  data  structure  containing  any  information  your  function  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns  a  sourcelD  parameter  which  must  be  passed  to  all  other 
functions  that  reference  the  source.  All  data  sources  are  automatically  disposed 
when  the  sequence  they  are  associated  with  is  disposed. 

//  CDSequenceNewDataSource  coding  example 
//  See  “Discovering  QuickTime,”  page  309 
{ 

ImageSequenceDataSource  ISrcl  =  0; 

//  Store  a  description  of  the  first  GWorld  in  hlmageDescl 
nErr  =  Ma ke ImageDescri pti on  For Pi xMap(GetGWorl dPixMap(gWorldl), 
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&hImageDescl) ; 

//  Create  a  source  from  the  GWorld  description. 
nErr  =  CDSequenceNewDataSourcetgEffectSequencelD, 

&1 Srcl , 

‘srcA' , 

1. 

(Handle)hlmageDescl, 

NIL. 

0) ; 


//  Set  the  data  for  source  srcA  to  be  the  pixMap  of  gWorldl 
CDSequenceSetSourceDatadSrcl, 

GetPixBaseAddrtGetGWorldPixMaptgWorldl) ) , 
(**hImageDescl).dataSize); 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Sequences"  (V-2792) 

Related  Java  Methods 

quicktime.std.image.ImageSequenceDataSource.ImageSequenceDataSourceO 


See  Also 

See  DecompressSequenceBegi n  (1-238). 


CDSequenceNewMemory 


Requests  codec-allocated  memory. 


OSErr  CDSequenceNewMemory 
ImageSequence 
Ptr 
Si  ze 
1  ong 

ICMMemoryDi sposedUPP 
voi  d 


seqlD, 

*data , 
dataSi ze , 
datatlse , 
memoryGoneProc , 
*refCon  ) ; 
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seqlD 

Contains  the  unique  sequence  identifier  that  was  returned  by  the 
DecompressSequenceBegi  n  (1-238)  function. 

data 

Returns  a  pointer  to  the  allocated  memory. 
dataSi ze 

The  requested  size  of  the  data  buffer. 
dataUse 

A  code  (see  below)  that  indicates  how  the  memory  is  to  be  used.  For  example, 
the  memory  may  be  used  to  store  compressed  image  or  mask  plane  data,  or 
used  as  an  offscreen  image  buffer.  If  there  is  no  benefit  to  storing  a  particular 
kind  of  data  in  codec  memory,  the  codec  should  deny  the  request  for  the 
memory  allocation. 
memoryGoneProc 

A  pointer  to  a  callback  function  that  will  be  called  before  disposing  of  the 
memory  allocated  by  a  codec,  as  described  in  ICMMemoryDi  sposedProc  (III— 2092). 

refCon 

A  reference  constant  to  be  passed  to  your  callback.  Use  this  parameter  to  point 
to  a  data  structure  containing  any  information  your  function  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

dataUse  Constants 

0x0001 

Memory  will  be  used  for  holding  compressed  image  data. 

0x0002 

Memory  will  be  used  for  an  offscreen  image  buffer. 

Discussion 

Because  many  hardware  decompression  boards  contain  dedicated  on-board 
memory,  significant  performance  gains  can  be  realized  if  this  memory  is  used  to 
store  data  before  it  is  decompressed.  When  memory  is  allocated,  a  callback  function 
must  be  provided,  as  described  in  ICMMemoryDi  sposedProc.  The  decompressor  can 
dispose  of  all  memory  it  has  allocated  at  any  time,  but  it  calls  the  callback  routine 
before  disposing  of  the  memory.  A  callback  procedure  is  required  because  memory 
on  the  hardware  decompression  board  may  be  limited.  If  the  decompressor  cannot 
deallocate  memory  as  required,  it  is  possible  that  an  idle  decompressor  instance 
maybe  holding  a  large  amount  of  memory,  denying  those  resources  to  the  currently 
active  decompressor  instance.  When  the  callback  procedure  is  called,  the  memory 
is  still  available.  This  allows  any  pending  reads  into  the  block  to  be  canceled  before 
the  block  is  disposed.  The  decompressor  disposing  the  memory  must  ensure  that  it 
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is  not  disposing  a  block  that  it  is  currently  using  (that  is,  a  block  that  contains  the 
currently  decompressing  frame).  To  dispose  of  the  memory,  use 
CDSequenceDi sposeMemory  (1-77). 

Special  Considerations 

Decompressor  memory  must  never  be  disposed  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Sequences"  (V-2792) 

See  Also 

See  CDSequenceDi  sposeMemory  (1-77).  For  a  specification  of  your  callback  function, 
see  ICMMemoryDi sposedProc  (III — 2092). 


CDSequenceSetSourceData 


Sets  data  in  a  new  frame  to  a  specific  data  source. 

OSErr  CDSequenceSetSourceData  ( 

ImageSequenceDataSource  sourcelD, 

void  *data, 

1 ong  dataSi  ze  ) ; 

sourcelD 

Contains  the  source  identifier  of  the  data  source. 

data 

Points  to  the  data.  This  pointer  must  contain  a  32-bit  clean  address. 
dataSi ze 

The  size  of  the  data  buffer. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  called  to  set  data  in  a  new  frame  to  a  specific  source.  For  example, 
as  a  new  frame  of  compressed  data  arrives  at  a  source,  CDSequenceSetSourceData 
will  be  called. 

//  CDSequenceSetSourceData  coding  example 
//  See  “Discovering  QuickTime,”  page  309 
{ 
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ImageSequenceDataSource  ISrcl  =  0; 

//  Store  a  description  of  the  first  GWorld  in  hlmageDescl 
nErr  =  MakelmageDescriptionForPi xMap(GetGWorl dPixMap(gWorldl), 
&hImageDescl ) ; 

//  Create  a  source  from  the  GWorld  description. 
nErr  =  CDSequenceNewDataSource(gEffectSequenceID, 

&1 Srcl , 

‘srcA’ , 

1, 

(Handle)hlmageDescl, 

NIL, 

0); 


//  Set  the  data  for  source  srcA  to  be  the  pixMap  of  gWorldl 
CDSequenceSetSourceData (ISrcl, 

Get Pi xBaseAddr(GetGWorl dPixMap(gWorldl)), 
( **h Ima geDes cl ) .data  Size) ; 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Sequences"  (V-2792) 

Related  Java  Methods 

qui ckti me . std . image . ImageSequenceDataSource .set Sour ceData() 


CDSequenceSetSourceDataQueue 

Sets  a  data  queue  as  the  source  for  a  decompression  sequence. 

OSErr  CDSequenceSetSourceDataQueue  ( 

ImageSequenceDataSource  source  ID , 

QHdrPtr  dataQueue  ); 

sourcelD 

Contains  the  source  identifier  of  the  data  source. 
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dataQueue 

A  pointer  to  a  QHdr  (IV-2345)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


CDSequenceSetTimeBase 

Sets  a  time  base  for  a  decompression  sequence. 

OSErr  CDSequenceSetTimeBase  ( 

ImageSequence  seqlD, 

voi d  *base  ) ; 

seqlD 

A  unique  sequence  identifier  that  was  returned  by  CompressSequenceBegi  n 
(1-119). 

base 

A  pointer  to  the  time  base  for  this  operation.  Your  application  obtains  this  time 
base  identifier  from  NewTimeBase  (11-1119). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

When  you  run  a  visual  effect  outside  a  movie,  you  must  designate  a  time  base  that 
will  be  used  when  the  effect  is  run.  The  following  code  illustrates  this  use  of 
CDSequenceSetTimeBase: 

//  CDSequenceSetTimeBase  coding  example 
//  See  “Discovering  QuickTime,”  page  310 
timeBase  =  NewTimeBaset ) ; 

SetTimeBaseRatettimeBase,  0); 

CDSequenceSetTimeBasetgEffectSequencelD,  timeBase) ; 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 
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Related  Java  Methods 

qui ckti me . std . Image . CDSeq uence . setT imeBaseC ) 


CheckQuickT  imeRegistration 


Deprecated. 

void  CheckQuickTimeRegistration  ( 
void  *regi strati onKey , 

long  flags  ); 


Version  Notes 

This  function  is  listed  for  historical  purposes  only.  It  may  be  unsupported  or 
removed  in  future  versions  of  QuickTime. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


ClearMovieChanged 


Sets  the  movie  changed  flag  to  indicate  that  the  movie  has  not  been  changed. 

void  ClearMovieChanged  ( 

Movie  theMovie  ); 


theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Saving  Movies"  (V-2715) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . cl earChangedi ) 
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ClearMovieSelection 


Removes  the  segment  of  the  movie  that  is  defined  by  the  current  selection. 

void  ClearMovieSelection  ( 

Movi e  theMovi e  ) ; 


theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi esSti ckyError  (IM94). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "High-Level  Movie  Editing  Functions"  (V-2746) 

Related  Java  Methods 

qui cktime. std .movi es .Movi e. cl earSel ecti on( ) 


ClearMoviesStickyError 

Clears  the  sticky  error  value. 

void  ClearMoviesStickyError  (  void  ); 


Discussion 

The  Movie  Toolbox  provides  two  error  values  to  your  application:  the  current  error 
and  the  sticky  error.  The  current  error  is  the  result  code  from  the  last  Movie  Toolbox 
function;  it  is  updated  each  time  your  application  calls  a  Movie  Toolbox  function. 
The  Movie  Toolbox  saves  the  same  result  code  in  the  sticky  error  value.  Your 
application  clears  the  sticky  error  value  by  calling  Cl  earMovi  esSti  ckyError.  The 
Movie  Toolbox  then  places  the  first  nonzero  result  code  from  any  toolbox  function 
used  by  your  application  into  the  sticky  error  value.  The  Movie  Toolbox  does  not 
update  the  sticky  error  value  until  your  application  clears  it  again. 

Special  Considerations 

Many  Movie  Toolbox  functions  don't  return  an  error  as  a  function  result;  you  must 
use  GetMovi  es  Error  to  obtain  the  result  code.  Even  if  a  function  explicitly  returns  an 


1-90 


Inside  QuickTime:  Functions  A-H 


ClockCallMeWhen 


error  as  a  function  result,  that  result  is  also  available  using  GetMoviesError.  The 
Movie  Toolbox  does  not  place  a  result  code  into  the  sticky  error  value  until  the  field 
has  been  cleared.  Your  application  is  responsible  for  clearing  the  sticky  error  value 
to  ensure  that  it  does  not  contain  a  stale  result  code. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Error  Functions"  (V-2712) 

See  Also 

Your  application  calls  GetMoviesError  (1-492)  to  obtain  the  current  error  value  after 
calling  any  Movie  Toolbox  function.  Your  application  calls  GetMovi  esSti  ckyError 
(1-494)  to  obtain  the  result  code  stored  in  the  sticky  error  value. 


ClockCallMeWhen 


In  a  clock  component,  schedules  a  callback  event  for  invocation. 

ComponentResul t  ClockCallMeWhen  ( 

Componentlnstance  aClock, 

QTCallBack  cb, 

long  paraml, 

long  param2, 

long  param3  ); 

aCl ock 

Specifies  the  clock  for  the  operation.  Applications  obtain  this  identifier  from 
OpenComponent  (11-1130). 

cb 

Specifies  the  callback  event  for  the  operation.  The  Movie  Toolbox  obtains  this 
value  from  your  component's  Cl  ockNewCal  1  Back  (1-96)  function, 
paraml 

Contains  data  supplied  to  the  Movie  Toolbox  in  the  paraml  parameter  to  the 
Cal  1  MeWhen  (1-67)  function.  Your  component  interprets  this  parameter  based  on 
the  value  of  the  cal  1  BackType  parameter  to  the  Cl  ockNewCal  1  Back  (1-96) 
function.  If  cal  1  BackType  is  set  to  call  BackAtT  i  me,  the  paraml  parameter  contains 
flags  (see  below)  indicating  when  to  invoke  your  callback  function  for  this 
callback  event.  If  the  cal  1  BackType  parameter  is  set  to  cal  1  BackAtRate,  paraml 
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contains  flags  (see  below)  indicating  when  to  invoke  your  callback  function  for 
this  event. 

param2 

Contains  data  supplied  to  the  Movie  Toolbox  in  the  param2  parameter  to  the 
Call  MeWhen  (1-67)  function.  Your  component  interprets  this  parameter  based  on 
the  value  of  the  cal  1  BackType  parameter  to  the  Cl  ockNewCal  1  Back  (1-96) 
function.  If  cal  1  BackType  is  set  to  call  BackAtT  i  me,  the  param2  parameter  contains 
the  time  value  at  which  your  callback  function  is  to  be  invoked  for  this  event. 
The  pa  rami  parameter  contains  flags  affecting  when  the  Movie  Toolbox  calls 
your  function.  If  cal  1  BackType  is  set  to  cal  1  BackAtRate,  the  param2  parameter 
contains  the  rate  value  at  which  your  callback  function  is  to  be  invoked  for  this 
event. 

param3 

Contains  data  supplied  to  the  Movie  Toolbox  in  the  param3  parameter  to  the 
Call  MeWhen  (1-67)  function.  If  cbType  is  set  to  call  BackAtT  ime,  param3  contains 
the  time  scale  in  which  to  interpret  the  time  value  that  is  stored  in  pa  ram 2. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

callBackAtTime  Constants 

triggerTimeFwd 

Indicates  that  your  callback  function  should  be  called  at  the  time  specified  by 
pa  ram2  only  when  time  is  moving  forward  (positive  rate).  The  value  of  this  flag 
is  0x0001. 
triggerTimeBwd 

Indicates  that  your  callback  function  should  be  called  at  the  time  specified  by 
pa  ram2  only  when  time  is  moving  backward  (negative  rate).  The  value  of  this 
flag  is  0x0002. 

triggerTimeEither 

Indicates  that  your  callback  function  should  be  called  at  the  time  specified  by 
pa  ram2  without  regard  to  direction,  but  the  rate  must  be  nonzero.  The  value  of 
this  flag  is  0x0003. 

callBackAtRate  Constants 

tri ggerRateChange 

Indicates  that  your  callback  function  should  be  called  whenever  the  rate 
changes.  The  value  of  this  flag  is  0x0000. 
tri ggerRateLT 

Indicates  that  your  callback  function  should  be  called  when  the  rate  changes  to 
a  value  less  than  that  specified  by  param2.  The  value  of  this  flag  is  0x0004. 
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tri ggerRateGT 

Indicates  that  your  callback  function  should  be  called  when  the  rate  changes  to 
a  value  greater  than  that  specified  by  pa  ram 2.  The  value  of  this  flag  is  0x0008. 
tri ggerRateEqual 

Indicates  that  your  callback  function  should  be  called  when  the  rate  changes  to 
a  value  equal  to  that  specified  by  param2.  The  value  of  this  flag  is  0x0010. 

tri ggerRateLTE 

Indicates  that  your  callback  function  should  be  called  when  the  rate  changes  to 
a  value  that  is  less  than  or  equal  to  that  specified  by  pa  ram2.  The  value  of  this 
flag  is  0x0014. 
tri ggerRateGTE 

Indicates  that  your  callback  function  should  be  called  when  the  rate  changes  to 
a  value  that  is  greater  than  or  equal  to  that  specified  by  pa  ram2.  The  value  of  this 
flag  is  0x0018. 
tri ggerRateNot Equal 

Indicates  that  your  callback  function  should  be  called  when  the  rate  changes  to 
a  value  that  is  not  equal  to  that  specified  by  pa  ram2.  The  value  of  this  flag  is 
OxOOlC. 


Discussion 

If  your  clock  component  successfully  schedules  the  callback  event,  you  should  call 
the  AddCall  BackToTimeBase  (1-21)  function  to  add  it  to  the  list  of  callback  events  for 
the  corresponding  time  base.  If  your  component  cannot  schedule  the  callback  event, 
it  should  return  an  appropriate  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Using  Callback  Functions"  (V-2867) 

See  Also 

See  Cl  ockNewCal  1  Back  (1-96)  and  Cal  1  MeWhen  (1-67). 


ClockCancelCallBack 


In  a  clock  component,  removes  the  specified  callback  event  from  the  list  of 
scheduled  callback  events  for  a  time  base. 

ComponentResul  t  ClockCancelCallBack  ( 

Componentlnstance  aClock, 
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QTCal 1  Back  cb  )  ; 

aCl ock 

Specifies  the  clock  for  the  operation.  Your  application  obtains  this  identifier 
from  the  Component  Manager's  OpenComponent  (11-1130)  function. 

cb 

Specifies  the  callback  event  for  the  operation.  The  Movie  Toolbox  obtains  this 
value  from  your  component's  Cl  ockNewCal  1  Back  (1-96)  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

If  your  clock  component  successfully  cancels  the  callback  event,  you  should  call  the 
RemoveCal  1  BackFromTimeBase  (III— 1456)  function  so  that  the  Movie  Toolbox  can 
remove  the  callback  event  from  its  list  of  scheduled  events. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Using  Callback  Functions"  (V-2867) 


ClockDisposeCallBack 

In  a  clock  component,  disposes  of  the  memory  associated  with  the  specified 

callback  event. 

ComponentResul t  ClockDisposeCallBack  ( 

Componentlnstance  aClock, 

QTCal 1  Back  cb  ) ; 

aCl ock 

Specifies  the  clock  for  the  operation.  Applications  obtain  this  identifier  from  the 
Component  Manager's  OpenComponent  (11-1130)  function, 
cb 

Specifies  the  callback  event  for  the  operation.  The  Movie  Toolbox  obtains  this 
value  from  your  component's  Cl  ockNewCal  1  Back  (1-96)  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  should  not  call  this  function  at  interrupt  time. 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui ckTi  meComponents  .  h 

Programming  summary:  "Using  Callback  Functions"  (V-2867) 


ClockGetRate 


Fetches  the  rate  of  a  specified  clock. 

ComponentResul t  ClockGetRate  ( 

Componentlnstance  aClock, 

Fixed  *rate  ); 

aCl  ock 

Specifies  the  clock  for  the  operation.  Applications  obtain  this  identifier  from  the 
Component  Manager's  OpenComponent  (11-1130)  function. 

rate 

Pointer  to  memory  where  the  clock  rate  is  returned. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 


ClockGetTime 


Obtains  the  current  time  according  to  a  specified  clock. 

ComponentResul t  ClockGetTime  ( 

Componentlnstance  aClock, 

TimeRecord  *out  ); 

aCl ock 

Specifies  the  clock  for  the  operation.  You  obtain  this  identifier  from  the 
Component  Manager's  OpenComponent  (11-1130)  function.  See  Inside  Macintosh: 
More  Macintosh  Toolbox  (listed  in  the  bibliography)  for  details. 
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out 

A  pointer  to  a  Ti  meRecord  (IV-2486)  structure.  The  clock  component  updates 
this  structure  with  the  current  time  information.  Specifically,  the  clock 
component  sets  the  value  field  and  the  scale  field  in  the  time  structure.  Your 
clock  component  should  always  return  values  in  its  native  time  scale.  This  time 
scale  does  not  change  during  the  life  of  the  component  connection. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Getting  the  Current  Time"  (V-2867) 

Related  Java  Methods 

qui ckti me . std . cl ocks . Cl ock. getTi me( ) 


ClockNewCallBack 


In  a  clock  component,  allocates  memory  for  a  new  callback  event. 

QTCallBack  ClockNewCallBack  ( 

Componentlnstance  aClock, 

TimeBase  tb, 

short  callBackType  ); 

aCl ock 

Specifies  the  clock  for  the  operation.  Applications  obtain  this  identifier  from  the 
Component  Manager's  OpenComponent  (11-1130)  function. 

tb 

Specifies  the  callback  event's  time  base.  Typically,  your  component  does  not 
need  to  save  this  specification.  You  can  use  the  Movie  Toolbox's 
GetCal  1  BackTimeBase  (1-384)  function  to  determine  the  callback  event's  time 
base  when  it  is  invoked.  For  more  information  about  time  bases,  see  Inside 
Macintosh:  QuickTime  (listed  in  the  bibliography), 
cal  1 BackType 

Contains  a  constant  (see  below)  that  specifies  when  the  callback  event  is  to  be 
invoked.  The  value  of  this  parameter  governs  how  your  component  interprets 
the  data  supplied  in  the  pa  rami,  param2,  and  param3  parameters  to 
Cl  ockCal  1  MeWhen  (1-91). 
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ClockRateChanged 


function  result  A  pointer  to  a  Cal  1  BackRecord  (IV-2165)  structure.  Your  software  can 
pass  this  structure  to  other  functions,  such  as  ClockRateChanged 
(1-97). 

callBackType  Constants 

cal  1 BackAtT i me 

Indicates  that  the  event  is  to  be  invoked  at  a  specified  time, 
cal  1 BackAtRate 

Indicates  that  the  event  is  to  be  invoked  when  the  rate  for  the  time  base  reaches 
a  specified  value, 
call BackAtT i me Jump 

Indicates  that  the  event  is  to  be  invoked  when  the  time  base's  time  value 
changes  by  an  amount  that  differs  from  its  rate. 

call BackAt Interrupt 

Defines  the  bit  of  the  returned  value  which  indicates  that  the  event  can  be 
invoked  at  interrupt  time. 

Discussion 

Your  component  allocates  the  memory  required  to  support  the  callback  event.  The 
memory  must  be  in  a  locked  block  and  must  begin  with  a  QTCal  1  BackHeader 
(IV-2349)  structure  initialized  to  0.  Your  component  can  allocate  an  arbitrarily  large 
piece  of  memory  for  the  callback  event. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Using  Callback  Functions"  (V-2867) 


ClockRateChanged 


In  a  clock  component,  is  called  whenever  the  callback's  time  base  rate  changes. 

ComponentResul t  ClockRateChanged  ( 

Componentlnstance  aClock, 

QTCallBack  cb  ); 

aCl ock 

Specifies  the  clock  for  the  operation.  Applications  obtain  this  identifier  from  the 
Component  Manager's  OpenComponent  (11-1130)  function. 
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cb 

Specifies  the  callback  for  the  operation.  The  Movie  Toolbox  obtains  this  value 
from  your  component's  Cl  ockNewCal  1  Back  (1-96)  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  Movie  Toolbox  calls  this  function  once  for  each  qualified  callback  function 
associated  with  the  time  base.  Note  that  the  Movie  Toolbox  calls  this  function  only 
for  callback  events  that  are  currently  scheduled. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 
Programming  summary:  "Managing  the  Time"  (V-2868) 

See  Also 

See  the  Cal  1  BackRecord  (IV-2165)  structure. 


ClockSetTimeBase 


In  a  clock  component,  is  called  when  an  application  creates  a  time  base  that  uses  the 
clock  component. 

ComponentResul t  ClockSetTimeBase  ( 

Componentlnstance  aClock, 

T i meBase  tb  ) ; 

aCl ock 

Specifies  the  clock  for  the  operation.  Applications  obtain  this  identifier  from  the 
Component  Manager's  OpenComponent  (11-1130)  function. 

tb 

Specifies  the  time  base  that  is  associated  with  the  clock. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 
Programming  summary:  "Managing  the  Time"  (V-2868) 
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ClockStartStopChanged 


In  a  clock  component,  is  called  whenever  the  start  or  stop  time  of  the  callback's  time 
base  changes. 

ComponentResul t  ClockStartStopChanged  ( 

Componentlnstance  aClock, 

QTCallBack  cb. 

Boolean  startChanged , 

Boolean  stopChanged  ); 

aCl  ock 

Specifies  the  clock  for  the  operation.  Applications  obtain  this  identifier  from  the 
Component  Manager's  OpenComponent  (11-1130)  function, 
cb 

Specifies  the  callback  for  the  operation.  The  Movie  Toolbox  obtains  this  value 
from  your  component's  Cl  ockNewCal  1  Back  (1-96)  function. 

startChanged 

Indicates  that  the  start  time  of  the  time  base  associated  with  the  clock 
component  instance  has  changed. 
stopChanged 

Indicates  that  the  stop  time  of  the  time  base  associated  with  the  clock 
component  instance  has  changed. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  Movie  Toolbox  calls  this  function  once  for  each  qualified  callback  function 
associated  with  the  time  base.  Note  that  the  Movie  Toolbox  calls  this  function  only 
for  callback  events  that  are  currently  scheduled. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 
Programming  summary:  "Managing  the  Time"  (V-2868) 

See  Also 

See  the  Cal  1  BackRecord  (IV-2165)  structure. 
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ClockTimeChanged 

In  a  clock  component,  is  called  whenever  the  callback's  time  base  time  value  is  set. 

ComponentResul t  ClockTimeChanged  ( 

Componentlnstance  aClock, 

QTCal 1  Back  cb  ) ; 

aCl ock 

Specifies  the  clock  for  the  operation.  Applications  obtain  this  identifier  from  the 
Component  Manager's  OpenComponent  (11-1130)  function. 

cb 

Specifies  the  callback  for  the  operation.  The  Movie  Toolbox  obtains  this  value 
from  your  component's  Cl  ockNewCal  1  Back  (1-96)  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 
Programming  summary:  "Managing  the  Time"  (V-2868) 

See  Also 

See  the  Cal  1  BackRecord  (IV-2165)  structure. 


CloseComponent 

Terminates  your  application's  access  to  the  services  provided  by  a  component. 

OSErr  CloseComponent  ( 

Componentlnstance  aComponentlnstance  ); 

a Component  Instance 

A  component  instance.  Your  application  obtains  the  component  instance  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  following  snipped  shows  how  CloseComponent  is  called  when  a  component  is  no 
longer  needed. 

//  CloseComponent  coding  example 
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CloseComponentResFile 


It  See  “Discovering  QuickTime,”  page  279 

void  wri teGWorl dToImageFi 1 e(GWori dPtr  gw,  const  FSSpec  *fileSpec) 

{ 

Graphi csExportComponent  ge  =  0; 

OpenADef aul tComponentl Graphi csExporterComponentType , 

kQTFi 1 eTypePNG ,  &ge); 

Graphi cs Export Set InputGWorl d(ge ,  gw) ; 

Graphi csExportSetOutputFi le(ge,  fileSpec); 

Graph i cs Expo rt Do Expo rt(ge,  NIL); 

Cl oseComponent(ge) ; 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Component  Functions  Used  By  Applications"  (V-2781) 

CloseComponentResFile 

Closes  the  resource  file  that  your  component  opened  previously  with  the 
OpenComponentResFi  1  e  function. 

OSErr  CloseComponentResFile  ( 
short  refnum  ); 

ref num 

A  reference  number  that  identifies  the  resource  file.  Your  component  obtains 
this  value  from  OpenComponentResFi  1  e  (11-1130). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 
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CloseMixerSoundComponent 


CloseMixerSoundComponent 


Closes  the  Apple  Mixer  component. 

OSErr  CloseMixerSoundComponent  ( 
Componentlnstance  ci  ); 


ci 

A  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  usually  called  by  a  sound  output  device. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


CloseMovieFile 


Closes  an  open  movie  file. 

OSErr  CloseMovieFile  ( 
short  resRef Num  ) ; 

resRef Num 

The  movie  file  to  close.  Your  application  obtains  this  reference  number  from 
OpenMovi eFi  1  e  (11-1133). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

The  following  code  shows  a  typical  use  of  Cl  oseMovi  eFi  1  e. 

//  CloseMovieFile  coding  example 
//  See  “Discovering  QuickTime,”  page  50 
void  OpenMovie  (HWND  hwnd,  char  *szFileName) 

{ 

short  nFileRefNum  =  0; 
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FSSpec  fss; 

//  Convert  path  to  FSSpec 

Nati  vePathNameToFSSpecl szFi 1 eName ,  &fss,  0); 

//  Set  graphics  port 

SetGWori d( (CGraf Ptr )GetNati veWi ndowPortl hwnd ) ,  NIL); 

OpenMovieFi 1 e(&fss  ,  &n  Fi 1 eRefNum,  fsRdPerm);  //  Open  movie  file 
NewMovieFromFile(&movie,  nFi 1 eRefNum,  NIL,  //  Get  movie  from  file 
NIL,  newMovi eActi ve ,  NIL); 

Cl oseMovi eFi 1 e( n F i 1 eRefNum) ;  //  Close  movie  file 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Movie  Functions"  (V-2713) 

Related  Java  Methods 

qui  cktime .  i  o .  OpenedFi  1  e .  cl  ose( ) 


CodecManagerV  ersion 

Determines  the  version  of  the  installed  Image  Compression  Manager. 

OSErr  CodecManagerVersion  ( 
long  *version  ); 

versi on 

A  pointer  to  a  long  integer  that  is  to  receive  the  version  information.  The  Image 
Compression  Manager  returns  its  version  number  into  this  location.  The 
version  number  is  a  long  integer  value. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns  the  version  information  as  a  long  integer  value.  Use  this 
function  to  retrieve  the  version  number  associated  with  the  Image  Compression 
Manager  that  is  installed  on  a  particular  computer. 

Special  Considerations 

The  Image  Compression  Manager  provides  a  number  of  functions  that  allow  your 
application  to  obtain  information  about  the  facilities  available  for  image 
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Comp3tol 


compression  or  about  compressed  images.  Your  application  may  use  some  of  these 
functions  to  select  a  specific  compressor  or  decompressor  for  a  given  operation  or 
to  determine  how  much  memory  to  allocate  to  receive  a  decompressed  image.  In 
addition,  your  application  may  use  some  of  these  functions  to  determine  the 
capabilities  of  the  components  that  are  available  on  the  user's  computer  system. 
You  can  then  condition  the  options  your  program  makes  available  to  the  user  based 
on  the  user's  system  configuration. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Getting  Information  About  Compressor  Components" 
(V-2788) 

Related  Java  Methods 

qui ckti me. std . image. Codec Info. codec Vers i on ( ) 


Comp3tol 


Compresses  sound  samples  to  one-third  their  original  size.  Use 
SoundConverterConvertBuffer  (III— 1862)  instead,  if  possible. 

void  Comp3tol  ( 
const  void 
voi  d 

unsigned  long 
StateBl ockPtr 
StateBl ockPtr 
unsigned  long 
unsigned  long 

i nBuffer 

A  pointer  to  a  buffer  of  samples  to  be  compressed. 
outBuffer 

A  pointer  to  a  buffer  where  the  samples  are  to  be  written. 

cnt 

The  number  of  samples  to  compress, 
i nState 

A  pointer  to  a  128-byte  buffer  from  which  the  input  state  of  the  algorithm  is 
read,  or  NIL.  This  buffer  should  be  filled  with  zeros  to  initialize  the  algorithm. 


*i nBuffer , 
*outBuffer , 
cnt , 

i nState , 
outState , 
numChannel s , 
whi chChannel  ) ; 
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outState 

A  pointer  to  a  128-byte  buffer  to  which  the  output  state  of  the  algorithm  is 
written,  or  N I L.  This  buffer  may  be  the  same  as  that  specified  by  the  i  nState 
parameter. 
numChannel s 

The  number  of  channels  in  the  buffer  pointed  to  by  the  i nBuffer  parameter, 
whi chChannel 

The  channel  to  compress  when  numChannel  s  is  greater  than  1.  The  value  of  this 
parameter  must  be  in  the  range  1  to  numChannel  s. 

Discussion 

This  function  compresses  cnt  samples  of  sound  stored  in  the  buffer  specified  by 
i  nBuffer  and  places  the  result  in  the  buffer  specified  by  outBuffer,  which  must  be 
at  least  cnt/3  bytes  in  size.  The  original  samples  can  be  monophonic  or  include 
multiple  channels  of  sound,  but  they  must  be  in  8-bit  offset  binary  format.  Also,  if 
numChannel  s  is  greater  than  1,  then  the  noncompressed  sound  must  be  stored  in 
interleaved  format  on  a  sample  basis.  If  you  compress  polyphonic  sound,  you  retain 
only  one  channel  of  sound,  which  you  specify  in  the  whichChannel  parameter.  Thus, 
if  you  use  the  Comp3tol  procedure  to  compress  three-channel  sound,  you  will  have 
effectively  compressed  the  sound  to  one-ninth  its  original  size  in  bytes.  To  retain 
multiple  channels  of  sound  after  compression,  you  must  call  the  Comp3tol  procedure 
for  each  channel  to  be  compressed  and  then  interleave  the  compressed  sound  data 
on  a  packet  basis.  The  Comp3to  1  procedure  compresses  every  48  bytes  of  sound  data 
to  exactly  16  bytes  of  compressed  sound  data  and  compresses  remaining  bytes  to  no 
more  than  one-third  the  original  size.  You  can  use  the  i  nState  and  outState 
parameters  to  allow  the  MACE  compression  routines  to  preserve  information  about 
algorithms  across  calls.  Alternatively,  you  may  pass  NIL  state  buffers  and  let  the 
Sound  Manager  allocate  the  buffers  internally. 

Special  Considerations 

Because  the  Comp3tol  procedure  might  allocate  and  dispose  of  memory,  you  should 
not  call  it  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  4.  Macintosh  Note:  Not  available  in  CarbonLib,  but 
available  when  InterfaceLib  7.1  or  later  is  installed. 

Programming  Info 

C  interface  file:  Sound .  h 
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Comp6tol 


Compresses  sound  samples  to  one-sixth  their  original  size.  Use 
SoundConverterConvertBuffer  (III— 1862)  instead,  if  possible. 

void  Comp6tol  ( 
const  void 
voi  d 

unsigned  long 
StateBl ockPtr 
StateBl ockPtr 
unsigned  long 
unsigned  long 

i nBuffer 

A  pointer  to  a  buffer  of  samples  to  be  compressed. 
outBuffer 

A  pointer  to  a  buffer  where  the  samples  are  to  be  written. 

cnt 

The  number  of  samples  to  compress, 
i nState 

A  pointer  to  a  128-byte  buffer  from  which  the  input  state  of  the  algorithm  is 
read,  or  NIL.  This  buffer  should  be  filled  with  zeros  to  initialize  the  algorithm. 
outState 

A  pointer  to  a  128-byte  buffer  to  which  the  output  state  of  the  algorithm  is 
written,  or  NIL.  This  buffer  may  be  the  same  as  that  specified  by  the  instate 
parameter. 

numChannel s 

The  number  of  channels  in  the  buffer  pointed  to  by  the  i  nBuffer  parameter, 
whi chChannel 

The  channel  to  compress  when  numChannel  s  is  greater  than  1.  The  value  of  this 
parameter  must  be  in  the  range  1  to  numChannel  s. 

Discussion 

This  function  compresses  cnt  samples  of  sound  stored  in  the  buffer  specified  by 
i  nBuffer  and  places  the  result  in  the  buffer  specified  by  outBuffer,  which  must  be 
at  least  cnt/6  bytes  in  size.  Comp6tol  works  much  as  Comp3tol  (1-104),  but 
compresses  every  48  bytes  of  sound  data  to  exactly  8  bytes  of  compressed  sound 
data  and  compresses  remaining  bytes  to  no  more  than  one-sixth  the  original  size. 


*i nBuffer , 
*outBuffer , 
cnt , 

i nState , 
outState , 
numChannel s , 
whi chChannel  ) ; 
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Special  Considerations 

Because  the  Comp6tol  procedure  might  allocate  and  dispose  of  memory,  you  should 
not  call  it  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  4.  Macintosh  Note:  Not  available  in  CarbonLib,  but 
available  when  InterfaceLib  7.1  or  later  is  installed. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

See  Comp3tol  (1-104). 


CompAdd 


Undocumented 

void  CompAdd  ( 
wide  *src, 

wide  *dst  ); 


src 

Undocumented 

dst 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


CompCompare 


Undocumented 

long  CompCompare  ( 
const  wide  *a, 

const  wide  *minusb  ); 


a 

Undocumented 
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mi nusb 

Undocumented 

function  result  Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


CompDiv 


Undocumented 

long  CompDiv  ( 

wide  Numerator, 

long  denominator, 

1  ong  *remai nder  ) ; 

numerator 

Undocumented 

denomi nator 

Undocumented 

remai nder 

Undocumented 

function  result  Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


CompFixMul 


Undocumented 

void  CompFixMul  ( 

wide  *compSrc, 

Fixed  fixSrc, 

wi de  *compDst  ) ; 
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compSrc 

Undocumented 
f  i  xSrc 

Undocumented 

compDst 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


CompMul 


Undocumented 

void  CompMul  ( 
long  srcl, 

long  src2, 

wide  *dst  ); 

srcl 

Undocumented 

src2 

Undocumented 

dst 

Undocumented 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


CompMulDiv 


Undocumented 

void  CompMulDiv  ( 
wide  *co, 

1  ong  mul  , 
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1  ong  di vi sor  ) ; 

co 

Undocumented 

mul 

Undocumented 
di vi sor 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


CompMulDivT  rune 


Undocumented 

void  CompMulDivTrunc  ( 

wide  *co, 

1 ong  mul  , 

long  divisor, 

1  ong  *remai nder  ) ; 

co 

Undocumented 


mul 

Undocumented 

divisor 

Undocumented 
remai nder 

Undocumented 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 
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CompNeg 


Undocumented 

void  CompNeg  ( 

wide  *dst  ); 


dst 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


ComponentFunctionlmplemented 


Determines  whether  a  component  supports  a  specified  request. 

long  ComponentFunctionlmplemented  ( 

Componentlnstance  ci  , 

short  ftnNumber  ); 


ci 

A  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
ftnNumber 

A  request  code  value.  See  Inside  Macintosh:  QuickTime  Components  (listed  in  the 
bibliography)  for  information  about  the  request  codes  supported  by  the 
QuickTime  components  supplied  by  Apple.  For  other  components,  see  their 
developer's  documentation. 

function  result  A  long  integer  that  can  be  interpreted  as  a  Bool  ean  value.  If  TRUE,  the 
component  supports  the  request;  if  FALSE,  it  does  not. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Component  Functions  Used  By  Applications"  (V-2781) 
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ComponentSetT  arget 


Calls  a  component's  target  request  routine,  which  handles  the 
kComponentTargetSel  ect  request  code. 

long  ComponentSetTarget  ( 

Componentlnstance  ci  , 

Componentlnstance  target  ); 


ci 

A  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

target 

The  component  instance  of  the  component  issuing  the  target  request. 

function  result  The  value  that  the  targeted  component  instance  returned  in  response 
to  the  target  request,  or  a  constant  (see  below). 

Function  Result  Constants 

badComponentSel ector 

The  targeted  component  does  not  support  the  target  request. 

Discussion 

This  function  returns  a  function  result  of  badComponentSel  ector  if  the  targeted 
component  does  not  support  the  target  request.  Otherwise,  the  ComponentSetTarget 
function  returns  as  its  function  result  the  value  that  the  targeted  component 
instance  returned  in  response  to  the  target  request. 

Special  Considerations 

You  should  not  target  a  component  instance  if  the  component  does  not  support  the 
target  request.  Before  calling  this  function,  you  should  issue  a  can  do  request  to  the 
component  instance  you  want  to  target  to  verify  that  the  component  supports  the 
target  request.  If  the  component  supports  it,  use  the  ComponentSetT  arget  function  to 
send  a  target  request  to  the  component  instance  you  wish  to  target.  After  receiving 
a  target  request,  the  targeted  component  instance  should  call  the  component 
instance  that  targeted  it  whenever  the  targeted  component  instance  would 
normally  call  one  of  its  defined  functions. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 
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Compresslmage 


Compresses  a  single-frame  image  that  is  currently  stored  as  a  pixel  map  structure. 


OSErr  Compresslmage  ( 

PixMapHandle  src, 

const  Rect  *srcRect, 

CodecQ  quality, 

CodecType  cType, 

ImageDescri pti onHandl e  desc, 

Ptr  data  ); 


src 

A  handle  to  the  image  to  be  compressed.  The  image  must  be  stored  in  a  pixel 
map  structure. 

srcRect 

A  pointer  to  a  rectangle  defining  the  portion  of  the  image  to  compress, 
quality 

A  constant  (see  below)  that  defines  the  desired  compressed  image  quality. 
cType 

A  compressor  type;  see  "Codec  Identifiers"  (IV-2655). 

desc 

A  handle  that  is  to  receive  a  formatted  ImageDescri  pti  on  (IV-2285)  structure. 
The  Image  Compression  Manager  resizes  this  handle  for  the  returned  image 
description  structure.  Your  application  should  store  this  image  description 
with  the  compressed  image  data. 

data 

Points  to  a  location  to  receive  the  compressed  image  data.  It  is  your  program's 
responsibility  to  make  sure  that  this  location  can  receive  at  least  as  much  data 
as  indicated  by  the  GetMaxCompressi  onSi  ze  (1-420)  function.  The  Image 
Compression  Manager  places  the  actual  size  of  the  compressed  image  into  the 
dataSi  ze  field  of  the  ImageDescri  pti  on  (IV-2285)  structure  structure  referred  to 
by  the  desc  parameter.  This  pointer  must  contain  a  32-bit  clean  address. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

quality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
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codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics, 
codec Normal  Qua  1 i ty 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 
codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field. 
codecLosslessQuality 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

Discussion 

The  following  code  sample  illustrates  the  process  of  compressing  and 
decompressing  a  pixel  map. 


//  Compresslmage  coding  example 
//  See  “Discovering  QuickTime,”  page  286 
PicHandle  GetQTCompressedPi ct  ( Pi xMapHandl e  hpmlmage) 
{ 


1  ong 
Handl e 
Ptr 

ImageDescriptionHandle 

OSErr 

Pi cHandl e 

Rect 

CodecType 

CodecComponent 

CodecQ 

short 


1 MaxCompressedSi ze  =  0; 
hCompressedData  =  NIL; 
pCompressedData ; 
hlmageDesc  =  NIL; 
nErr ; 

hpicPicture  =  NIL; 

rectlmage  =  (**hpmlmage ). bounds ; 

dwCodecType  =  kJPEGCodecType ; 

codec  =  (CodecComponent)anyCodec; 

dwSpati al Qual i ty  =  codecNormal Qual i ty ; 

nDepth  =  0;  //  let  ICM  choose  depth 


nErr  =  GetMaxCompressi onSi ze( hpmlmage  ,  &rectlmage,  nDepth, 

dwSpati al Qual i ty , 
dwCodecType , 

( Comp  res so rComponen t ) codec , 
&1 MaxCompressedSi ze ) ; 


if  (nErr  !=  noErr) 
return  NIL; 
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hlmageDesc  =  ( ImageDescri pti onHandl e)NewHandl e(4) ; 
hCompressedData  =  NewHandl e( 1 MaxCompressedSi ze) ; 
if  ((hCompressedData  !=  NIL)  &&  (hlmageDesc  !=  NIL))  { 
MoveHHi (hCompressedData ) ; 

HLock( hCompressedData ) ; 

pCompressedData  =  Stri pAddress (*hCompressedData  ) ; 


nErr  =  Compress Image( hpmlmage , 

&rectlmage , 
dwSpati al Qual i ty , 
dwCodecType , 
hlmageDesc, 
pCompressedData ) ; 


if  (nErr  ==  noErr)  { 

Cl  ip Rect(& recti mage) ; 

hpi cPi cture  =  OpenPi cture(&rectlmage) ; 

nErr  =  Decompress Image( pCompressedData  , 

hlmageDesc, 
hpmlmage , 
&rectlmage , 
&rectlmage , 
srcCopy , 
NIL) ; 

Cl osePi cture( ) ; 

} 


if  (theErr  ||  (GetHandl eSi ze( ( Handl e)hpi cPi cture)  == 

sizeof ( Pi cture) ) )  { 

Ki 1 1  Pi cture( hpi cPi cture) ; 
hpi cPi cture  =  NIL; 

} 

} 

if  (hlmageDesc  !=  NIL) 

DisposeHandle(( Handl e)hImageDesc); 

if  (hCompressedData  !=  NIL) 
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DisposeHandlet h Compressed Data ) ; 
return  hpicPicture; 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Pixel  Maps"  (V-2789) 

Related  Java  Methods 

qui ckti me . std . i mage . QT Image . compress ( ) 


CompressPicture 


Compresses  a  single-frame  image  stored  as  a  picture  structure  and  places  the  result 
in  another  picture. 

OSErr  CompressPicture  ( 

PicHandle  srcPicture, 

PicHandle  dstPicture, 

CodecQ  quality, 

CodecType  cType  ) ; 

srcPi cture 

A  handle  to  the  source  image,  stored  as  a  picture. 
dstPi cture 

A  handle  to  the  destination  for  the  compressed  image.  The  compressor  resizes 
this  handle  for  the  result  data. 

qual i ty 

A  constant  (see  below)  that  defines  the  desired  compressed  image  quality. 
cType 

You  must  set  this  parameter  to  a  valid  compressor  identifier;  see  "Codec 
Identifiers"  (IV-2655).  If  the  value  passed  in  is  0,  or  '  raw  and  the  source 
picture  is  compressed,  the  destination  picture  is  created  as  an  uncompressed 
picture  and  does  not  require  QuickTime  for  its  display. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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quality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 
codecNormal Quality 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 

codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field, 
codec Los  si essQual  i  ty 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

Discussion 

This  function  compresses  only  image  data.  Any  other  types  of  data  in  the  picture, 
such  as  text,  graphics  primitives,  and  previously  compressed  images,  are  not 
modified  in  any  way  and  are  passed  through  to  the  destination  picture.  This 
function  supports  parameters  governing  image  quality  and  compressor  type.  The 
compressor  infers  the  other  compression  parameters  from  the  image  data  in  the 
source  picture. 

Special  Considerations 

If  a  picture  with  multiple  pixel  maps  and  other  graphical  objects  is  passed,  the  pixel 
maps  will  be  compressed  individually  and  the  other  graphic  objects  will  not  be 
affected.  This  function  does  not  use  the  graphics  port. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Pictures  and  PICT  Files"  (V-2790) 

Related  Java  Methods 

qui ckti me . qd . Pi ct . compress ( ) 


See  Also 

If  your  picture  does  not  fit  in  memory,  use  the  Compress  Pi  ctureFi  1  e  (1-118)  function. 
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CompressPictureFile 

Compresses  a  single-frame  image  stored  as  a  picture  file  and  places  the  result  in 
another  picture  file. 

OSErr  CompressPictureFile  ( 
short  srcRefNum, 

short  dstRefNum, 

CodecQ  quality, 

CodecType  cType  ) ; 

srcRefNum 

A  file  reference  number  for  the  source  'PICT'  file. 
dstRefNum 

A  file  reference  number  for  the  destination  'PICT'  file.  Note  that  the  compressor 
overwrites  the  contents  of  the  file  referred  to  by  dstRefNum.  You  must  open  this 
file  with  write  permission.  The  destination  file  can  be  the  same  as  the  source  file 
specified  by  the  srcRefNum  parameter. 

qual i ty 

A  constant  (see  below)  that  defines  the  desired  compressed  image  quality. 
cType 

A  compressor  type.  You  must  set  this  parameter  to  a  valid  compressor  type 
constant;  see  "Codec  Identifiers"  (IV-2655).  If  the  value  passed  in  is  0,  or  '  raw 
' ,  and  the  source  picture  is  compressed,  the  destination  picture  is  created  as  an 
uncompressed  picture  and  does  not  require  QuickTime  to  be  displayed. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

quality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics, 
codec Normal Qual i ty 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 

codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field. 
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codec Los  si essQual i ty 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

Discussion 

This  function  supports  parameters  governing  image  quality  and  compressor  type. 
The  compressor  infers  the  other  compression  parameters  from  the  image  data  in  the 
source  picture  file. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Pictures  and  PICT  Files"  (V-2790) 


CompressSequenceBegin 


Signals  the  beginning  of  the  process  of  compressing  a  sequence  of  frames. 


OSErr  CompressSequenceBegin 
ImageSequence 
Pi xMapHandl e 
Pi xMapHandl e 
const  Rect 
const  Rect 
short 
CodecType 

Comp res sorComponent 
CodecQ 
CodecQ 
1  ong 

CTabHandl e 
CodecFl  ags 

ImageDescri pti on Hand! e 


*seqID, 
src, 
prev , 

*srcRect, 
*prevRect , 
col orDepth , 
cType , 
codec , 

spati al Qual i ty , 
temporal Qual i ty , 
keyFrameRate , 
ctabl e , 
fl ags , 
desc  ); 


seqlD 

A  pointer  to  a  field  to  receive  the  unique  identifier  for  this  sequence.  You  must 
supply  this  identifier  to  all  subsequent  Image  Compression  Manager  functions 
that  relate  to  this  sequence. 

src 

A  handle  to  a  pixel  map  that  will  contain  the  image  to  be  compressed.  The 
image  must  be  stored  in  a  pixel  map  structure. 
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prev 

A  handle  to  a  pixel  map  that  will  contain  a  previous  image.  The  compressor 
uses  this  buffer  to  store  a  previous  image  against  which  the  current  image 
(stored  in  the  pixel  map  referred  to  by  the  s  rc  parameter)  is  compared  when 
performing  temporal  compression.  This  pixel  map  must  be  created  at  the  same 
depth  and  with  the  same  color  table  as  the  source  image.  The  compressor 
manages  the  contents  of  this  pixel  map  based  upon  several  considerations,  such 
as  the  key  frame  rate  and  the  degree  of  difference  between  compared  images. 
If  you  want  the  compressor  to  allocate  this  pixel  map  or  if  you  do  not  want  to 
perform  temporal  compression  (that  is,  you  have  set  the  value  of  the 
temporal  Qual  i  ty  parameter  to  0),  set  this  parameter  to  NIL. 
srcRect 

A  pointer  to  a  rectangle  defining  the  portion  of  the  image  to  compress.  The 
compressor  applies  this  rectangle  to  the  image  stored  in  the  buffer  referred  to 
by  the  s  rc  parameter. 

prevRect 

A  pointer  to  a  rectangle  defining  the  portion  of  the  previous  image  to  use  for 
temporal  compression.  The  compressor  uses  this  portion  of  the  previous  image 
as  the  basis  of  comparison  with  the  current  image.  The  compressor  ignores  this 
parameter  if  you  have  not  provided  a  buffer  for  previous  images.  This  rectangle 
must  be  the  same  size  as  the  source  rectangle,  which  is  specified  with  the 
srcRect  parameter, 
col orDepth 

The  depth  at  which  the  sequence  is  likely  to  be  viewed.  Compressors  may  use 
this  as  an  indication  of  the  color  or  grayscale  resolution  of  the  compressed 
images.  If  you  set  this  parameter  to  0,  the  Image  Compression  Manager 
determines  the  appropriate  value  for  the  source  image.  Values  of  1, 2, 4,  8, 16, 
24,  and  32  indicate  the  number  of  bits  per  pixel  for  color  images.  Values  of  34, 
36,  and  40  indicate  2-bit,  4-bit,  and  8-bit  grayscale,  respectively,  for  grayscale 
images.  Your  program  can  determine  which  depths  are  supported  by  a  given 
compressor  by  examining  the  compressor  information  structure  returned  by 
the  GetCodecInfo  (1-385)  function. 
cType 

You  must  set  this  parameter  to  a  valid  compressor  type  constant.  See  "Codec 
Identifiers"  (IV-2655). 

codec 

Specify  a  particular  compressor  by  setting  this  parameter  to  its  compressor 
identifier.  Alternatively,  you  may  use  a  special  identifier  (see  below). 
Specifying  a  component  instance  maybe  useful  if  you  have  previously  set  some 
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parameter  on  a  specific  instance  of  a  codec  field  and  want  to  make  sure  that  the 
specified  instance  is  used  for  that  operation. 

spati al Qual i ty 

A  pointer  to  a  field  containing  a  constant  (see  below)  that  defines  the  desired 
compressed  image  quality.  You  can  change  the  value  of  this  parameter  for  an 
active  sequence  by  calling  SetCSequenceQual  i  ty  (III— 1580). 

temporal Qual i ty 

A  pointer  to  a  field  containing  a  constant  (see  below)  that  defines  the  desired 
temporal  quality.  This  parameter  governs  the  level  of  compression  you  desire 
with  respect  to  information  between  successive  frames  in  the  sequence.  Set  to  0 
if  you  do  not  want  temporal  compression.  You  can  change  the  value  of  this 
parameter  for  an  active  sequence  by  calling  SetCSequenceQual  i  ty  (III— 1580). 

keyFrameRate 

Specifies  the  maximum  number  of  frames  allowed  between  key  frames.  The 
compressor  determines  the  optimum  placement  for  key  frames  based  upon  the 
amount  of  redundancy  between  adjacent  images  in  the  sequence. 
Consequently,  the  compressor  may  insert  key  frames  more  frequently  than  you 
have  requested.  However,  the  compressor  never  places  fewer  key  frames  than 
is  indicated  by  the  setting  of  the  keyFrameRate  parameter.  The  compressor 
ignores  this  parameter  if  you  have  not  requested  temporal  compression  (that  is, 
you  have  set  the  temporal  Qual  i  ty  parameter  to  0).  If  you  pass  in  0  in  this 
parameter,  this  indicates  that  there  are  no  key  frames  in  the  sequence.  If  you 
pass  in  any  other  number,  it  specifies  the  number  of  non-key  frames  between 
key  frames.  Set  this  parameter  to  1  to  specify  all  key  frames,  to  2  to  specify  every 
other  frame  as  a  key  frame,  to  3  to  specify  every  third  frame  as  a  key  frame,  and 
so  forth.  Your  application  may  change  the  key  frame  rate  for  an  active  sequence 
by  calling  SetCSequenceKeyFrameRate  (III— 1577). 

ctabl e 

A  handle  to  a  custom  color  lookup  table.  Your  program  may  use  this 
parameter  to  indicate  a  custom  color  lookup  table  to  be  used  with  this  image.  If 
the  value  of  the  colorDepth  parameter  is  less  than  or  equal  to  8  and  the  custom 
color  lookup  table  is  different  from  that  of  the  source  pixel  map  (that  is,  the 
ctSeed  field  values  differ  in  the  two  pixel  maps),  the  compressor  remaps  the 
colors  of  the  image  to  the  custom  colors.  If  you  set  the  col  orDepth  parameter  to 
16, 24,  or  32,  the  compressor  stores  the  custom  color  table  with  the  compressed 
image.  The  compressor  may  use  the  table  to  specify  the  best  colors  to  use  when 
displaying  the  image  at  lower  bit  depths.  The  compressor  ignores  the  ctabl  e 
parameter  when  col  orDepth  is  set  to  33,  34, 36,  or  40.  If  you  set  this  parameter 
to  NIL,  the  compressor  uses  the  color  lookup  table  from  the  source  pixel  map. 
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fl  ags 

Contains  flags  (see  below)  that  provide  further  control  information.  You  must 
set  either  codecFl  agllpdatePrevi  ous  or  codecFl  agUpdatePrevi  ousComp  to  1.  Set 
unused  flags  to  0. 

desc 

A  handle  that  is  to  receive  a  formatted  ImageDescri  pti  on  (IV-2285)  structure. 
The  Image  Compression  Manager  resizes  this  handle  for  the  returned  image 
description  structure.  Your  application  should  store  this  image  description 
with  the  compressed  sequence.  During  the  compression  operation,  the  Image 
Compression  Manager  and  the  compressor  component  update  the  contents  of 
this  image  description.  Consequently,  you  should  not  store  the  image 
description  until  the  sequence  has  been  completely  processed. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

spatialQuality  and  temporalQuality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 
codecNormal Qual i ty 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 
codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field, 
codec LosslessQuality 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

codec  Constants 

anyCodec 

The  first  compressor  or  decompressor  of  the  specified  type. 
bestSpeedCodec 

The  fastest  compressor  or  decompressor  of  the  specified  type. 
bestFi del i tyCodec 

The  most  accurate  compressor  or  decompressor  of  the  specified  type. 


1-122 


Inside  QuickTime:  Functions  A-H 


CompressSequenceBegin 


bestCompressi onCodec 

The  compressor  that  produces  the  smallest  resulting  data. 

flags  Constants 

codec FI  a g Update P rev i  ous 

Controls  whether  the  compressor  updates  the  previous  image  during 
compression.  This  flag  is  only  used  with  sequences  that  are  being  temporally 
compressed.  If  you  set  this  flag  to  1,  the  compressor  copies  the  current  frame 
into  the  previous  frame  buffer  at  the  end  of  frame  compression. 

codec FI  a g Update P rev i ous Comp 

Controls  whether  the  compressor  updates  the  previous  image  buffer  with  the 
compressed  image.  This  flag  is  only  used  with  temporal  compression  and  is 
similar  to  the  codecFl  agllpdatePrevI  ous  flag.  As  with  the 

codecFl  agllpdatePrevi  ous  flag,  if  you  set  this  flag  to  1,  the  compressor  updates 
the  previous  frame  buffer  at  the  end  of  frame  compression.  However,  this  flag 
causes  the  Image  Compression  Manager  to  update  the  frame  buffer  using  an 
image  obtained  by  decompressing  the  results  of  the  most  recent  compression 
operation,  rather  than  the  source  image,  which  may  give  better  results  at  the 
expense  of  taking  more  time. 

codecFl a g Was Compressed 

Indicates  to  the  compressor  that  the  image  to  be  compressed  has  been 
compressed  before.  This  information  may  be  useful  to  compressors  that  can 
compensate  for  the  image  degradation  that  may  otherwise  result  from  repeated 
compression  and  decompression  of  the  same  image.  Set  this  flag  to  1  to  indicate 
that  the  image  was  previously  compressed.  Set  this  flag  to  0  if  the  image  was 
not  previously  compressed. 

Discussion 

The  Image  Compression  Manager  prepares  for  a  sequence-compression  operation 
by  reserving  appropriate  system  resources.  Hence  you  must  call 
CompressSequenceBegi  n  before  you  call  CompressSequenceFrame  (1-124). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Sequences"  (V-2792) 

Related  Java  Methods 

qui ckti me . std . image . CSeq uence . CSequenceC ) 
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See  Also 

You  can  set  or  change  the  previous  image  buffer  for  an  active  sequence,  or  change 
its  rectangle,  by  calling  SetCSequencePrev  (III— 1579).  You  can  obtain  a  pointer  to  a 
pixel  map  that  was  allocated  by  the  compressor  by  calling  GetCSequencePrevBuf  f  er 

(1-406). 


CompressSequenceFrame 


Compresses  one  of  a  sequence  of  frames. 


OSErr  CompressSequenceFrame  ( 
ImageSequence 
Pi xMapHandl e 
const  Rect 
CodecFl ags 
Ptr 
1  ong 
UInt8 

ICMCompl etionProcRecordPtr 


seqlD , 
src , 

*srcRect , 
fl ags , 
data , 

*dataSi ze , 

*si mi  1 ari ty , 
asyncCompl eti onProc  ); 


seqlD 

Unique  sequence  identifier  that  was  returned  by  CompressSequenceBegi  n 
(1-119). 

src 

A  handle  to  a  pixel  map  that  contains  the  image  to  be  compressed.  The  image 
must  be  stored  in  a  pixel  map  structure. 

srcRect 

A  pointer  to  a  rectangle  defining  the  portion  of  the  image  to  compress.  The 
compressor  applies  this  rectangle  to  the  image  stored  in  the  buffer  referred  to 
by  the  src  parameter. 

fl  ags 

Specifies  flags  (see  below)  that  provide  further  control  information.  You  must 
set  either  codecFl  agllpdatePrevi  ous  or  codecFl  agUpdatePrevi  ousComp  to  1.  Set 
unused  flags  to  0. 

data 

Points  to  a  location  to  receive  the  compressed  image  data.  It  is  your  program's 
responsibility  to  make  sure  that  this  location  can  receive  at  least  as  much  data 
as  indicated  by  the  GetMaxCompressi  onSi  ze  (1-420)  function.  The  Image 
Compression  Manager  places  the  actual  size  of  the  compressed  image  into  the 
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field  referred  to  by  the  dataSi  ze  parameter.  This  pointer  must  contain  a  32-bit 
clean  address. 

dataSi ze 

A  pointer  to  a  field  that  is  to  receive  the  size,  in  bytes,  of  the  compressed  image, 
si  mi  1 ari ty 

A  pointer  to  a  field  that  is  to  receive  a  similarity  value.  The 
CompressSequenceFrame  function  returns  a  value  that  indicates  the  similarity  of 
the  current  frame  to  the  previous  frame.  A  value  of  0  indicates  that  the  current 
frame  is  a  key  frame  in  the  sequence.  A  value  of  255  indicates  that  the  current 
frame  is  identical  to  the  previous  frame.  Values  from  1  through  254  indicate 
relative  similarity,  ranging  from  very  different  (1)  to  very  similar  (254). 
asyncCompl eti on P roc 

Points  to  an  ICMCompl  eti  onProc  (III— 2087)  callback.  The  compressor  calls  your 
completion  function  when  an  asynchronous  compression  operation  is 
complete.  You  can  cause  the  compression  to  be  performed  asynchronously  by 
specifying  a  completion  function  if  the  compressor  supports  asynchronous 
compression. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

codec FI  a g Update P rev i  ous 

Controls  whether  the  compressor  updates  the  previous  image  during 

compression.  This  flag  is  only  used  with  sequences  that  are  being 

temporally  compressed.  If  you  set  this  flag  to  1,  the  compressor  copies 

the  current  frame  into  the  previous  frame  buffer  at  the  end  of  frame 

compression, 
codec FI  a g Was Compressed 

Indicates  to  the  compressor  that  the  image  to  be  compressed  has  been 

compressed  before.  This  information  may  be  useful  to  compressors  that 

can  compensate  for  the  image  degradation  that  may  otherwise  result  from 
repeated  compression  and  decompression  of  the  same  image.  Set  this  flag  to  1 
to  indicate  that  the  image  was  previously  compressed.  Set  this  flag  to  0 

if  the  image  was  not  previously  compressed. 

codecFl  agllpdatePrevi  ousComp 

Controls  whether  the  compressor  updates  the  previous  image  buffer  with 
the  compressed  image.  This  flag  is  only  used  with  temporal  compression 
and  is  similar  to  the  codecFl  agllpdatePrevi  ous  flag.  If  you  set  this  flag  to  1,  the 
compressor  updates  the  previous  frame  buffer  at  the  end  of  frame  compression. 
However,  this  flag  causes  the  Image  Compression  Manager  to  update  the  frame 
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buffer  using  an  image  obtained  by  decompressing  the  results  of  the  most 
recent  compression  operation,  rather  than  the  source  image. 

codec  FI  a g Force Key  Frame 

Controls  whether  the  compressor  creates  a  key  frame  from  the  current 

image.  This  flag  is  only  used  with  temporal  compression.  If  you  set  this 

flag  to  1,  the  compressor  makes  the  current  image  a  key  frame.  If  you  set 
this  flag  to  0,  the  compressor  decides  based  on  other  criteria,  such  as  the 
key  frame  rate,  whether  to  create  a  key  frame  from  the  current  image.  If 

you  don't  want  any  key  frames  other  than  the  ones  that  are  forced,  set 

the  key  frame  rate  for  the  sequence  to  0. 

codecFl  agLi  veGrab 

Indicates  to  the  compressor  that  speed  is  of  the  utmost  importance,  and 

that  size  and  quality  are  of  lesser  importance.  This  flag  is  useful  when 

you  are  grabbing  sequences  from  a  live  source  where  each  frame  must 

be  compressed  quickly. 

Discussion 

The  Image  Compression  Manager  prepares  for  a  sequence-compression  operation 
by  reserving  appropriate  system  resources.  Hence  you  must  call 
CompressSequenceBegi  n  (1-119)  before  you  call  CompressSequenceFrame. 

Special  Considerations 

If  you  specify  asynchronous  operation,  you  must  not  read  the  compressed  data 
until  the  compressor  indicates  that  the  operation  is  complete  by  calling  your 
completion  function.  Set  asyncCompl  eti  onProc  to  NI L  to  specify  synchronous 
compression.  If  you  set  asyncCompl  eti  onProc  to  -1,  the  operation  is  performed 
asynchronously  but  the  compressor  does  not  call  your  completion  function.  If  the 
asyncCompleti  onProc  parameter  is  not  N I L,  the  following  conditions  are  in  effect:  the 
pixels  in  the  source  image  must  stay  valid  until  the  completion  function  is  called 
with  itscodecCompletionSource  flag,  and  the  resulting  compressed  data  is  not  valid 
until  it  is  called  with  its  codecCompl  eti  onDest  flag  set. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Sequences"  (V-2792) 

Related  Java  Methods 

quicktime.std.image.CSequence. compress  Frame ( ) 


See  Also 

See  SCCompressSequenceFrame  (III — 1534). 
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CompShift 


Undocumented 

void  CompShift  ( 
wide  *src, 

short  shift  ); 


src 

Undocumented 

shift 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


CompSquareRoot 

Undocumented 

long  CompSquareRoot  ( 

const  wi de  *src  ) ; 

src 

Undocumented 

function  result  Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


CompSub 


Undocumented 

void  CompSub  ( 
wide  *src, 

wide  *dst  ); 
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src 

Undocumented 

dst 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


ConcatMatrix 


Concatenates  two  matrices,  combining  the  transformations  described  by  both 
matrices  into  a  single  matrix. 

void  ConcatMatrix  ( 

const  MatrixRecord  *a , 

Matri xRecord  *b  ) ; 


a 

A  pointer  to  the  source  matrix, 
b 

A  pointer  to  the  destination  matrix.  The  ConcatMatrix  function  performs  a 
matrix  multiplication  operation  on  the  two  matrices  and  leaves  the  result  in  the 
matrix  specified  by  this  parameter. 

Discussion 

This  is  a  matrix  multiplication  operation,  as  a  result  of  which  [B]  =  [B]  x  [A].  Note 
that  matrix  multiplication  is  not  commutative. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Matrices"  (V-2764) 

Related  Java  Methods 

qui ckti me. std . image .Matrix. concat( ) 
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ConvertFileT  oMovieFile 


Converts  a  file  to  a  movie  file  and  supports  a  user  settings  dialog  box  for  import 
operations. 


OSErr  ConvertFileToMovieFile  ( 


const  FSSpec 
const  FSSpec 
OSType 
Seri ptCode 
short 
1  ong 

Componentlnstance 
Movi eProgressUPP 
1  ong 


*i  nputFi  1  e , 
*outputFi  1  e , 
creator , 
scri ptTag , 
*resID, 
fl ags , 
userComp , 
proc , 
refCon  ); 


i  nputFi 1 e 

A  pointer  to  the  file  system  specification  for  the  file  to  be  converted  into  a  movie 
file. 

outputFi 1 e 

A  pointer  to  the  file  specification  for  the  destination  movie  file, 
creator 

The  creator  value  for  the  file  if  it  is  a  new  one. 
scri ptTag 

The  script  in  which  the  movie  file  should  be  converted.  Use  the  Script  Manager 
constant  smSystemScri  pt  to  use  the  system  script;  use  the  smCurrentScri  pt 
constant  to  use  the  current  script.  See  Inside  Macintosh:  Text  (listed  in  the 
bibliography)  for  more  information  about  scripts  and  script  tags. 
resID 

A  pointer  to  a  field  that  is  to  receive  the  resource  ID  of  the  file  to  be  converted. 
If  you  don't  want  to  receive  the  resource  ID,  set  this  parameter  to  NIL. 
fl  ags 

Contains  flags  (see  below)  that  control  movie  file  conversion  and  determine 
whether  or  not  the  user  settings  dialog  box  appears. 

userComp 

Indicates  a  component  or  component  instance  of  the  movie  export  component 
you  want  to  perform  the  conversion.  Otherwise,  set  this  parameter  to  0  for  the 
Movie  Toolbox  to  choose  the  appropriate  component.  If  you  pass  in  a 
component  instance,  it  will  be  used  by  ConvertFi  1  eToMovi  eFi  1  e.  This  allows 
you  to  communicate  directly  with  the  component  before  using  this  function  to 
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establish  any  conversion  parameters.  If  you  pass  in  a  component  ID,  an  instance 
is  created  and  closed  within  this  function. 

proc 

Points  to  your  progress  callback.  To  remove  a  movie's  progress  function,  set 
this  parameter  to  N I L.  Set  this  parameter  to  -1  for  the  Movie  Toolbox  to  provide 
a  default  progress  function.  See  Movi eProgressProc  (III— 2105)  for  the  interface 
your  progress  callback  must  support. 

refCon 

A  reference  constant  to  be  passed  to  your  callback.  Use  this  parameter  to  point 
to  a  data  structure  containing  any  information  your  function  needs. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

flags  Constants 

createMovieFileDeleteCurFile 

Indicates  whether  to  delete  an  existing  file.  If  you  set  this  flag  to  1,  the  Movie 
Toolbox  deletes  the  file  (if  it  exists)  before  converting  the  new  movie  file.  If  you 
set  this  flag  to  0  and  the  file  specified  by  the  f  i  1  eSpec  parameter  already  exists, 
the  Movie  Toolbox  uses  the  existing  file.  In  this  case,  the  toolbox  ensures  that 
the  file  has  both  a  data  and  a  resource  fork. 

movi eToFi 1 eOnly Export 

If  this  bit  is  set  and  the  showllserSetti  ngsDi  al  og  bit  is  set,  the  Save  As  dialog  box 
restricts  the  user  to  those  file  formats  that  are  supported  by  movie  data  export 
components, 
movi eFi 1 eSpecVal i d 

If  this  bit  is  set  and  the  showllserSetti  ngsDi  al  og  bit  is  set,  the  name  field  of  the 
outputFile  parameter  is  used  as  the  default  name  of  the  exported  file  in  the 
Save  As  dialog  box. 
showllserSetti  ngsDi  al  og 

Controls  whether  the  user  settings  dialog  box  for  the  specified  import  operation 
can  appear.  Set  this  flag  to  1  to  display  the  user  settings  dialog  box. 

Discussion 

Use  this  function  to  specify  an  input  file  and  convert  it  to  a  movie  file.  Because  some 
conversions  may  take  a  nontrivial  amount  of  time,  you  can  pass  a  standard  movie 
progress  function  in  the  proc  and  refCon  parameters. 

Special  Considerations 

Once  you  are  finished  working  with  a  movie,  you  should  release  the  resources  used 
by  the  movie  by  calling  Di  sposeMovi  e  (1-268). 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Movie  Functions"  (V-2713) 

Related  Java  Methods 

qui cktime . i o . QTFi 1 e . convertToMovi e  F i  1  e ( ) 


See  Also 

ConvertMovi  eToFi  1  e  (1-134)  takes  a  specified  movie  (or  a  single  track  within  that 
movie)  and  converts  it  into  an  output  file. 


Convertlmage 


Converts  the  format  of  a  compressed  image. 
OSErr  Convertlmage  ( 


ImageDescri pti onHandle 

srcDD, 

Ptr 

srcData , 

short 

col orDepth , 

CTabHandl e 

ctabl e , 

CodecQ 

accuracy , 

CodecQ 

quality. 

CodecType 

cType , 

CodecComponent 

codec , 

ImageDescri pti on Hand! e 

dstDD , 

Ptr 

dstData  ); 

srcDD 

A  handle  to  the  ImageDescri  pti  on  (IV-2285)  structure  that  describes  the 
compressed  image. 
srcData 

Points  to  the  compressed  image  data.  This  pointer  must  contain  a  32-bit  clean 
address, 
col orDepth 

The  depth  at  which  the  recompressed  image  is  likely  to  be  viewed. 
Decompressors  may  use  this  as  an  indication  of  the  color  or  grayscale 
resolution  of  the  compressed  image.  If  you  set  this  parameter  to  0,  the  Image 
Compression  Manager  determines  the  appropriate  value  for  the  source  image. 
Values  of  1,  2, 4,  8, 16,  24,  and  32  indicate  the  number  of  bits  per  pixel  for  color 
images.  Values  of  34, 36,  and  40  indicate  2-bit,  4-bit,  and  8-bit  grayscale. 
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respectively,  for  grayscale  images.  Your  program  can  determine  which  depths 
are  supported  by  a  given  compressor  by  examining  the  compressor 
information  structure  returned  by  the  GetCodecInfo  (1-385)  function. 

ctabl e 

A  handle  to  a  custom  color  lookup  table.  Your  program  may  use  this 
parameter  to  indicate  a  custom  color  lookup  table  to  be  used  with  this  image.  If 
the  value  of  the  colorDepth  parameter  is  less  than  or  equal  to  8  and  the  custom 
color  lookup  table  is  different  from  that  of  the  source  pixel  map  (that  is,  the 
ctSeed  field  values  differ  in  the  two  pixel  maps),  the  compressor  remaps  the 
colors  of  the  image  to  the  custom  colors.  If  you  set  the  colorDepth  parameter  to 
16, 24,  or  32,  the  compressor  stores  the  custom  color  table  with  the  compressed 
image.  The  compressor  may  use  the  table  to  specify  the  best  colors  to  use  when 
displaying  the  image  at  lower  bit  depths.  The  compressor  ignores  the  ctabl  e 
parameter  when  colorDepth  is  set  to  33,  34,  36,  or  40.  If  you  set  this  parameter 
to  NIL,  the  compressor  uses  the  color  lookup  table  from  the  source 
ImageDescri pti on  (IV-2285)  structure. 

accuracy 

A  constant  (see  below)  that  defines  the  accuracy  desired  in  the  decompressed 
image.  Values  for  this  parameter  are  on  the  same  scale  as  compression  quality. 
For  a  good  display  of  still  images,  you  should  specify  at  least  codecHi  ghQual  i  ty. 
qual i ty 

A  constant  (see  below)  that  defines  the  desired  compressed  image  quality. 
cType 

A  compressor  type;  see  "Codec  Identifiers"  (IV-2655). 
codec 

Specify  a  particular  compressor  by  setting  this  parameter  to  its  compressor 
identifier.  Alternatively,  you  may  use  a  special  constant  (see  below).  Specifying 
a  component  instance  may  be  useful  if  you  have  previously  set  some  parameter 
on  a  specific  instance  of  a  codec  field  and  want  to  make  sure  that  the  specified 
instance  is  used  for  that  operation. 
dstDD 

A  handle  that  is  to  receive  a  formatted  ImageDescri  pti  on  (IV-2285)  structure. 
The  Image  Compression  Manager  resizes  this  handle  for  the  returned 
ImageDescri  pti  on  (IV-2285)  structure.  Your  application  should  store  this  image 
description  with  the  compressed  image  data. 

dstData 

Points  to  a  location  to  receive  the  compressed  image  data.  It  is  your  program's 
responsibility  to  make  sure  that  this  location  can  receive  at  least  as  much  data 
as  indicated  by  GetMaxCompressi  onSi  ze  (IM20).  The  Image  Compression 
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Manager  places  the  actual  size  of  the  compressed  image  into  the  dataSi  ze  field 
of  the  image  description  referred  to  by  the  dstDD  parameter.  This  pointer  must 
contain  a  32-bit-clean  address. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

accuracy  and  quality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 
codecNormal Quality 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 

codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field, 
codec Los  si essQual  i  ty 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

codec  Constants 

anyCodec 

The  first  compressor  or  decompressor  of  the  specified  type. 
bestSpeedCodec 

The  fastest  compressor  or  decompressor  of  the  specified  type. 
bestFi del i tyCodec 

The  most  accurate  compressor  or  decompressor  of  the  specified  type. 
bestCompressi onCodec 

The  compressor  that  produces  the  smallest  resulting  data. 

Discussion 

The  action  of  this  function  is  essentially  equivalent  to  decompressing  and 
recompressing  the  image.  During  the  decompression  operation,  the  decompressor 
uses  the  srcDD,  srcData,  and  accuracy  parameters.  During  the  subsequent 
compression  operation,  the  compressor  uses  the  col  orDepth,  ctabl  e,  cType,  codec, 
quality,  dstDD,  and  dstData  parameters. 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Pixel  Maps"  (V-2789) 

Related  Java  Methods 

quicktime.std.image.QTIrriage.convertO 


ConvertMovieT  oFile 


Takes  a  specified  movie  (or  a  single  track  within  that  movie)  and  converts  it  into  a 
specified  file  and  type,  supporting  a  Save  As  dialog  box. 


OSErr  ConvertMovieToFile 
Movi  e 
T  rack 
FSSpec 
OSType 
OSType 
Seri ptCode 
short 
1  ong 

Componentlnstance 


( 

theMovi e , 
onlyTrack, 
*outputFi 1 e , 
f i 1 eType , 
creator , 
scri ptTag , 
*resID, 
fl ags , 
userComp  ) ; 


theMovi e 

The  source  movie  for  this  conversion  operation.  Your  application  obtains  this 
movie  identifier  from  such  functions  as  NewMovi  e  (11-1069),  NewMovi eFromFi  1  e 
(11-1080),  and  NewMovi  eFromHandl  e  (11-1084). 
onlyT  rack 

The  track  within  the  source  movie  for  this  conversion  operation.  To  specify  all 
tracks,  set  the  value  of  this  parameter  to  0. 

outputFi 1 e 

A  pointer  to  the  file  specification  for  the  destination  file, 
f i 1 eType 

The  data  type  of  the  destination  file  for  the  movie  specified  in  the  parameter 
theMovi  e. 
creator 

The  creator  value  for  the  output  file  if  it  is  a  new  one. 
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scri ptTag 

The  script  into  which  the  movie  should  be  converted  if  the  output  file  is  a  new 
one.  Use  the  Script  Manager  constant  smSystemScri  pt  to  use  the  system  script; 
use  the  smCurrentScri  pt  constant  to  use  the  current  script.  See  Inside  Macintosh: 
Text  (listed  in  the  bibliography)  for  more  information  about  scripts  and  script 
tags. 
resID 

A  pointer  to  a  field  that  is  to  receive  the  resource  ID  of  the  open  movie.  If  you 
don't  want  to  receive  this  information,  set  the  resID  parameter  to  NIL. 

fl  ags 

Contains  flags  (see  below)  that  control  whether  and  how  the  Save  As  dialog  box 
appears. 
userComp 

If  you  want  a  particular  movie  export  component  to  perform  the  conversion, 
you  may  pass  the  component  or  an  instance  of  that  component  in  this 
parameter.  Otherwise,  set  it  to  0  to  allow  the  Movie  Toolbox  to  use  the 
appropriate  component.  If  you  pass  in  a  component  instance,  it  is  used  by 
ConvertMovieToFile.  This  allows  you  to  communicate  directly  with  the 
component  before  making  this  call  to  establish  any  conversion  parameters.  If 
you  pass  in  a  component  ID,  an  instance  is  created  and  closed  within  this  call. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

flags  Constants 

showUserSetti ngsDi  al  og 

If  this  bit  is  set,  the  Save  As  dialog  box  will  be  displayed  to  allow  the  user  to 
choose  the  type  of  file  to  export  to,  as  well  as  the  file  name  to  export  to. 

movieToFi 1 eOnly Export 

If  this  bit  is  set  and  the  showUserSetti  ngsDi  al  og  bit  is  set,  the  Save  As  dialog  box 
restricts  the  user  to  those  file  formats  that  are  supported  by  movie  data  export 
components, 
movi eFi 1 eSpecVal i d 

If  this  bit  is  set  and  the  showUserSetti  ngsDi  al  og  bit  is  set,  the  name  field  of  the 
outputFile  parameter  is  used  as  the  default  name  of  the  exported  file  in  the 
Save  As  dialog  box. 

Discussion 

Your  application  controls  whether  a  Save  As  dialog  box  appears  by  setting  the  value 
of  the  flags  parameter.  The  dialog  box  lets  the  user  specify  the  file  name  and  type. 
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Supported  types  include  standard  QuickTime  movies,  flattened  movies,  single-fork 
flattened  movies,  and  any  format  that  is  supported  by  a  movie  data  export 
component.  The  following  code  snippets  show  how  to  call  ConvertMovi  eToFi  1  e  to 
provide  a  simple  export  capability  and  how  to  save  a  sound-only  QuickTime  movie 
as  a  WAV  file. 

//  Providing  an  export  capability  with  ConvertMovieToFile 
err  =  ConvertMovieToFile  (theMovie,  /*  identifies  movie  */ 

NIL,  /*  all  tracks  */ 

NIL,  /*  no  output  file  */ 

0,  /*  no  file  type  */ 

0,  /*  no  creator  */ 

-1,  /*  script  */ 

NIL,  /*  no  resource  ID  */ 

createMovi eFi 1 eDel eteCurFi 1 e  | 
showUserSetti ngsDi al og  | 
mo vi eToFi 1 eOnly Export , 

0);  /*  no  specific  component  */ 


//  Saving  a  sound-only  QuickTime  movie  as  a  WAVE  file 
//  See  “Discovering  QuickTime,”  page  257 
void  SndSni p_SaveSoundMovi eAsWAVEFi 1 e  (Movie  theMovie) 
{ 


StandardFi 1 eReply  myReply; 

//  have  the  user  select  the  name  and  location  of  the  new  WAVE  file 
StandardPutFi 1 e( "\pSave  sound  movie  file  as:", 

"\pUntitled.wav",  &myReply); 


if  ( imyReply .sfGood) 
return ; 

//  use  the  default  progress  procedure,  if  any 
SetMovieProgressProcttheMovie,  (MovieProgressUPP)-lL,  0) 
//  export  the  movie  into  a  file 
ConvertMovi eToFi 1 e(  theMovie, 

NIL, 

&myReply .  sf  Fi  1  e  , 
kQTFi 1 eTypeWave , 

F0UR_CHAR„C0DE ( 'TVOD' ) 
smSystemScri pt , 

NIL, 


0L, 


//  the  movie  to  convert 
//  all  tracks  in  the  movie 
//  the  output  file 

//  the  output  file  type 

//  the  output  file  creator 

//  the  script 

//  no  resource  ID 
//  to  be  returned 
//  no  flags 
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} 


NIL)  ; 


//  no  specific  component 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Movie  Functions"  (V-2713) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . convertToFi 1 e( ) 


ConvertTime 


Converts  a  time  obtained  from  one  time  base  into  a  time  that  is  relative  to  another 
time  base. 

void  ConvertTime  ( 

TimeRecord  *inout, 

TimeBase  newBase  ); 

i  nout 

A  pointer  to  a  time  structure  that  contains  the  time  value  to  be  converted.  The 
ConvertTime  function  replaces  the  contents  of  this  time  structure  with  the  time 
value  relative  to  the  specified  time  base. 

newBase 

The  time  base  for  this  operation.  Your  application  obtains  this  time  base 
identifier  from  the  NewTimeBase  (11-1119)  function. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Discussion 

This  function  includes  the  rate  associated  with  each  time  value  in  the  conversion; 
therefore,  you  should  use  this  function  when  you  want  to  convert  time  values.  Both 
time  bases  must  rely  on  the  same  time  source,  and  you  must  specify  the  time  to  be 
converted  in  a  time  structure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Times"  (V-2762) 
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Related  Java  Methods 

qui  ckti  me .  std .  cl  ocks  .Time  Record .  convertin'  me  ( ) 

See  Also 

Use  ConvertTimeScale  (1-138)  to  convert  durations. 


ConvertTimeScale 

Converts  a  time  from  one  time  scale  into  a  time  that  is  relative  to  another  time  scale. 

void  ConvertTimeScale  ( 

TimeRecord  *inout, 

TimeScale  newScale  ); 

i  nout 

A  pointer  to  a  time  structure  that  contains  the  time  value  to  be  converted. 
ConvertTimeScale  replaces  the  contents  of  this  time  structure  with  the  time 
value  relative  to  the  specified  time  scale. 

newScal e 

The  time  scale  for  this  operation. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (W494). 

Discussion 

This  function  does  not  include  the  rate  associated  with  the  time  value  in  the 
conversion;  therefore,  you  should  use  this  function  when  you  want  to  convert  time 
durations,  but  not  when  converting  time  values. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Times"  (V-2762) 

Related  Java  Methods 

qui ckti me . std . cl ocks .TimeRecord . con vertTi meScal e( ) 

See  Also 

Use  ConvertT i  me  (1-137)  to  convert  time  values. 
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CopyMatrix 


Copies  the  contents  of  one  matrix  into  another  matrix. 

void  CopyMatrix  ( 

const  MatrixRecord  *ml, 

MatrixRecord  *m2  ); 


ml 

The  source  matrix  for  the  copy  operation. 
m2 

A  pointer  to  the  destination  matrix  for  the  copy  operation.  CopyMatrix  copies 
the  values  from  the  matrix  specified  by  the  ml  parameter  into  this  matrix. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Matrices"  (V-2764) 

Related  Java  Methods 

qui ckti me . std . image . Matrix. copy () ,  qui ckti me . std . image . Matrix. cl  one ( ) 


CopyMovieSelection 

Creates  a  new  movie  that  contains  the  original  movie's  current  selection. 

Movie  CopyMovieSelection  ( 

Movie  theMovie  ); 

theMovi e 

The  source  movie  for  this  operation.  Your  application  obtains  this  movie 
identifier  from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080), 
and  NewMovi  eFromHandl  e  (11-1084). 

function  result  The  new  movie. 

Discussion 

This  function  creates  a  new  movie  from  the  source  movie's  current  selection,  but 
does  not  change  the  source  movie  or  the  selection.  If  you  have  assigned  a  progress 
function  to  the  source  movie,  the  Movie  Toolbox  calls  that  progress  function  during 
long  copy  operations. 
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Special  Considerations 

Your  application  must  dispose  of  the  new  movie  once  you  are  done  with  it,  using 
DisposeMovie  (1-268). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "High-Level  Movie  Editing  Functions"  (V-2746) 

Related  Java  Methods 

qu ickti me. std. mo vies. Mo vie. copy Selection!) 


CopyMovieSettings 


Copies  many  settings  from  one  movie  to  another,  overwriting  the  destination 
settings  in  the  process. 

OSErr  CopyMovieSettings  ( 

Movie  srcMovie, 

Movi  e  dstMovi e  ) ; 

srcMovi e 

The  source  movie  for  this  operation.  Your  application  obtains  this  movie 
identifier  from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080), 
and  NewMovieFromHandl  e  (11-1084). 
dstMovi e 

The  destination  movie  for  this  operation.  The  CopyMovi  eSetti  ngs  function  uses 
the  settings  from  the  source  movie,  which  is  specified  by  the  srcMovie 
parameter,  to  replace  the  current  settings  of  this  movie. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

Use  this  function  to  copy  certain  important  settings  from  one  movie  to  another.  It 
copies  the  preferred  rate  and  volume,  source  clipping  region,  matrix  information, 
and  user  data;  it  does  not  copy  the  movie's  contents.  To  work  with  movie  contents, 
you  should  use  segment  editing  functions. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


1-140 


Inside  QuickTime:  Functions  A-H 


CopyTrackSettings 


Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Low-Level  Movie  Editing  Functions"  (V-2749) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . copy Sett i ngs ( ) 


See  Also 

If  you  want  to  work  with  specific  movie  characteristics,  you  can  use  the  Movie 
Toolbox  functions  that  allow  you  to  manipulate  movie  settings  individually.  For 
example,  you  use  InsertMovieSegment  (11-762)  to  copy  a  segment  from  one  movie  to 
another  and  InsertEmptyMovi  eSegment  (11-759)  to  insert  an  empty  segment  into  a 
movie.  You  delete  a  segment  from  a  movie  by  calling  Del  eteMovi  eSegment  (1-250),  or 
change  a  segment's  duration  by  calling  Seal  eMovi  eSegment  (III— 1528).  These 
functions  are  described  in  the  discussion  section  of  SetMovi  eGWorl  d  (III— 1619). 


CopyT  rackSettings 


Copies  many  settings  from  one  track  to  another,  overwriting  the  destination 
settings. 

OSErr  CopyTrackSettings  ( 

Track  srcTrack, 

Track  dstTrack  ); 

srcTrack 

The  source  track  for  this  operation.  Your  application  obtains  this  track  identifier 
from  such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eTrack  (1-497). 

dstT  rack 

The  destination  track  for  this  operation.  The  CopyT rackSetti  ngs  function  uses 
the  settings  from  the  source  track,  which  you  specify  with  the  srcTrack 
parameter,  to  replace  the  current  settings  of  this  track. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

This  function  copies  matrix  information,  track  volume,  the  clipping  region,  user 
data,  matte  information,  media  language,  quality,  user  data,  and  other 
media-specific  settings  (such  as  sound  balance  and  video  graphics  mode).  It  does 
not  copy  any  alternate  group  information  pertaining  to  the  track.  This  function  does 
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not  copy  the  track's  contents.  To  work  with  track  contents,  you  should  use 
segment-editing  functions. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Editing  Tracks"  (V-2750) 

Related  Java  Methods 

qu ickti me. std. mo vies. Track. copy Sett  ingsO 


See  Also 

If  you  want  to  work  with  specific  track  characteristics,  you  can  use  the  Movie 
Toolbox  functions  that  allow  you  to  manipulate  track  settings  individually.  These 
functions  are  described  in  SetMovi  eGWorl  d  (III— 1619). 


CountComponentlnstances 


Allows  you  to  determine  the  number  of  open  connections  being  managed  by  a 
specified  component. 

long  CountComponentlnstances  ( 

Component  aComponent  ) ; 


aComponent 

A  component  instance.  Your  application  obtains  the  component  instance  from 
OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 


function  result  The  number  of  open  connections  being  managed  by  the  specified 
component. 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 

Related  Java  Methods 

qui ckti me . std . comp . Component . count! ) 
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CountComponents 


Determines  the  number  of  registered  components  that  meet  a  given  set  of  criteria. 

long  CountComponents  ( 

ComponentDescri pti on  *looking  ); 


1  ooki  ng 

A  ComponentDescri  pti  on  (IV-2212)  record.  Your  application  specifies  the 
criteria  for  the  component  search  in  the  fields  of  this  record.  If  you  set  all  the 
fields  to  0,  the  Component  Manager  returns  the  total  number  of  QuickTime 
components  registered  in  the  system. 


function  result  The  number  of  registered  components  that  meet  the  given  selection 
criteria 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Component  Functions  Used  By  Applications"  (V-2781) 

Related  Java  Methods 

qui cktime . std . comp . ComponentDescri pti on . count ( ) 


Court  tlmageDescriptionExtensionType 


Counts  the  number  of  extensions  of  a  given  type  in  an  ImageDescri  pti  onHandl  e. 

OSErr  CountlmageDescri pti onExtensi onType  ( 

ImageDescri pti onHandl e  desc, 

long  idType, 

long  *count  ); 


desc 

A  handle  to  the  ImageDescri  pti  on  (IV-2285)  structure  with  the  extensions  to  be 
counted, 
i dType 

Indicates  the  type  of  extension  to  be  counted  in  the  specified  ImageDescri  pti  on 
(IV-2285)  structure.  Set  the  value  of  this  parameter  to  0  to  match  any  extension, 
and  return  a  count  of  all  of  the  extensions. 
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count 

A  pointer  to  an  integer  that  indicates  how  many  extensions  of  the  given  type 
are  in  the  given  ImageDescri  pti  on  (IV-2285)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

When  used  with  GetNextlmageDescri  pti  onExtensi  onType  (1-501),  this  function 
allows  the  application  to  determine  the  total  set  of  extensions  present  in  the 
ImageDescription  (IV-2285)  structure  designated  by  d e s c . 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Image  Descriptions"  (V-2790) 


CountUserDataType 


Determines  the  number  of  items  of  a  given  type  in  a  user  data  list. 

short  CountUserDataType  ( 

UserData  theUserData, 

OSType  udType  ) ; 

theUserData 

The  user  data  list  for  this  operation.  You  obtain  this  list  reference  by  calling  the 
GetMovi eUserData  (1-499),  GetT rackUserData  (1-546),  or  GetMedi aUserData 
(1-456)  functions. 

udType 

The  type.  The  Movie  Toolbox  determines  the  number  of  items  of  this  type  in  the 

user  data  list. 

function  result  The  number  of  items  of  the  given  type  in  the  user  data  list. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  User  Data"  (V-2743) 

Related  Java  Methods 

qu ickti me. std. mo vies. media. User Da ta.countTypeO 
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CreateMovieFile 


Creates  a  movie  file,  creates  an  empty  movie  which  references  the  file,  and  opens 
the  movie  file  with  write  permission. 


OSErr  CreateMovieFile  ( 


const  FSSpec 
OSType 
Seri ptCode 
1  ong 
short 
Movi  e 


*fi 1 eSpec , 
creator , 
scri ptTag , 

createMovi eFi 1 eFl ags , 
*resRefNum, 

*newmovie  ); 


f i 1 eSpec 

A  pointer  to  the  file  system  specification  for  the  movie  file  to  be  created, 
creator 

The  creator  value  for  the  new  file, 
scri ptTag 

The  script  in  which  the  movie  file  should  be  created.  Use  the  Script  Manager 
constant  smSystemScript  to  use  the  system  script;  use  the  smCurrentScri pt 
constant  to  use  the  current  script.  See  Inside  Macintosh:  Text  (listed  in  the 
bibliography)  for  more  information  about  scripts  and  script  tags. 

createMovi eFi 1 eFl ags 

Controls  movie  file  creation  flags  (see  below). 
resRefNum 

A  pointer  to  a  field  that  is  to  receive  the  file  reference  number  for  the  opened 
movie  file.  Your  application  must  use  this  value  when  calling  other  Movie 
Toolbox  functions  that  work  with  movie  files.  If  you  set  this  parameter  to  NI L, 
the  Movie  Toolbox  creates  the  movie  file  but  does  not  open  the  file, 
newmovi e 

A  pointer  to  a  field  that  is  to  receive  the  identifier  of  the  new  movie. 
CreateMovi  eFi  1  e  returns  the  identifier  of  the  new  movie.  If  the  function  could 
not  create  a  new  movie,  it  sets  this  returned  value  to  NIL.  If  you  set  this 
parameter  to  NIL,  the  Movie  Toolbox  does  not  create  a  movie. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 
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createMovieFileFlags  Constants 

createMovieFileDontCreateResFile 

Use  this  flag  to  create  a  single-fork  movie  file  that  will  contain  the  movie  in  its 
data  fork.  The  movie  file  will  not  contain  a  resource  fork.  On  non-Macintosh 
systems,  no  resource  file  will  be  created.  You  must  store  a  movie  in  the  data  fork 
of  any  file  that  has  been  created  with  this  flag.  In  addition,  attention  must  be 
paid  to  the  resRef Num  and  resld  parameters  when  calling  AddMovi  eResource 
(1-36)  or  UpdateMovi  eResource  (III— 1983)  on  files  created  with  this  flag. 

createMovi eFi 1 eDel eteCurFi 1 e 

Indicates  whether  to  delete  an  existing  file.  If  you  set  this  flag  to  1,  the  Movie 
Toolbox  deletes  the  file  (if  it  exists)  before  creating  the  new  movie  file.  If  you  set 
this  flag  to  0  and  the  file  specified  by  the  f  i  1  eSpec  parameter  already  exists,  the 
Movie  Toolbox  uses  the  existing  file.  In  this  case,  the  toolbox  ensures  that  the 
file  has  both  a  data  and  a  resource  fork. 
createMovi eFi leDontCreateMo vie 

Controls  whether  CreateMovi  eFi  1  e  creates  a  new  movie  in  the  movie  file.  If  you 
set  this  flag  to  1,  the  Movie  Toolbox  does  not  create  a  movie  in  the  new  movie 
file.  In  this  case,  the  function  ignores  the  newmovi  e  parameter.  If  you  set  this  flag 
to  0,  the  Movie  Toolbox  creates  a  movie  and  returns  the  movie  identifier  in  the 
field  referred  to  by  the  newmovi  e  parameter. 
createMovi  eFi  leDontOpenFile 

Controls  whether  CreateMovi  eFi  1  e  opens  the  new  movie  file.  If  you  set  this  flag 
to  1,  the  Movie  Toolbox  does  not  open  the  new  movie  file.  In  this  case,  the 
function  ignores  the  resRef  Num  parameter.  If  you  set  this  flag  to  0,  the  Movie 
Toolbox  opens  the  new  movie  file  and  returns  its  reference  number  into  the 
field  referred  to  by  the  resRefNum  parameter. 

newMovi eActi ve 

Controls  whether  the  new  movie  is  active.  Set  this  flag  to  1  to  make  the  new 
movie  active.  A  movie  that  does  not  have  any  tracks  can  still  be  active.  When 
the  Movie  Toolbox  tries  to  play  the  movie,  no  images  are  displayed,  because 
there  is  no  movie  data.  You  can  make  a  movie  active  or  inactive  by  calling 
SetMovi  eActi  ve  (III — 1609). 
newMovi eDontAutoAlternate 

Controls  whether  the  Movie  Toolbox  automatically  selects  enabled  tracks  from 
alternate  track  groups.  If  you  set  this  flag  to  1,  the  Movie  Toolbox  does  not 
automatically  select  tracks  for  the  movie;  you  must  enable  tracks  yourself. 

Discussion 

The  following  code  snippet  shows  how  CreateMovi  eFi  le  maybe  used  to  create  and 
open  a  QuickTime  movie  file. 
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CreateMovieFile 


//  CreateMovieFile  coding  example 
//  See  “Discovering  QuickTime,"  page  243 
void  CreateMyCool Movi e  (void) 

{ 

StandardFi 1 eReply  sfr; 

Movie  movie  =  NIL; 

FSSpec  fss; 

short  nFileRefNum  =  0; 

short  nResID  =  movielnDataForkResID; 

StandardPutFi 1 e( "\pEnter  movie  file  name:",  "\punti tl ed .mov" ,  &sfr); 
if  ( ! sf r . sfGood ) 
return ; 

CreateMovi eFile(&sfr.sfFile, 

F0UR_CHAR_C0DE( 'TVOD' ) , 
smCurrentScri pt , 
createMovi eFi 1 eDel eteCurFi 1 e  | 
createMovi eFi 1 eDontC reate Res Fi 1 e , 

&nFi 1 eRefNum, 

&movi e) ; 

CreateMyVideoTrack(movie) ;  //  See  “Discovering  QuickTime,”  page  244 
CreateMySoundTrack(movie) ;  //  See  “Discovering  QuickTime,”  page  250 

AddMovi eResource(movi e ,  nFileRefNum,  &nResID,  NIL); 
if  ( n F i 1 eRefNum  !=  0) 

Cl oseMovi eFi 1 e( n  F i 1 eRef Num) ; 

Di sposeMovie (movie) ; 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Movie  Functions"  (V-2713) 

Related  Java  Methods 

qui ckti me . i o . QT  Fi 1 e . createMovi eFi  1  e( ) , 
qui ckti me . std .movi es . Movi e . createMovi eFi  1  e( ) 
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CreatePortAssociation 


See  Also 

Your  application  can  use  the  functions  described  in  NewMovi  eTrack  (11-1092)  to  place 
movie  data  into  the  new  movie  file. 


CreatePortAssociation 


Associates  a  data  structure  of  type  GrafPort  with  an  onscreen  native  window. 

GrafPtr  CreatePortAssociation  ( 
void  *theWnd, 

Ptr  storage, 

1 ong  f 1 ags  ) ; 

theWnd 

Native  window  to  associate  the  GrafPort  (IV-2273)  with.  In  Windows,  this 
parameter  represents  the  movie  HWND. 

storage 

Pointer  to  optional  storage  space  you  allocate  for  the  graphics  port.  If  you  pass 
N I L,  QuickTime  allocates  the  space  for  you. 

fl  ags 

Flags  (see  below)  that  determine  how  events  will  be  handled. 

function  result  A  pointer  to  a  Graf  Port  (IV-2273)  structure. 

flags  Constants 

kQTMLHandl ePortEvents 

Asks  QTML  to  handle  events. 
kQTMLNoIdl eEvents 

Asks  QTML  not  to  send  idle  events.  If  you  set  this  flag,  QuickTime  will  not  pass 
periodic  idle  messages  to  the  WndProc  associated  with  this  window.  In  this  case 
it  is  your  responsibility  to  task  any  movies  playing  in  this  window.  When  this 
flag  is  not  set,  QuickTime  makes  sure  the  WndProc  associated  with  the  onscreen 
window  gets  periodic  idle  messages  so  your  code  can  in  turn  idle  any  movie 
controllers  contained  within  that  window. 

Discussion 

This  function  associates  a  QuickDraw  graphics  port  with  an  onscreen  window.  The 
graphics  port  provides  a  drawing  context  for  QuickTime  and  QuickDraw.  In 
addition,  QuickTime  hooks  the  native  window,  so  that  any  window  state  changes 
are  reflected  in  the  associated  graphics  port. 

//  Registering  a  QuickTime  movie  window  in  Windows 
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//  See  “Discovering  QuickTime, 
LRESULT  CALLBACK  WndProc 
( HWND  hwnd , 

UINT  i Msg , 

WPARAM  wParam, 

LPARAM  IParam) 

{ 


page  228 

//  Handle  to  window 
//  Message  type 

//  Message-dependent  parameter 
//  Message-dependent  parameter 


switch  (iMsg)  { 

case  WM_CREATE : 

CreatePortAssoci ati on( hwnd ,  NIL,  OL); 
break; 


}  //  end  switch  (l'Msg) 

}  //  end  WndProc 

Special  Considerations 

Before  you  dispose  of  the  native  window,  call  DestroyPortAssoci  ati  on  (1-254). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML .  h 


CreateShortcutMovieFile 


Creates  a  movie  file  that  just  contains  a  reference  to  another  movie. 


OSErr  CreateShortcutMovieFile  ( 


const  FSSpec 
OSType 
Seri ptCode 
1  ong 
Handl e 
OSType 


*fi 1 eSpec , 
creator , 
scri ptTag , 

createMovi eFi 1 eFl ags , 
targetDataRef , 
targetDataRefType  ); 


f i 1 eSpec 

A  pointer  to  the  file  system  specification  for  the  movie  file  to  be  created, 
creator 

The  creator  value  for  the  new  file. 
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scri ptTag 

The  script  in  which  the  movie  file  should  be  created.  Use  the  Script  Manager 
constant  smSystemScri  pt  to  use  the  system  script;  use  the  smCurrentScri  pt 
constant  to  use  the  current  script.  See  Inside  Macintosh:  Text  (listed  in  the 
bibliography)  for  more  information  about  scripts  and  script  tags. 
createMovieFileFlags 

Contains  movie  file  creation  flags  (see  below). 
targetDataRef 

A  handle  to  the  data  referred  to  by  the  movie  that  this  function  creates, 
target Data RefType 

The  type  of  the  data  referred  to  by  the  movie  that  this  function  creates;  see 
"Data  References"  (IV-2661). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

createMovieFileFlags  Constants 

flatten AddMo vieTo Da taFork 

Causes  the  movie  to  be  placed  in  the  data  fork  of  the  new  movie  file,  as  well  as 
in  the  resource  fork.  You  may  use  this  flag  to  create  movie  files  that  are  more 
easily  moved  to  computer  systems  other  than  the  Macintosh. 

flattenDontlnterleaveFlatten 

Allows  you  to  disable  the  Movie  Toolbox's  data  storage  optimizations.  By 
default,  the  Movie  Toolbox  stores  movie  data  in  a  format  that  is  optimized  for 
playback.  Set  this  flag  to  1  to  disable  these  optimizations, 
fl atten Ac tiveT racks Only 

Causes  the  Movie  Toolbox  to  add  only  enabled  movie  tracks  to  the  new  movie 
file.  Use  SetTrackEnabl  ed  (III— 1658)  to  enable  and  disable  movie  tracks, 
f 1 attenCompressMovi e Resource 

Compresses  the  movie  resource  stored  in  the  file's  data  fork,  but  not  the  movie 
resource  stored  in  the  resource  fork  on  Mac  OS  systems, 
fl atten FSSpecPtrls Data  Ref RecordPtr 

Set  this  flag  to  1  if  the  FSSpec  pointer  is  a  pointer  to  a  DataReferenceRecord 
(IV-2233)  structure.  This  capability  enables  you  to  flatten  movies  for  devices 
other  than  file  systems. 
flattenForceMovi eResourceBeforeMovi eData 

Set  this  flag  when  you  are  creating  a  fast  start  movie,  to  put  the  movie  resource 
at  the  front  of  the  resulting  movie  file. 
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Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Related  Java  Methods 

qui cktime . i o . QTFi 1 e . createShortcutMovi eFi  1  e( ) 


Curve  Add  AtomT  o  VectorStream 


Adds  an  atom  to  a  vector  data  stream. 

ComponentResul t  CurveAddAtomToVectorStream  ( 

Componentlnstance  effect, 

OSType  atomType, 

Size  atomSize, 

void  *pAtomData, 

Handle  vectorStream  ); 

effect 

The  instance  of  the  QuickTime  vector  codec  component  for  the  request.  Your 
software  obtains  this  reference  when  calling  the  Component  Manager's 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131)  function. 

atomType 

The  type  of  atom  to  add  to  the  vector  data  stream. 

atomSi ze 

The  size  of  the  data  for  the  atom. 
pAtomData 

A  pointer  to  the  data  for  the  atom. 
vectorStream 

A  handle  to  the  vector  data  stream  to  which  to  add  the  atom. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  adds  the  atom  to  the  end  of  the  specified  vector  data  stream  and 
resizes  the  vector  data  stream  handle. 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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CurveAddPathAtomToVectorStream 


Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Vector  Codec  Component  Functions"  (V-2899) 


Curve  AddPath  AtomT  o  V  ectorStream 


Adds  a  path  to  a  vector  data  stream. 

ComponentResul t  CurveAddPathAtomToVectorStream  ( 

Componentlnstance  effect, 

Handle  pathData, 

Handle  vectorStream  ); 

effect 

The  instance  of  the  QuickTime  vector  codec  component  for  the  request.  Your 
software  obtains  this  reference  when  calling  the  Component  Manager's 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131)  function. 

pathData 

A  handle  to  the  data  for  the  path. 
vectorStream 

A  handle  to  the  vector  data  stream  to  which  to  add  the  path. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  adds  the  path  to  the  end  of  the  specified  vector  data  stream  and 
resizes  the  vector  data  stream  handle. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Vector  Codec  Component  Functions"  (V-2899) 


Curve  AddZero  AtomT  o  VectorStream 


Adds  a  kCurveEndAtom  to  a  vector  data  stream;  this  atom  marks  the  end  of  the  vector 
data  stream, 

ComponentResul t  CurveAddZeroAtomToVectorStream  ( 

Componentlnstance  effect, 
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Handle  vectorStream  ); 

effect 

The  instance  of  the  QuickTime  vector  codec  component  for  the  request.  Your 
software  obtains  this  reference  when  calling  the  Component  Manager's 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131)  function. 

vectorStream 

A  handle  to  the  vector  data  stream  to  which  to  add  the  kCurveEndAtom  atom. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  adds  a  kCurveEndAtom  atom  to  the  end  of  the  specified  vector  data 
stream  and  resizes  the  vector  data  stream  handle.  The  kCurveEndAtom  atom  is 
required  at  the  end  of  a  vector  data  stream,  and  there  may  be  only  one 
kCurveEndAtom  atom  in  the  stream. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Vector  Codec  Component  Functions"  (V-2899) 


CurveCountPointsInPath 


Counts  the  points  along  either  one  of  a  path's  contours  or  all  of  its  contours. 


Component  Res ul t  CurveCountPoints InPath 
Componentlnstance  effect, 
gxPaths  *aPath, 

unsigned  long  contourlndex, 

unsigned  long  *pCount  ); 


( 


effect 

The  instance  of  the  QuickTime  vector  codec  component  for  the  request. 
aPath 

A  pointer  to  the  path, 
contourlndex 

The  index  of  the  contour  to  be  counted. 
pCount 

A  pointer  to  a  field  that  is  to  receive  the  number  of  points  in  the  contour  or  path. 
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CurveCreateVectorStream 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Vector  Codec  Component  Functions"  (V-2899) 


CurveCreate  V  ectorStream 


Creates  a  new,  empty  vector  data  stream. 

ComponentResul t  CurveCreateVectorStream  ( 

Componentlnstance  effect, 

Handl  e  *pStream  ) ; 

effect 

The  instance  of  the  QuickTime  vector  codec  component  for  the  request.  Your 
software  obtains  this  reference  when  calling  the  Component  Manager's 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131)  function. 

pStream 

A  pointer  to  the  handle  that  is  to  receive  the  newly  created  vector  data  stream. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  caller  is  responsible  for  disposing  of  the  stream  when  finished  with  it.  This  can 
be  done  by  calling  Di  sposeHandl  e. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.  h 

Programming  summary:  "Vector  Codec  Component  Functions"  (V-2899) 


CurveGetAtomDataFromVectorStream 


Finds  the  first  atom  of  a  specified  type  within  a  vector  data  stream  and  get  its  data. 

ComponentResul t  CurveGetAtomDataFromVectorStream  ( 

Componentlnstance  effect, 

Handle  vectorStream , 
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long  atomType, 

long  *dataSize, 

Ptr  *dataPtr  ); 

effect 

The  instance  of  the  QuickTime  vector  codec  component  for  the  request.  Your 
software  obtains  this  reference  when  calling  the  Component  Manager's 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131)  function. 
vectorStream 

A  handle  to  the  vector  data  stream  from  which  to  get  the  atom. 
atomType 

The  type  of  atom  to  find. 
dataSi ze 

A  pointer  to  a  field  that  is  to  receive  the  size  of  the  atom's  data. 
dataPtr 

A  pointer  to  a  pointer  to  a  field  that  is  to  receive  the  atom's  data. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Before  calling  this  function,  your  software  must  lock  the  handle  for  the  vector  data 
stream  (with  Macintosh,  by  calling  HLock).  This  prevents  the  handle  from  being 
moved,  which  could  invalidate  the  pointer  to  the  atom  data  before  your  software 
gets  the  data. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Vector  Codec  Component  Functions"  (V-2899) 


CurveGetLength 


Calculates  the  length  of  one  of  a  path's  contours  or  the  sum  of  the  lengths  of  all  of 
its  contours. 

ComponentResul t  CurveGetLength  ( 

Componentlnstance  effect, 
gxPaths  *target, 

long  index, 

wide  *wideLength  ); 
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CurveG  etNearestPathPoint 


effect 

The  instance  of  the  QuickTime  vector  codec  component  for  the  request.  Your 
software  obtains  this  reference  when  calling  the  Component  Manager's 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131)  function, 
target 

A  pointer  to  the  path, 
i  ndex 

Contains  the  index  of  the  contour  whose  length  is  to  be  calculated  or,  if  the 
value  is  0,  specifies  to  calculate  the  lengths  of  all  of  the  path's  contours  and 
return  the  sum  of  the  lengths, 
wi deLength 

A  pointer  to  a  field  that  is  to  receive  the  length. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Vector  Codec  Component  Functions"  (V-2899) 


CurveGetNearestPathPoint 


Finds  the  closest  point  on  a  path  to  a  specified  point. 


Component Res ul t  CurveGetNearestPathPoint 


Componentlnstance 
gxPaths 
Fi xedPoi nt 
unsigned  long 
unsigned  long 
Fi  xed 


effect , 

*aPath , 

*thePoi nt , 
*contourIndex , 
*poi ntlndex , 
*theDelta  ); 


( 


effect 

The  instance  of  the  QuickTime  vector  codec  component  for  the  request.  Your 
software  obtains  this  reference  when  calling  the  Component  Manager's 
OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131)  function. 

aPath 

A  pointer  to  the  path. 
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thePoi nt 

A  pointer  to  a  point  for  which  to  find  the  closest  point  on  the  path, 
contourlndex 

A  pointer  to  a  field  that  is  to  receive  the  index  of  the  contour  that  contains  the 
closest  point, 
poi ntlndex 

A  pointer  to  a  field  that  is  to  receive  the  index  of  the  closest  point. 
theDel ta 

A  pointer  to  a  field  that  is  to  receive  the  distance  between  the  specified  point 
and  the  closest  point  in  the  contour  to  it. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

In  programs  where  users  directly  manipulate  curves,  you  can  use  this  function  to 
determine  the  closest  control  point  to  a  given  point. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Vector  Codec  Component  Functions"  (V-2899) 


CurveGetPathPoint 


Obtains  a  point  from  a  path  and  to  find  out  if  the  point  is  on  the  curve. 


ComponentResul t  CurveGetPathPoint  ( 


Componentlnstance 
gxPaths 
unsigned  long 
unsigned  long 
gxPoi nt 
Bool ean 


effect , 

*aPath , 
contourlndex, 
poi ntlndex, 
*thePoi nt , 
*pt!sOnPath  ); 


effect 

The  instance  of  the  QuickTime  vector  codec  component  for  the  request.  Your 
software  obtains  this  reference  when  calling  the  Component  Manager's 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131)  function. 

aPath 

A  pointer  to  the  path. 
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CurvelnsertPointlntoPath 


contourlndex 

The  index  of  the  contour  from  which  to  get  the  point, 
poi ntlndex 

The  index  of  the  point  to  get. 
thePoi nt 

A  pointer  to  a  field  that  is  to  receive  the  point. 
ptlsOnPath 

A  pointer  to  a  field  that  is  to  receive  a  Boolean  value  that,  if  TRUE,  specifies  that 
the  point  is  on  the  curve. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  lets  programs  get  a  single  point  from  a  path  without  walking  the  path 
data. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.  h 

Programming  summary:  "Vector  Codec  Component  Functions"  (V-2899) 

See  Also 

For  the  corresponding  set  function,  see  CurveSetPathPoi  nt  (1-162). 


CurvelnsertPointlntoPath 


Adds  a  new  point  to  a  path. 


ComponentResul t  Curve 
Componentlnstance 
gxPoi nt 
Handl e 

unsigned  long 
unsigned  long 
Bool ean 


InsertPoi ntlntoPath  ( 
effect , 

*aPoi nt , 
thePath , 
contourlndex , 
poi ntlndex , 
ptlsOnPath  ) ; 


effect 

The  instance  of  the  QuickTime  vector  codec  component  for  the  request.  Your 
software  obtains  this  reference  when  calling  the  Component  Manager's 
OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131)  function. 
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aPoi nt 

A  pointer  to  the  point  to  add  to  the  path. 
thePath 

A  handle  to  the  path  to  which  to  add  the  point, 
contourlndex 

The  index  of  the  path  contour  to  which  to  add  the  point, 
poi ntlndex 

The  index  of  the  point  to  add. 
ptlsOnPath 

If  TRUE,  specifies  that  the  new  point  is  to  be  on  the  path. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  best  for  adding  a  single  point  to  a  path  rather  than  large  numbers  of 
points. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Vector  Codec  Component  Functions"  (V-2899) 


CurveLengthT  oPoint 


Obtains  the  point  at  a  specified  distance  along  a  curve. 


ComponentResul t  CurveLengthToPoint  ( 


Componentlnstance 
gxPaths 
1  ong 
Fi  xed 

Fi  xedPoi  nt 
Fi xedPoi nt 


effect , 
*target, 
i ndex, 

1 ength , 

*1 ocati on 
*tangent 


); 


effect 

The  instance  of  the  QuickTime  vector  codec  component  for  the  request.  Your 
software  obtains  this  reference  when  calling  the  Component  Manager's 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131)  function, 
target 

A  pointer  to  the  path. 
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CurveN  ewPath 


i  ndex 

The  index  of  the  path  contour  from  which  to  get  the  point. 

1 ength 

The  distance  along  the  curve  at  which  to  find  the  point. 

1 ocati on 

A  pointer  to  a  field  that  is  to  receive  the  point, 
tangent 

A  pointer  to  a  field  that  is  to  receive  a  point  that  is  tangent  to  the  point  at  the 
specified  distance. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  useful  for  converting  a  value  to  a  point,  such  as  when  creating  an 
animation  that  follows  a  curve. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.  h 

Programming  summary:  "Vector  Codec  Component  Functions"  (V-2899) 


CurveNewPath 


Creates  a  new  path. 

ComponentResul t  CurveNewPath  ( 

Componentlnstance  effect, 

Handle  *pPath  ); 

effect 

The  instance  of  the  QuickTime  vector  codec  component  for  the  request.  Your 
software  obtains  this  reference  when  calling  the  Component  Manager's 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131)  function. 

pPath 

A  pointer  to  a  handle  that  is  to  receive  the  new  path. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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CurvePathPointToLength 


Discussion 

The  path  created  by  this  function  contains  one  contour  and  no  points.  The  caller 
must  dispose  of  the  handle  when  it  is  finished  with  it  (with  Macintosh,  by  calling 
Di  sposeHandl  e). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Vector  Codec  Component  Functions"  (V-2899) 


CurvePathPointT  oLength 


Obtains  the  length  of  a  path  between  specified  starting  and  ending  distances  that  is 
nearest  a  point. 


Component Res ui t  CurvePathPointToLength 


Componentlnstance 
gxPaths 
Fi  xed 
Fi  xed 

Fi xedPoi nt 
Fi  xed 


ci  , 

*aPath , 
startDi st, 
endDi st , 
*thePoi nt , 
*pLength  ); 


( 


ci 

The  instance  of  the  QuickTime  vector  codec  component  for  the  request.  Your 

software  obtains  this  reference  when  calling  the  Component  Manager's 

OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131)  function. 
aPath 

A  pointer  to  the  path. 
startDi st 

The  distance  along  the  path  at  which  to  start  measuring  the  path's  length. 
endDi st 

The  distance  along  the  path  at  which  to  stop  measuring  the  path's  length. 
thePoi nt 

A  pointer  to  a  point;  the  function  measures  the  path  closest  to  this  point. 
pLength 

A  pointer  to  a  field  that  is  to  receive  the  length  of  the  specified  part  of  the  path. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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Curve  S  et  PathPoint 


Discussion 

You  can  use  this  function  to  test  if  the  user  has  clicked  on  the  specified  portion  of 
the  curve. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Vector  Codec  Component  Functions"  (V-2899) 


CurveSetPathPoint 


Changes  the  location  of  a  point  in  a  path. 


ComponentResul t  CurveSetPathPoint  ( 


Componentlnstance 
gxPaths 
unsigned  long 
unsigned  long 
gxPoi nt 
Bool ean 


effect , 

*aPath , 
contourlndex , 
poi ntlndex , 
*thePoi nt , 
ptlsOnPath  ) ; 


effect 

The  instance  of  the  QuickTime  vector  codec  component  for  the  request.  Your 

software  obtains  this  reference  when  calling  the  Component  Manager's 

OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131)  function. 
aPath 

A  pointer  to  the  path, 
contourlndex 

The  index  of  the  path  contour  that  contains  the  point  to  change, 
poi ntlndex 

The  index  of  the  point  to  change. 
thePoi nt 

A  pointer  to  the  new  value  for  the  point. 
ptlsOnPath 

If  TRUE,  specifies  that  the  new  point  is  to  be  on  the  path. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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CustomGetFilePreview 


Discussion 

This  function  edits  an  existing  point  location  within  a  path.  The  function  that  you 
call  to  send  the  interpolated  value  to  the  receiving  track  is  defined  as  a  universal 
procedure  in  systems  that  support  the  Macintosh  Code  Fragment  Manager  (CFM) 
or  is  defined  as  a  data  procedure  for  non-CFM  systems.  With  Macintosh,  the 
TweenerDataUPP  function  pointer  specifies  the  function  the  tween  component  calls 
with  the  value  generated  by  the  tween  operation.  A  tween  component  calls  this 
function  from  its  implementation  of  the  TweenerDoTween  (III— 1976)  function.  You  call 
this  function  by  invoking  the  function  specified  in  the  tween  record's  dataProc  field. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Vector  Codec  Component  Functions"  (V-2899) 

See  Also 

For  the  corresponding  get  function,  see  CurveGetPathPoi  nt  (1-157). 


CustomGetFilePreview 


Presents  an  Open  dialog  box  to  the  user  and  allows  the  user  to  view  file  previews. 


void  CustomGetFilePreview  ( 
FileFilterYDUPP 
short 

ConstSFTypeLi stPtr 
StandardFi 1 eReply 
short 
Poi  nt 

DlgHookYDUPP 
Modal FilterYDUPP 
Acti vati onOrderLi stPtr 
Acti vateYDUPP 
voi  d 


f  i  1  eFi  1  ter , 
numTypes , 
typeLi  st , 

*reply , 
dlglD, 
where , 
dl gHook, 
f i 1 terProc , 
acti  veLi  st , 
acti vateProc , 
*yourDataPtr  ); 


f  i  1  eFi  1  ter 

Points  to  an  optional  function  that  filters  the  files  that  are  displayed  to  the  user 
in  the  dialog  box.  See  Fi  1  eFi  1  terYDProc  (III— 2083)  for  details  of  this  function.  If 
you  don't  want  to  supply  a  filter  function,  set  this  parameter  to  NIL.  If  this 
parameter  is  not  NIL,  CustomGetFi  1  ePrevi  ew  calls  the  function  for  each  file  to 
determine  whether  to  display  the  file  to  the  user.  Your  function  returns  a 
Bool  ean  value  that  you  set  to  FALSE  to  cause  the  file  to  be  displayed. 
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CustomGetFilePreview 


CustomGetFi  1  ePrevi  ew  uses  this  parameter  along  with  the  numTypes  and 
typeLi  st  parameters  to  determine  which  files  appear  in  the  dialog  box. 

numTypes 

The  number  of  file  types  in  the  array  specified  by  the  typeLi  st  parameter, 
which  must  be  a  number  between  1  and  4.  Set  this  parameter  to  -1  to  display 
all  files. 

typeLi  st 

Specifies  an  array  of  file  types  to  be  displayed  to  the  user.  The 
CustomGetFi  1  ePrevi  ew  function  only  displays  files  whose  type  matches  an  entry 
in  this  array  (unless  you  set  the  numTypes  parameter  to  -1;  in  this  case,  the 
function  displays  all  files  to  the  user), 
reply 

A  pointer  to  a  reply  structure  that  is  to  receive  information  about  the  user's 
selection.  See  Inside  Macintosh:  Files  (listed  in  the  bibliography)  for  more 
information  about  reply  structures. 

dlglD 

The  resource  ID  of  your  custom  dialog  template.  Use  this  parameter  to  specify 
a  custom  dialog  template  resource  that  has  a  resource  type  that  differs  from  the 
standard  value.  Set  this  parameter  to  0  to  use  the  standard  template. 

where 

The  location  of  the  upper-left  corner  of  the  dialog  box  in  global  coordinates.  If 
you  set  this  point  to  ( - 1  - 1 ),  the  Movie  Toolbox  centers  the  dialog  box  on  the 
main  screen.  If  you  set  this  point  to  ( -  2  -  2 ),  the  Movie  Toolbox  centers  the 
dialog  box  on  the  screen  that  has  the  best  display  characteristics, 
dl  gFlook 

Points  to  a  custom  dialog  function,  described  inDlgFlookYDProc  (III— 2080).  Use 
this  parameter  to  support  a  custom  dialog  box  function  you  have  supplied  by 
specifying  a  dialog  template  resource  in  your  resource  file.  You  specify  the 
dialog  template's  resource  ID  with  the  dlglD  parameter.  If  you  are  not 
supplying  a  custom  dialog  function,  set  this  parameter  to  NIL.  For  more 
information  about  using  custom  dialog  functions  with  the 
CustomGetFi  1  ePrevi  ew  routine,  see  Inside  Macintosh:  Files  (listed  in  the 
bibliography). 

f i 1 terProc 

Points  to  your  modal-dialog  filter  function,  described  in  Modal  Fi  1  terYDProc 
(III— 2099).  This  function  gives  you  greater  control  over  the  interface  presented 
to  the  user.  See  Inside  Macintosh:  Files  (listed  in  the  bibliography)  for  more 
information  about  using  modal-dialog  filter  functions  with  CustomGetFi  1  e. 
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CustomGetFilePreview 


acti  veLi  st 

A  pointer  to  a  list  of  all  items  in  the  dialog  box  that  can  be  activated;  that  is, 
made  the  target  of  keyboard  input.  The  list  is  stored  as  an  array  of  integers.  The 
first  integer  must  contain  the  number  of  items  in  the  array  (not  including  this 
count  value).  The  remaining  array  entries  must  contain  item  numbers  that 
specify  valid  targets  of  keyboard  input,  in  the  order  in  which  the  items  are  to  be 
activated.  Set  this  parameter  to  N I L  to  direct  all  keyboard  input  to  the  displayed 
list  of  filenames, 
acti vateProc 

Points  to  your  activation  function,  Acti  vateYDProc  (III-2075),  which  controls  the 
highlighting  of  any  items  whose  shape  is  known  only  by  your  application.  See 
Inside  Macintosh:  Files  (listed  in  the  bibliography)  for  more  information  about 
standard  file  activation  functions. 

yourDataPtr 

A  pointer  to  optional  data  supplied  by  your  application  to  your  callback 
functions.  When  the  CustomGetFi  1  ePrevi  ew  function  calls  any  of  your  callback 
functions,  it  places  this  data  on  the  stack,  making  it  available  to  your  functions. 
Set  this  parameter  to  N I L  if  you  are  not  supplying  any  optional  data. 

Discussion 

This  function  differs  from  StandardGetFi  1  ePrevi  ew  (III— 1910)  in  that  you  can 
provide  a  custom  dialog  template  and  functions  to  support  your  template. 
CustomGetFi  1  ePrevi  ew  automatically  converts  files  to  movies  if  your  application 
requests  movies.  If  a  file  could  be  converted  into  a  movie  file  using  a  movie  import 
component,  then  the  file  is  shown  in  the  Standard  File  dialog  box. 

Special  Considerations 

CustomGetFi  1  ePrevi  ew  does  not  appear  in  the  interface  file  Movi  es  .  h;  instead,  it's 
listed  in  ImageCompressi  on  .  h. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Displaying  File  Previews"  (V-2758) 

See  Also 

See  Inside  Macintosh:  Files  (listed  in  the  bibliography)  for  a  description  of  the 
CustomGetFi  1  e  routine  and  for  more  information  about  the  parameters  to 
CustomGetFi 1 ePrevi ew. 
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CutMovieSelection 


CutMovieSelection 


Creates  a  new  movie  that  contains  the  original  movie's  current  selection. 

Movie  CutMovieSelection  ( 

Movi e  theMovi e  ) ; 

theMovi e 

The  source  movie  for  this  operation.  Your  application  obtains  this  movie 
identifier  from  such  functions  as  NewMovi  e  (11-1069),  NewMovi eFromFi 1  e  (11-1080), 
and  NewMovi eFromHandl  e  (11-1084). 

function  result  The  newly  created  movie. 

Discussion 

This  function  removes  the  current  selection  from  the  original  movie  and  makes  the 
selection  into  a  new  movie.  After  the  current  selection  has  been  removed  from  the 
original  movie,  the  duration  of  the  current  selection  is  0.  The  starting  time  of  the 
current  selection  is  not  affected.  If  you  have  assigned  a  progress  function  to  the 
source  movie,  the  Movie  Toolbox  calls  that  progress  function  during  long  cut 
operations. 

Special  Considerations 

Your  application  must  dispose  of  the  new  movie  once  you  are  done  with  it,  using 
DisposeMovie  (1-268). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es . h 

Programming  summary:  "High-Level  Movie  Editing  Functions"  (V-2746) 

Related  Java  Methods 

qui cktime. std .movi es .Movi e. cutSel  ecti  on( ) 


DataCodecBeginlnterruptSafe 

Called  before  performing  a  compression  or  decompression  operation  during 
interrupt  time. 
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DataCodecCompress 


ComponentResul t  DataCodecBeginlnterruptSafe  ( 
DataCodecComponent  dc, 

unsigned  long  maxSrcSize  ); 


dc 

The  instance  of  a  compressor  or  decompressor  component  for  this  request. 
Your  software  obtains  this  reference  when  calling  the  Component  Manager's 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131)  function. 
maxSrcSi ze 

The  maximum  size  of  a  block  of  data  to  be  compressed  or  decompressed,  in 
bytes. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  allocates  any  temporary  buffers  that  are  necessary  to  perform  the 
operation  during  interrupt  time.  To  release  the  resources  used  to  make  the 
operation  safe  during  interrupt  time,  call  the  DataCodecEndlnterruptSafe  (1-172) 
function  or  close  the  instance  of  the  compressor  or  decompressor  component. 

Special  Considerations 

If  the  function  returns  an  error,  your  software  must  not  perform  compression  or 
decompression  operations  during  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Data  Codec  Functions"  (V-2807) 


DataCodecCompress 


Compresses  data  using  the  specified  compressor  component. 

ComponentResul t  DataCodecCompress  ( 

DataCodecComponent  dc, 
void  *srcData, 

UInt32  srcSize, 

void  *dstData, 

UInt32  dstBuf f erSi ze , 

UInt32  *actual DstSi ze , 

UInt32  *decompressSl op  ); 
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DataCodecCompress 


dc 

The  compressor  component  to  used. 
srcData 

A  pointer  to  the  data  to  be  compressed. 
srcSi ze 

The  size  of  the  data  to  be  compressed,  in  bytes. 
dstData 

A  pointer  to  the  buffer  in  which  to  store  the  compressed  data. 
dstBufferSi ze 

The  size  of  the  buffer  in  which  to  store  the  compressed  data,  in  bytes, 
actual DstSi ze 

The  size  of  the  compressed  data  that  was  created,  in  bytes. 
decompressSl op 

The  number  of  bytes  that  should  be  added  to  the  decompression  buffer  size  if 
decompression  occurs  in  place. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Before  calling  this  function,  you  should  call  DataCodecGetCompressBufferSi  ze 
(1-172)  to  obtain  the  maximum  possible  size  of  the  compressed  data  that  will  be 
returned.  You  can  then  use  this  value  as  the  value  of  the  dstBufferSi  ze  parameter. 
Note  that  a  buffer  for  compressed  data  that  is  the  same  size  as  the  uncompressed 
data  may  not  be  large  enough:  in  some  cases,  the  size  of  the  compressed  data  can  be 
larger  than  the  size  of  the  decompressed  data.  When  you  compress  data,  you  should 
store  the  size  of  data  before  compression  at  the  beginning  of  the  file,  immediately 
before  the  compressed  data.  This  allows  you  to  obtain  the  size  of  the  decompressed 
data  and  allocate  the  buffer  for  storing  the  decompressed  data  before  calling 
DataCodecDecompress  (1-170). 

Special  Considerations 

You  can  compress  sprites  by  calling  this  function.  If  you  do,  you  must  include  the 
uncompressed  size  of  the  sample  at  the  beginning  of  the  sample,  before  the 
compressed  data,  and  store  the  component  subtype  of  the  data  compressor  used  to 
compress  the  sprite  in  the  decomp ressorType  field  of  the  sample's  Spri  teDescri  pti  on 
(IV-2458)  structure.  You  can  also  compress  QuickDraw  3D  media  samples  by 
calling  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


1-168 


Inside  QuickTime:  Functions  A-H 


DataCodecCompressPartial 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Data  Codec  Functions"  (V-2807) 

Related  Java  Methods 

qui cktime . std . qt components . DataCodecCompressor . compress ( ) 


DataCodecCompressPartial 


Undocumented 


ComponentResul t  DataCodecCompressPartial  ( 


ponentResult  DataCO' 
DataCodecComponent 
void 

unsigned  long 
unsigned  long 
voi  d 

unsigned  long 
unsigned  long 
Bool ean 
Bool ean 


dc , 

**next_i n , 
*avai l_i n , 
*total_i n , 
**next_out , 
*avail_out, 
*total_out, 
tryToFi ni sh , 
*did Finish  ); 


dc 

The  compressor  component  to  used. 
next_i n 

Undocumented 

a  v  a i 1  _i  n 

Undocumented 

total _i n 

Undocumented 

next_out 

Undocumented 

avai l_out 

Undocumented 

total_out 

Undocumented 

tryToFi ni sh 

Undocumented 

didFinish 

Undocumented 
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DataCodecDecompress 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


DataCodecDecompress 


Decompresses  data  using  the  specified  compressor  component. 

ComponentResul t  DataCodecDecompress  ( 

DataCodecComponent  dc, 
void  *srcData, 

UInt32  srcSize, 

void  *dstData, 

UInt32  dstBufferSi ze  ); 


dc 

The  decompressor  component  to  used. 
srcData 

A  pointer  to  the  data  to  be  decompressed. 
srcSi ze 

The  size  of  the  data  to  be  decompressed,  in  bytes. 
dstData 

A  pointer  to  the  buffer  in  which  to  store  the  decompressed  data. 
dstBufferSi ze 

The  size  of  the  buffer  in  which  to  store  the  decompressed  data,  in  bytes. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Before  allocating  the  buffer  in  which  to  store  decompressed  data,  you  need  to  get 
the  size  of  the  decompressed  data.  The  size  is  normally  stored  at  the  beginning  of 
the  file,  immediately  before  the  compressed  data. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Data  Codec  Functions"  (V-2807) 
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DataCodecDecompressPartial 


Related  Java  Methods 

qui cktime . std . qt components . Da taCodecDecompress or . decompress ( ) 


DataCodecDecompressPartial 


Undocumented 

ComponentResul t  DataCod 
DataCodecComponent 
voi  d 

unsigned  long 
unsigned  long 
voi  d 

unsigned  long 
unsigned  long 
Bool ean 


cDecompressParti al  ( 
dc , 

**next_i n , 

*avai 1 _ i n , 

*total_i n , 
**next_out , 
*avail_out, 
*total_out , 

*d  id  Finish  ); 


dc 

The  decompressor  component  to  used. 
next_i n 

Undocumented 
a  v  a i 1  _i  n 

Undocumented 
total _i n 

Undocumented 

next_out 

Undocumented 
avai l_out 

Undocumented 

total_out 

Undocumented 

didFinish 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 
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DataCodecEndlnterruptSafe 


DataCodecEndlnterruptSafe 


Releases  resources  used  by  DataCodecBeginlnterruptSafe  (1-166). 

ComponentResul t  DataCodecEndlnterruptSafe  ( 
DataCodecComponent  dc  ) ; 


dc 

The  instance  of  a  compressor  or  decompressor  component  for  this  request. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

When  your  software  has  finished  a  compression  or  decompression  operation  that 
must  be  performed  during  interrupt  time,  it  can  call  this  function  to  release  any 
memory  of  other  resources  that  were  used  by  DataCodecBegi  nlnterruptSafe. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Data  Codec  Functions"  (V-2807) 


DataCodecGetCompressBufferSize 


Returns  the  maximum  possible  size  of  the  compressed  data  that  will  be  returned 
using  the  specified  compressor  component. 

ComponentResul t  DataCodecGetCompressBufferSize  ( 

DataCodecComponent  dc, 

UInt32  srcSize, 

UInt32  *dstSize  ); 


dc 

The  compressor  component  to  used. 
srcSi ze 

The  size  in  bytes  of  the  data  being  compressed. 
dstSi ze 

A  pointer  to  the  maximum  size  of  the  compressed  data  that  will  be  returned. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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DataHAddMovie 


Discussion 

The  actual  size  of  the  compressed  data  will  likely  be  smaller  than  the  size  you 
initially  have  to  allocate,  so  after  you  compress  the  data  you  should  shrink  the 
compressed  data  handle  down  to  the  actual  data  size.  When  compressing  a  movie, 
allocate  an  extra  ten  32-bit  integers  of  space  to  store  the  compressed  movie  resource 
header  information,  as  shown  in  the  following  code  sample: 

unsigned  long  compressedSi ze ; 

Handle  compressedData ; 

DataCodecGetCompressBuf ferSi ze(dataCompressor ,  movi eResourceSi ze , 
&compressedSi ze) ; 

compressedData  =  NewHandl e( compressedSi ze  +  (10  *  si zeof ( UInt32 ) ) ) ; 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Related  Java  Methods 

qui cktime . std . qt components . DataCodecCompressor . getCompress But ferSi ze( ) 


See  Also 

DataCodecCompress  (1-167). 


DataHAddMovie 


Assigns  movie  data  to  a  data  handler. 

ComponentResul t  DataHAddMovie  ( 
DataHandler  dh. 

Movie  theMovie, 

short  *id  ); 


dh 

A  data  handler  component. 
theMovi  e 

A  movie  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e 
(11-1084). 
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DataHAppend64 


i  d 

A  pointer  to  the  field  that  specifies  the  resource  containing  the  movie  data  that 
is  to  be  added. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


DataHAppend64 


Appends  data  to  the  current  data  reference. 


ComponentResul t  DataHAppend64  ( 
DataHandler  dh, 

void  *data, 

wide  *fileOffset, 

unsi gned  1 ong  size  ) ; 


dh 

A  data  handler  component. 

data 

A  pointer  to  data  to  be  appended, 
f i 1 eOffset 

A  pointer  to  a  64-bit  value  that  represents  the  offset  in  the  file  of  data  to  be 
appended. 

si  ze 

The  size  of  the  data  to  be  appended. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 
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DataHCanUseDataRef 


Reports  whether  a  data  handler  can  access  the  data  associated  with  a  specified  data 
reference. 


ComponentResul t 
DataHandl er 
Handl e 
1  ong 


DataHCanUseDataRef 
dh , 

dataRef , 
*useFlags  ); 


( 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component. 
dataRef 

The  data  reference.  This  parameter  contains  a  handle  to  the  information  that 
identifies  the  container  in  question. 
useFl  ags 

A  pointer  to  a  field  of  flags  (see  below)  that  your  data  handler  component  uses 
to  indicate  its  ability  to  access  the  container  identified  by  the  dataRef  parameter. 
Set  all  appropriate  flags  to  1;  set  unused  flags  to  0.  For  example,  if  your 
component  supports  networked  multimedia  servers  using  a  special  set  of 
protocols,  your  data  handler  should  set  the  kDataHCanRead  and 
kDataHCanSpecialRead  flags  to  1  for  any  container  that  is  on  that  server.  In 
addition,  if  your  component  can  write  to  the  server,  set  the  kDataHCanWrite  and 
kDataHCanSpeci  al  Wri  te  flags  to  1  (perhaps  along  with 

kDataHCanStreamingWrite).If  your  data  handler  cannot  access  the  container,  set 
the  whole  field  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

useFlags  Constants 

kDataHCanRead 

Indicates  that  your  data  handler  can  read  from  the  container. 
kDataHSpeci al Read 

Indicates  that  your  data  handler  can  read  from  the  container  using  a  specialized 
method.  For  example,  your  data  handler  might  support  access  to  networked 
multimedia  servers  using  a  special  protocol.  In  that  case,  your  component 
would  set  this  flag  to  1  whenever  the  data  reference  identifies  a  container  on  a 
supported  server. 

kDataHSpeci a 1  Read Fi 1 e 

Indicates  that  your  data  handler  can  read  from  the  container  using  a  specialized 
method  that  is  particular  to  the  type  of  container  in  question  (for  example,  a 
FlyperCard  stack).  This  flag  represents  a  special  case  of  the  kDataHSpeci  al  Read 
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DataHCloseForRead 


flag.  That  is,  this  flag  is  appropriate  only  if  you  have  also  set  kDataHSpeci  a  1  Read 
to  1. 

kDataHCanWri te 

Indicates  that  your  data  handler  can  write  data  to  the  container.  In  particular, 
use  this  flag  to  indicate  that  your  data  handler's  DataHPutData  (1-216)  function 
will  work  with  this  data  reference. 

kDataHSpeci al  Write 

Indicates  that  your  data  handler  can  write  to  the  container  using  a  specialized 
method.  As  with  the  kDataHSpeci  al  Read  flag,  your  data  handler  would  use  this 
flag  to  indicate  that  the  data  reference  identifies  a  container  which  your 
component  can  access  using  specialized  support  (for  example,  special  network 
protocols). 

kDataHCanStreamingWrite 

Indicates  that  your  data  handler  can  support  the  special  write  functions  for 
capturing  movie  data  when  writing  to  this  container. 

Discussion 

Apple's  standard  data  handler  sets  both  the  kDataHCanRead  and  kDataHCanWri  te  flags 
to  1  for  any  data  reference  it  receives,  indicating  that  it  can  read  from  and  write  to 
any  volume. 

Special  Considerations 

Your  data  handler  may  use  any  facilities  necessary  to  determine  whether  it  can 
access  the  container.  Bear  in  mind,  though,  that  your  component  should  try  to  be  as 
quick  about  this  determination  as  possible,  in  order  to  minimize  the  chance  that  the 
delay  will  be  noticed  by  the  user. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Selecting  a  Data  Handler"  (V-2838) 

See  Also 

The  Movie  Toolbox  calls  your  component's  DataHGetVol  umeLi  st  (1-207)  function  to 
retrieve  your  data  handler's  capabilities  for  an  entire  volume. 


DataHCloseForRead 

Closes  read-only  access  to  its  data  reference. 
ComponentResul t  DataHCloseForRead  ( 
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DataHCloseForWrite 


DataHandler  dh  ); 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Data  handler  components  provide  two  basic  read  facilities:  DataHGetData  (1-186) 
function  is  a  fully  synchronous  read  operation,  while  DataHSchedul  eData  (1-220)  is 
asynchronous.  Applications  provide  scheduling  information  when  they  call  your 
component's  DataHSchedul  eData  function.  When  your  component  processes  the 
queued  request,  it  calls  the  application's  data-handler  completion  function.  Before 
any  application  can  read  data  from  a  data  reference,  it  must  open  read  access  to  that 
reference  by  calling  your  component's  DataHOpenForRead  (1-209)  function. 

DataHCl  oseForRead  (1-176)  closes  that  read  access  path. 

Special  Considerations 

Note  that  a  client  program  may  close  its  connection  to  your  component  (by  calling 
Cl  oseComponent  (I— 100))  without  closing  the  read  path.  If  this  happens,  your 
component  should  close  the  data  reference  before  closing  the  connection. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Reading  Movie  Data"  (V-2839) 

See  Also 

By  calling  your  component's  DataHFi  ni  shData  (1-182)  function,  applications  can 
force  your  component  to  process  queued  read  requests.  Applications  may  call  your 
component's  DataHGetScheduleAheadTime  (1-206)  function  in  order  to  determine 
how  far  in  advance  your  component  prefers  to  get  read  requests. 


DataHCloseForW  rite 

Closes  write-only  access  to  its  data  reference. 

ComponentResul t  DataHCloseForWrite  ( 

DataHandler  dh  ); 

dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component. 
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DataHCompareDataRef 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Data  handlers  provide  two  distinct  write  facilities:  DataHPutData  (1-216)  is  a  simple 
synchronous  interface  that  allows  applications  to  append  data  to  the  end  of  a 
container,  and  DataHWriteisa  more  capable,  asynchronous  write  function  that  is 
suitable  for  movie  capture  operations.  Before  writing  data  to  a  data  reference, 
applications  must  call  your  component's  DataHOpenForWri  te  (1-210)  function  to 
open  a  write  path  to  the  container.  DataHCl  oseForWri  te  closes  that  write  path.  As  is 
the  case  with  DataHSchedul  eData  (1-220),  your  component  calls  the  application's 
data-handler  completion  function  when  you  are  done  with  the  write  request. 

Special  Considerations 

A  client  program  may  close  its  connection  to  your  component  (by  calling 
Cl  oseComponent  (I— 100))  without  closing  the  write  path.  If  this  happens,  your 
component  should  close  the  data  reference  before  closing  the  connection.  Note  that 
some  data  handlers  may  not  support  write  operations.  For  example,  some  shared 
devices,  such  as  a  CD-ROM  "jukebox,"  may  be  read-only  devices.  As  a  result,  it  is 
very  important  that  your  data  handler  correctly  report  its  write  capabilities  to  client 
programs. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Writing  Movie  Data"  (V-2840) 

See  Also 

There  are  several  other  helper  functions  that  allow  applications  to  prepare  your 
data  handler  for  a  movie  capture  operation.  DataHCreateFi  1  e  (1-180)  asks  your 
component  to  create  a  new  container.  The  DataHSetFi  1  eSi  ze  (1-227)  and 
DataHGetFi  1  eSi  ze  (1-194)  functions  work  with  a  container's  size,  in  bytes.  The 
DataHGetFreeSpace  (1-198)  function  allows  applications  to  determine  when  to  make 
a  container  larger.  DataHPreextend  (1-214)  asks  your  component  to  make  a  container 
larger.  Applications  may  call  your  component's  DataHGetPreferredBl  ockSi  ze 
(1-204)  function  in  order  to  determine  how  best  to  interact  with  your  data  handler. 


DataHCompareDataRef 

Compares  a  supplied  data  reference  against  its  current  data  reference  and  returns  a 
Boolean  value  indicating  whether  the  data  references  are  equivalent  (that  is,  the  two 
data  references  identify  the  same  container). 
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ComponentResul t 
DataHandl er 
Hand] e 
Bool ean 


DataHCompareDataRef 
dh , 

dataRef , 

*equal  ); 


( 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component. 
dataRef 

The  data  reference  to  be  compared  to  your  component's  current  data  reference. 
Different  types  of  containers  may  require  different  types  of  data  references.  For 
example,  a  reference  to  a  memory-based  movie  may  be  a  handle,  while  a 
reference  to  a  file-based  movie  maybe  an  alias.  Apple's  memory-based  data 
handler  for  the  Macintosh  uses  handles  (and  has  a  subtype  value  of  ’  hndl  ’), 
while  the  HFS  data  handler  uses  Alias  Manager  aliases  (its  subtype  value  is 
’  al  i  s  ’ ).  See  "Data  References"  (IV-2661). 
equal 

A  pointer  to  a  Boolean.  Your  component  should  set  that  Bool  ean  to  TRUE  if  the 
two  data  references  identify  the  same  container.  Otherwise,  set  the  Bool  ean  to 
FALSE. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

All  data  handler  components  use  data  references  to  identify  and  locate  a  movie's 
container.  DataHCompareDataRef  asks  your  component  to  compare  a  data  reference 
against  the  current  data  reference  and  indicate  whether  the  references  are 
equivalent  (that  is,  refer  to  the  same  container).  Client  programs  can  correlate  data 
references  with  data  handlers  by  matching  the  component's  subtype  value  with  the 
data  reference  type;  the  subtype  value  indicates  the  type  of  data  reference  the 
component  supports.  All  data  handlers  with  the  same  subtype  value  must  support 
the  same  data  reference  type. 

Special  Considerations 

Note  that  your  component  cannot  simply  compare  the  bits  in  the  two  data 
references.  For  example,  two  completely  different  aliases  may  refer  to  the  same  HFS 
file.  Consequently,  you  need  to  completely  resolve  the  data  reference  in  order  to 
determine  the  file  identified  by  the  reference. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Identifying  Data  References"  (V-2839) 
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DataHCreateFile 


See  Also 

DataHSetDataRef  (1-224)  and  DataHGetDataRef  (1-189)  allow  applications  to  assign 
your  data  handler's  current  data  reference.  DataHResol  veDataRef  (1-218)  permits 
your  component  to  locate  a  data  reference's  container. 


DataHCreateFile 


Creates  a  new  container  that  meets  the  specifications  of  the  current  data  reference. 


ComponentResul t 
DataHandl er 
OSType 
Bool ean 


DataHCreateFile  ( 
dh , 

creator , 

del eteExi sti ng 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component, 
creator 

The  creator  type  of  the  new  container.  If  the  client  program  sets  this  parameter 
to  0,  your  component  should  choose  a  reasonable  value  (for  example,  '  TVOD 
the  creator  type  for  Apple's  movie  player). 

del eteExi sti ng 

Indicates  whether  to  delete  any  existing  data.  If  this  parameter  is  set  to  TRU  E  and 
a  container  already  exists  for  the  current  data  reference,  your  component 
should  delete  that  data  before  creating  the  new  container.  If  this  parameter  is 
set  to  FALSE,  your  component  should  preserve  any  data  that  resides  in  the 
container  defined  by  the  current  data  reference  (if  there  is  any). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Data  handlers  provide  two  distinct  write  facilities:  DataHPutData  (1-216)  is  a  simple 
synchronous  interface  that  allows  applications  to  append  data  to  the  end  of  a 
container,  while  DataHWri  te  is  a  more  capable,  asynchronous  write  function  that  is 
suitable  for  movie  capture  operations.  As  is  the  case  with  DataHScheduleData  (1-220), 
your  component  calls  the  application's  data-handler  completion  function  when  you 
are  done  with  the  write  request. 

Special  Considerations 

Note  that  some  data  handlers  may  not  support  write  operations.  For  example,  some 
shared  devices,  such  as  a  CD-ROM  "jukebox,"  may  be  read-only  devices.  As  a 
result,  it  is  very  important  that  your  data  handler  correctly  report  its  write 
capabilities  to  client  programs. 
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DataHCreateFileWithFlags 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui ckTi  meComponents  .  h 
Programming  summary:  "Writing  Movie  Data"  (V-2840) 

See  Also 

There  are  several  other  helper  functions  that  allow  applications  to  prepare  your 
data  handler  for  a  movie  capture  operation.  DataHCreateFi  1  e  (1-180)  asks  your 
component  to  create  a  new  container.  The  DataHSetFi  1  eSi  ze  (1-227)  and 
DataHGetFi  1  eSi  ze  (1-194)  functions  work  with  a  container's  size,  in  bytes.  The 
DataHGetFreeSpace  (1-198)  function  allows  applications  to  determine  when  to  make 
a  container  larger.  DataHPreextend  (1-214)  asks  your  component  to  make  a  container 
larger.  Applications  may  call  your  component's  DataHGetPreferredBlockSize 
(1-204)  function  in  order  to  determine  how  best  to  interact  with  your  data  handler. 
Before  writing  data  to  a  data  reference,  applications  must  call  your  component's 
DataHOpenForWri  te  (1-210)  function  to  open  a  write  path  to  the  container. 

DataHCl  oseForWri  te  (1-177)  closes  that  write  path. 


DataHCreateFileWithFlags 


Undocumented 


ComponentResul t 
DataHandl er 
OSType 
Bool ean 
UInt32 


DataHCreateFi 1 eWi th FI  a gs 
dh , 

creator , 

del eteExi sti ng  , 

flags  ); 


( 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component, 
creator 

The  creator  type  of  the  new  container.  If  the  client  program  sets  this  parameter 
to  0,  your  component  should  choose  a  reasonable  value  (for  example,  '  TVOD ' , 
the  creator  type  for  Apple's  movie  player). 

del eteExi sti ng 

Indicates  whether  to  delete  any  existing  data.  If  this  parameter  is  set  to  TRU  E  and 
a  container  already  exists  for  the  current  data  reference,  your  component 
should  delete  that  data  before  creating  the  new  container.  If  this  parameter  is 
set  to  FALSE,  your  component  should  preserve  any  data  that  resides  in  the 
container  defined  by  the  current  data  reference  (if  there  is  any). 
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DataHDoesBuffer 


fl  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


DataHDoesBuffer 


Reports  whether  a  data  handler  does  buffer  reads  and  writes. 

ComponentResul t  DataHDoesBuffer  ( 

DataHandler  dh, 

Boolean  *buffersReads , 

Boolean  *buffersWri tes  ); 


dh 

A  data  handler  component. 
buffersReads 

A  pointer  toaBoolean  that  is  returned  true  if  the  data  handler  component  does 
buffer  reads,  false  otherwise. 

buffersWri tes 

A  pointer  toaBoolean  that  is  returned  true  if  the  data  handler  component  does 
buffer  writes,  false  otherwise. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 


DataHFinishData 

Completes  or  cancels  one  or  more  queued  read  requests. 

ComponentResul t  DataHFinishData  ( 

DataHandler  dh, 
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DataHFinishData 


Ptr  PI aceToPutDataPtr, 

Boolean  Cancel  ); 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component. 

PI aceToPutDataPtr 

The  location  in  memory  that  is  to  receive  the  data.  The  value  of  this  parameter 
identifies  the  specific  read  request  to  be  completed.  If  this  parameter  is  set  to 
N I L,  the  call  affects  all  pending  read  requests. 

Cancel 

Indicates  whether  the  calling  program  wants  to  cancel  the  outstanding  request. 
If  this  parameter  is  set  to  TRUE,  your  data  handler  should  cancel  the  request  (or 
requests)  identified  by  the  PI  aceToPutDataPtr  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Client  programs  use  DataHFinishData  either  to  cancel  outstanding  read  requests  or 
to  demand  that  the  requests  be  serviced  immediately.  Note  that  your  component 
must  call  the  client  program's  data-handler  completion  function  for  each  queued 
request,  even  though  the  client  program  called  DataHFinishData.  Be  sure  to  call  the 
completion  function  for  both  canceled  and  completed  read  requests. 

Special  Considerations 

Preroll  operations  are  a  special  case  of  the  immediate  service  request.  The  client 
program  will  have  queued  one  or  more  read  requests  with  their  scheduled  time  of 
delivery  set  infinitely  far  into  the  future.  Your  data  handler  queues  those  requests 
until  the  client  program  calls  DataHFinishData  demanding  that  all  outstanding  read 
requests  be  satisfied  immediately. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Reading  Movie  Data"  (V-2839) 

See  Also 

Data  handler  components  provide  two  basic  read  facilities.  DataHGetData  (1-186) 
function  is  a  fully  synchronous  read  operation,  while  DataHSchedul  eData  (1-220)  is 
asynchronous.  When  your  component  processes  the  queued  request,  it  calls  the 
application's  data-handler  completion  function.  Client  programs  queue  read 
requests  by  calling  your  component's  DataHSchedul  eData  (1-220)  function. 
Applications  may  call  your  component's  DataHGetSchedul  eAheadTime  (1-206) 
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DataHFlushCache 


function  in  order  to  determine  how  far  in  advance  your  component  prefers  to  get 
read  requests.  Before  any  application  can  read  data  from  a  data  reference,  it  must 
open  read  access  to  that  reference  by  calling  your  component's  DataHOpenForRead 
(1-209)  function.  DataHCloseForRead  (1-176)  closes  that  read  access  path. 


DataHFlushCache 

Discards  the  contents  of  any  cached  read  buffers. 

ComponentResul t  DataHFlushCache  ( 

DataHandl er  dh  ) ; 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Note  that  this  function  does  not  invalidate  any  queued  read  requests  (made  by 
calling  your  component's  DataHSchedul  eData  (1-220)  function). 

Special  Considerations 

Client  programs  may  call  this  function  if  they  have,  in  some  way,  changed  the 
container  associated  with  the  current  data  reference  on  their  own.  Under  these 
circumstances,  data  your  component  may  have  read  and  cached  in  anticipation  of 
future  read  requests  from  the  client  may  be  invalid. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Managing  Data  Handler  Components"  (V-2841) 


DataHFlushData 


Forces  any  data  in  your  component's  write  buffers  to  be  written  to  the  device  that 
contains  the  current  data  reference. 

ComponentResul t  DataHFlushData  ( 

DataHandl er  dh  ) ; 
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DataHGetAvailableFileSize 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  essentially  analogous  to  the  Mac  OS  File  Manager's  PBFlushFile 
function.  The  client  program  may  call  this  function  after  any  write  operation  (either 
DataHPutData  (1—216)  or  DataHWri  te  (1-232)).  Your  component  should  do  what  is 
necessary  to  make  sure  that  the  data  is  written  to  the  storage  device  that  contains 
the  current  data  reference. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Managing  Data  Handler  Components"  (V-2841) 


DataHGetAvailableFileSize 


Returns  the  available  file  size  for  a  data  handler  component. 

ComponentResul t  DataHGetAvailableFileSize  ( 

DataHandler  dh, 

long  *fileSize  ); 


dh 

A  data  handler  component, 
f i 1 eSi ze 

A  pointer  to  the  file  size. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 


DataHGetCacheSizeLimit 


Returns  the  cache  size  limit  for  a  data  handler  component. 


Inside  QuickTime:  Functions  A-H 
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DataHGetData 


ComponentResul t  DataHGetCacheSi zeLi mi t  ( 
DataHandler  dh, 

Size  *cacheSi zeLi mi t  ); 


dh 

A  data  handler  component. 
cacheSi zeLi mi t 

A  pointer  to  the  cache  size  limit. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

See  Also 

For  the  corresponding  set  function,  see  DataHSetCacheSi  zeLi  mi  t  (1-224). 


DataHGetData 


Reads  data  from  its  current  data  reference,  which  is  a  synchronous  read  operation. 

ComponentResul t  DataHGetData  ( 

DataHandler  dh, 

Handle  h, 

long  hOffset, 

long  offset, 

1 ong  size  ) ; 

dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component, 
h 

The  handle  to  receive  the  data. 
hOffset 

Identifies  the  offset  into  the  handle  where  your  component  should  return  the 
data. 

offset 

The  offset  in  the  data  reference  from  which  your  component  is  to  read. 

si  ze 

The  number  of  bytes  to  read. 
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DataHGetDataAvailability 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Data  handler  components  provide  two  basic  read  facilities.  DataHGetData  function  is 
a  fully  synchronous  read  operation,  while  DataHSchedul  eData  (1-220)  is 
asynchronous.  (Applications  provide  scheduling  information  when  they  call 
DataHSchedul  eData.)  Before  any  application  can  read  data  from  a  data  reference,  it 
must  open  read  access  to  that  reference  by  calling  your  component's 
DataHOpenForRead  (1-209)  function.  DataHCl  oseForRead  (1-176)  closes  that  read  access 
path.  When  your  component  processes  the  queued  request,  it  calls  the  application's 
data-handler  completion  function. 

Special  Considerations 

Note  that  the  Movie  Toolbox  may  try  to  read  data  from  a  data  reference  without 
calling  your  component's  DataHOpenForRead  (1-209)  function.  If  this  happens,  your 
component  should  open  the  data  reference  for  read-only  access,  respond  to  the  read 
request,  and  then  leave  the  data  reference  open  in  anticipation  of  later  read  requests. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Reading  Movie  Data"  (V-2839) 

See  Also 

DataHGetData  provides  a  high-level  read  interface.  This  is  a  synchronous  read 
operation;  that  is,  the  client  program's  execution  is  blocked  until  your  component 
returns  control  from  this  function.  As  a  result,  most  time-critical  clients  use  the 
DataHSchedul  eData  (1-220)  function  to  read  data.  By  calling  your  component's 
DataHFinishData  (1-182)  function,  applications  can  force  your  component  to  process 
queued  read  requests.  Applications  may  call  your  component's 
DataHGetSchedul  eAheadT i  me  (1-206)  function  in  order  to  determine  how  far  in 
advance  your  component  prefers  to  get  read  requests.  Client  programs  can  force 
your  component  to  invalidate  any  cached  data  by  calling  your  component's 
DataHFl  ushCache  (1-184)  function. 


DataHGetDataAvailability 


Undocumented 

ComponentResul t  DataHGetDataAvailability  ( 
DataHandler  dh, 

long  offset. 
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DataHG  etDatalnBuf  f  er 


1  ong 
1  ong 
1  ong 


1  en , 

*mi ssi ng_offset , 
*mi ssi ng_l en  ) ; 


dh 

A  data  handler  component, 
offset 

Undocumented 
1  en 

Undocumented 
mi ssi ng_offset 
Undocumented 
mi ssi ng_l en 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


DataHGetDatalnBuffer 


Returns  the  information  about  the  data  in  a  data  handler  component's  buffer. 

ComponentResul t  DataHGetDatalnBuffer  ( 

DataHandler  dh, 

long  startOffset, 

1 ong  *si  ze  ) ; 


dh 

A  data  handler  component. 
startOffset 

The  offset  to  the  start  of  the  data. 

si  ze 

The  size  of  the  data. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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DataHGetDataRate 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


DataHGetDataRate 


Undocumented 


ComponentResul t 
DataHandl er 
1  ong 
1  ong 


DataHGetDataRate  ( 
dh , 

fl ags , 

*bytesPerSecond 


): 


dh 

A  data  handler  component, 
fl  ags 

Undocumented 

bytesPerSecond 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 


DataHGetDataRef 


Retrieves  your  component's  current  data  reference. 

ComponentResul t  DataHGetDataRef  ( 

DataHandler  dh. 

Handle  *dataRef  ); 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component. 
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DataHG  etDataRef  AsType 


dataRef 

A  pointer  to  a  data  reference  handle.  Your  component  should  make  a  copy  of 
its  current  data  reference  in  a  handle  and  return  that  handle  in  this  field.  The 
client  program  is  responsible  for  disposing  of  that  handle.  Different  types  of 
containers  may  require  different  types  of  data  references.  For  example,  a 
reference  to  a  memory -based  movie  may  be  a  handle,  while  a  reference  to  a 
file-based  movie  may  be  an  alias.  Apple's  memory-based  data  handler  for  the 
Macintosh  uses  handles  (and  has  a  subtype  value  of  ’  hndl  ’ ),  while  the  HFS 
data  handler  uses  Alias  Manager  aliases  (its  subtype  value  is  '  a  1  i  s ' ).  See  "Data 
References"  (IV-2661). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

All  data  handler  components  use  data  references  to  identify  and  locate  a  movie's 
container.  Client  programs  can  correlate  data  references  with  data  handlers  by 
matching  the  component's  subtype  value  with  the  data  reference  type;  the  subtype 
value  indicates  the  type  of  data  reference  the  component  supports.  All  data 
handlers  with  the  same  subtype  value  must  support  the  same  data  reference  type. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Identifying  Data  References"  (V-2839) 

See  Also 

DataHCompareDataRef  (1-178)  asks  your  component  to  compare  a  data  reference 
against  the  current  data  reference  and  indicate  whether  the  references  are 
equivalent  (that  is,  refer  to  the  same  container).  DataHResol  ve Data  Ref  (1-218)  permits 
your  component  to  locate  a  data  reference's  container.  For  the  set  function 
corresponding  to  DataHGetDataRef,  see  DataHSetDataRef  (1-224). 


DataHGetDataRef  AsT  ype 


Retrieves  a  data  handler  component's  current  data  reference  of  a  given  type. 


Component Res ul t  DataHGetDataRef AsType 
DataHandler  dh, 

OSType  requestedType , 

Handl e  *dataRef  ) ; 


( 
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DataHG  etDataRef  Extension 


dh 

A  data  handler  component. 
requestedType 

The  type  of  the  data  reference  to  retrieve;  see  "Data  References"  (IV-2661). 
dataRef 

A  pointer  to  a  data  reference  handle.  Your  component  should  make  a  copy  of 
its  current  data  reference  in  a  handle  and  return  that  handle  in  this  field.  The 
client  program  is  responsible  for  disposing  of  that  handle.  Different  types  of 
containers  may  require  different  types  of  data  references.  For  example,  a 
reference  to  a  memory-based  movie  may  be  a  handle,  while  a  reference  to  a 
file-based  movie  may  be  an  alias.  Apple's  memory-based  data  handler  for  the 
Macintosh  uses  handles  (and  has  a  subtype  value  of  '  hndl ' ),  while  the  HFS 
data  handler  uses  Alias  Manager  aliases  (its  subtype  value  is  '  a  1  i  s ' ).  See  "Data 
References"  (IV-2661). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


DataHGetDataRefExtension 


Retrieves  your  component's  current  data  reference  extension  data. 

ComponentResul t  DataHGetDataRefExtension  ( 

DataHandler  dh. 

Handle  *extension, 

OSType  idType  ); 


dh 

A  data  handler  component, 
extensi on 

A  pointer  to  a  handle  to  the  extension  data, 
i dType 

A  four-byte  signature  identifying  the  type  of  extension  data. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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DataHG  etDataRef  WithAnchor 


Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

See  Also 

For  the  corresponding  set  function,  see  DataHSetDataRef  Extensi  on  (1-225). 


DataHGetDataRef  W  ith  Anchor 


Retrieves  a  data  handler  component's  component's  current  data  reference  and 
anchor  data  reference. 


ComponentResul t 
DataHandl er 
Handl e 
OSType 
Handl e 


Da taHGet Data  Ref Wi th Anchor 
dh , 

anchorDataRef , 
dataRefType , 

*dataRef  ); 


( 


dh 

A  data  handler  component. 
anchorDataRef 

A  handle  to  the  anchor  data  reference. 
dataRefType 

The  type  of  the  data  reference;  see  "Data  References"  (IV-2661). 
dataRef 

A  pointer  to  a  data  reference  handle.  Your  component  should  make  a  copy  of 
its  current  data  reference  in  a  handle  and  return  that  handle  in  this  field.  The 
client  program  is  responsible  for  disposing  of  that  handle.  Different  types  of 
containers  may  require  different  types  of  data  references.  For  example,  a 
reference  to  a  memory-based  movie  may  be  a  handle,  while  a  reference  to  a 
file-based  movie  may  be  an  alias.  Apple's  memory -based  data  handler  for  the 
Macintosh  uses  handles  (and  has  a  subtype  value  of  ’  hndl ' ),  while  the  HFS 
data  handler  uses  Alias  Manager  aliases  (its  subtype  value  is  ’alls').  See  "Data 
References"  (IV-2661). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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DataHGetDevicelndex 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

See  Also 

For  the  corresponding  set  function,  see  DataHSetDataRefWi  thAnchor  (1-226). 


DataHGetDevicelndex 


Returns  a  value  that  identifies  the  device  on  which  a  data  reference  resides. 

ComponentResul t  DataHGetDevicelndex  ( 

DataHandler  dh, 

long  *devicelndex  ); 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component, 
devi celndex 

A  pointer  to  a  field  that  your  data  handler  component  uses  to  return  a  device 
identifier  value.  Your  component  may  use  any  identifier  value  that  is 
appropriate  (for  example,  Apple's  HFS  data  handler  uses  the  volume  reference 
number).  The  client  program  should  do  nothing  with  this  value  other  than 
compare  it  with  other  identifiers  returned  by  your  data  handler  component. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Some  client  programs  may  need  to  account  for  the  fact  that  two  or  more  data 
references  reside  on  the  same  device.  For  instance,  this  may  affect  storage-allocation 
requirements.  This  function  allows  such  client  programs  to  obtain  this  information 
from  your  data  handler. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Selecting  a  Data  Flandler"  (V-2838) 


DataHGetFileName 


Retrieves  the  name  of  the  file  supplying  the  current  data  reference  for  a  data 
handler. 


Inside  QuickTime:  Functions  A-H 
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DataHGetFileSize 


ComponentResul t  DataHGetFi 1 eName  ( 

DataHandler  dh, 

Str255  str  ) ; 

dh 

A  data  handler  component. 

str 

The  name  of  the  file  as  a  string. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


DataHGetFileSize 


Returns  the  size,  in  bytes,  of  the  current  data  reference. 

ComponentResul t  DataHGetFileSize  ( 

DataHandler  dh, 

1 ong  *f i 1 eSi ze  ) ; 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component, 
f i 1 eSi ze 

A  pointer  to  a  long  integer.  Your  component  returns  the  size  of  the  container 
corresponding  to  the  current  data  reference,  in  bytes. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  operationally  equivalent  to  the  Mac  OS  File  Manager's  Get  EOF 
function.  Before  writing  data  to  a  data  reference,  applications  must  call  your 
component's  DataHOpenForWri  te  (1-210)  function  to  open  a  write  path  to  the 
container.  DataHCloseForWrite  (1-177)  closes  that  write  path.  As  is  the  case  with 
DataHSchedul  eData  (1-220),  your  component  calls  the  application's  data-handler 
completion  function  when  you  are  done  with  the  write  request. 

Special  Considerations 

Note  that  some  data  handlers  may  not  support  write  operations.  For  example,  some 
shared  devices,  such  as  a  CD-ROM  "jukebox,"  may  be  read-only  devices.  As  a 
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DataHGetFileSize64 


result,  it  is  very  important  that  your  data  handler  correctly  report  its  write 
capabilities  to  client  programs. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Writing  Movie  Data"  (V-2840) 

See  Also 

Data  handlers  provide  two  distinct  write  facilities.  DataHPutData  (1-216)  is  a  simple 
synchronous  interface  that  allows  applications  to  append  data  to  the  end  of  a 
container.  DataHWri  te  is  a  more  capable,  asynchronous  write  function  that  is 
suitable  for  movie  capture  operations.  There  are  several  other  helper  functions  that 
allow  applications  to  prepare  your  data  handler  for  a  movie  capture  operation. 
DataHCreateFi  1  e  (1-180)  asks  your  component  to  create  a  new  container.  The 
DataHSetFi  1  eSi  ze  (1-227)  and  DataHGetFi  1  eSi  ze  functions  work  with  a  container's 
size,  mbytes.  The  DataHGetFreeSpace  (1-198)  function  allows  applications  to 
determine  when  to  make  a  container  larger.  DataHPreextend  (1-214)  asks  your 
component  to  make  a  container  larger.  Applications  may  call  your  component's 
DataHGetPreferredBlockSize  (1-204)  function  in  order  to  determine  how  best  to 
interact  with  your  data  handler.  For  the  set  function  corresponding  to 
DataHGetFi  1  eSi  ze,  see  DataHSetFi  1  eSi  ze  (1-227). 


DataHGetFileSize64 


Provides  a  64-bit  version  ofDataHGetFileSize  (1-194). 

ComponentResul t  DataHGetFi 1 eSi ze64  ( 

DataHandler  dh, 

wide  *fileSize  ); 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component, 
f i 1 eSi ze 

A  pointer  to  a  wide.  Your  component  returns  the  size  of  the  container 
corresponding  to  the  current  data  reference,  in  bytes. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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DataHGetFileSizeAsync 


Discussion 

The  only  difference  between  this  function  and  DataHGetFileSize  (1-194)  is  that  the 
f  i  1  eSi  ze  parameter  is  a  64-bit  integer  instead  of  a  32-bit  integer. 

Special  Considerations 

New  applications  should  use  this  function  instead  of  the  32-bit  version. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

See  Also 

See  DataHGetFi  1  eSi  ze  (1-194).  For  the  set  function  corresponding  to 
DataFIGetFi  1  eSi  ze64,  see  DataFISetFi  1  eSi  ze64  (1-228). 


DataHGetFileSizeAsync 


Returns  the  size  of  the  current  data  reference,  invoking  a  completion  callback. 


ComponentResul  t  DataFIGetFi  1  eSi  zeAsync  ( 
DataHandier  dh, 

wide  *fileSize, 

DataHCompl eti onUPP  compl eti onRtn , 
1 ong  refCon  ) ; 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component, 
f i 1 eSi ze 

A  pointer  to  a  64-bit  value.  Your  component  returns  the  size  of  the  container 
corresponding  to  the  current  data  reference,  in  bytes. 

compl eti onRtn 

A  pointer  to  a  data  handler  completion  callback,  described  in 
DataHCompl  eti  onProc  (III — 2078). 

refCon 

A  reference  constant  to  be  passed  to  your  callback.  Use  this  parameter  to  point 
to  a  data  structure  containing  any  information  your  function  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 
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DataHGetFileTypeOrdering 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


DataHGetFileTypeOrdering 


Returns  the  preferred  ordering  for  file  typing  information. 

ComponentResul t  DataHGetFileTypeOrdering  ( 

DataHandler  dh, 

DataHFi 1 eTypeOrderi ngHandl e  *orderi ngLi stHandl e  ); 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component, 
orderi ngLi stHandl e 

A  pointer  to  a  handle  to  a  list  of  OS  Type  values  (see  below).  The  list  may  contain 
only  a  subset  of  the  currently  defined  types  (i.e.,  Mac  OS  file  type,  extension, 
MIME  type)  to  limit  the  consideration  to  reasonable  types. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

orderingListHandle  Constants 

kDataHFi 1 eTypeMacOSFi 1 eType 
The  file  type;  value  is  '  f  typ ' . 
kDataHFi 1 eTypeExtensi  on 

The  file  type  extension;  value  is  '  text ' . 
kDataHFi 1 eTypeMIME 

The  MIME  type;  value  is  '  mi  me ' . 

Discussion 

If  the  data  handler  has  not  set  the  data  reference,  it  can  choose  to  return  either  an 
error  or  a  reasonable  default  ordering  list. 

Special  Considerations 

Before  making  a  call  to  this  function,  the  client  should  have  opened  the  data  handler 
and  called  DataHSetDataRef  (1-224)  or  DataHSetDataRefWi  thAnchor  (1-226).  This 
allows  the  data  handler  to  return  a  different  ordering  based  on  the  particular  file. 
This  might  allow  for  a  data  handler  to  vary  its  ordering  based  on  the  location  of  the 
file.  For  example,  on  the  Mac  OS,  it  might  use  extensions  only  on  foreign  volumes. 
For  other  volumes,  it  might  use  a  Mac  OS  file  type  followed  by  a  file  extension. 

Version  Notes 

Introduced  in  QuickTime  5. 
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DataHGetFreeSpace 


Programming  Info 

C  interface  file:  Qui  cktimeComponents .  h 


DataHGetFreeSpace 


Reports  the  number  of  bytes  available  on  the  device  that  contains  the  current  data 
reference. 

ComponentResult  DataHGetFreeSpace  ( 

DataHandler  dh, 

unsigned  long  *freeSize  ); 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component, 
f reeSi ze 

A  pointer  to  an  unsigned  long  integer.  Your  component  returns  the  number  of 
bytes  of  free  space  available  on  the  device  that  contains  the  container  referred 
to  by  the  current  data  reference. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Before  writing  data  to  a  data  reference,  applications  must  call  your  component's 
DataHOpenForWri  te  (1-210)  function  to  open  a  write  path  to  the  container. 

DataHCl  oseForWri  te  (1-177)  closes  that  write  path.  As  is  the  case  with 
DataHSchedul  eData  (1-220),  your  component  calls  the  application's  data-handler 
completion  function  when  you  are  done  with  the  write  request. 

Special  Considerations 

Note  that  some  data  handlers  may  not  support  write  operations.  For  example,  some 
shared  devices,  such  as  a  CD-ROM  "jukebox,"  may  be  read-only  devices.  As  a 
result,  it  is  very  important  that  your  data  handler  correctly  report  its  write 
capabilities  to  client  programs. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Writing  Movie  Data"  (V-2840) 

See  Also 

Data  handlers  provide  two  distinct  write  facilities.  DataHPutData  (1-216)  is  a  simple 
synchronous  interface  that  allows  applications  to  append  data  to  the  end  of  a 
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container.  DataHWri  te  (1-232)  is  a  more  capable,  asynchronous  write  function  that  is 
suitable  for  movie  capture  operations.  There  are  several  other  helper  functions  that 
allow  applications  to  prepare  your  data  handler  for  a  movie  capture  operation. 
DataHCreateFi  1  e  (1-180)  asks  your  component  to  create  a  new  container.  The 
DataHSetFi  1  eSi  ze  (1-227)  and  DataHGetFil  eSi  ze  (1-194)  functions  work  with  a 
container's  size,  in  bytes.  The  DataHGetFreeSpace  function  allows  applications  to 
determine  when  to  make  a  container  larger.  DataFIPreextend  (1-214)  asks  your 
component  to  make  a  container  larger.  Applications  may  call  your  component's 
DataHGetPreferredBl  ockSi  ze  (1-204)  function  in  order  to  determine  how  best  to 
interact  with  your  data  handler. 


DataHGetFreeSpace64 


Provides  a  64-bit  version  of  DataHGetFreeSpace  (1-198). 

ComponentResul t  DataHGetFreeSpace64  ( 

DataHandler  dh, 

wide  *freeSize  ); 


dh 

A  data  handler  component, 
f reeSi ze 

A  pointer  to  a  64-bit  integer.  Your  component  returns  the  number  of  bytes  of 
free  space  available  on  the  device  that  contains  the  container  referred  to  by  the 
current  data  reference. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  only  difference  between  this  function  and  DataHGetFreeSpace  (1-198)  is  that  the 
f  reeSi  ze  parameter  is  a  64-bit  integer  instead  of  a  32-bit  integer. 

Special  Considerations 

New  applications  should  use  this  function  instead  of  the  32-bit  version. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 
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DataHGetlnfoFlags 


Provides  information  about  the  operation  of  a  data  handler  component. 

ComponentResul t  DataHGetlnfoFlags  ( 

DataHandler  dh, 

UInt32  *f 1 ags  ); 


dh 

A  data  handler  component, 
fl  ags 

Flags  (see  below)  that  provide  information  about  the  data  handler. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

kDataHInfoFlagNeverStreams 

The  data  handler  doesn't  stream. 
kDataHInfoFlagCanUpdate Data  Refs 

The  data  handler  might  update  the  current  data  reference. 
kDataHInfoFl agNeedsNetworkBandwi dth 

The  data  handler  may  need  to  occupy  the  current  network. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


DataHGetMacOSFileType 


Gets  the  Mac  OS  file  type  for  a  data  handler's  current  data  reference. 

ComponentResul t  DataHGetMacOSFileType  ( 

DataHandler  dh, 

OSType  *f i 1 eType  ) ; 


dh 

A  data  handler  component, 
f  i  1 eType 

A  pointer  to  a  file  type;  see  "File  Types  and  Creators"  (IV-2668). 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

See  Also 

For  the  corresponding  set  function,  see  DataHSetMacOSFi  1  eType  (1-229). 


DataHGetMIMEType 


Gets  the  MIME  type  for  a  data  handler's  current  data  reference. 

ComponentResul t  DataHGetMIMEType  ( 

DataHandler  dh, 

Str255  mimeType  ); 


dh 

A  data  handler  component, 
mi meType 

A  MIME  type  string. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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DataHGetMIMETypeAsync 


Performs  asynchronous  discovery  of  a  HTTP/FTP  connection's  MIME  type. 


ComponentResul t  DataHGetMIMETypeAsync  ( 
DataHandler  dh, 

Str255  mimeType, 

DataHCompl eti onUPP  comp! eti onRtn , 
long  refCon  ); 


dh 

A  data  handler  component. 
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mi meType 

The  MIME  type  string  when  (and  if)  it  becomes  available, 
compl eti onRtn 

A  DataHCompl  eti  onProc  (III— 2078)  callback  that  is  called  when  either  the  data 
becomes  available  or  there  is  a  failure.  Failure  can  happen  if  there  is  a  timeout 
or  DataHFi  ni  shData  (1-182)  is  called  with  a  cancel  instruction.  The  mimeType 
parameter  will  not  be  updated  until  the  complete  routine  executes.  If  a 
completion  routine  is  not  specified,  the  call  will  return  immediately. 

refCon 

A  reference  constant  to  be  passed  to  your  callback.  Use  this  parameter  to  point 
to  a  data  structure  containing  any  information  your  function  needs. 

function  result  If  the  MIME  type  is  known,  this  function  updates  mi  meType  and 
returns  noErr.  If  the  information  is  not  known  yet,  the  error 
notEnoughDataErris  returned.  This  allows  non-blocking  calls  to  be 
made  to  this  function.  If  it  returns  another  error,  that  indicates  some 
other  failure;  see  "Error  Codes"  (IV-2663). 

Discussion 

This  function  removes  synchronous  blocks  from  QuickTime's  movie  opening  code. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 
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See  Also 

DataHGetMIMEType  (1-201)  will  block  if  the  MIME  type  data  is  not  available  yet  and 
will  continue  blocking  until  either  the  information  becomes  available  or  the 
operation  times  out  in  60  seconds. 


DataHGetMovie 


Gets  the  movie  for  a  data  handler's  current  data  reference. 

ComponentResul t  DataHGetMovie  ( 

DataHandler  dh, 

Movie  *theMovie, 

short  *id  ); 


dh 

A  data  handler  component. 
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theMovi e 

A  movie  identifier.  This  is  the  same  as  the  identifier  your  application  obtains 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
i  d 

A  pointer  to  the  field  that  specifies  the  resource  containing  the  movie  data. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


DataHGetMovieWithFlags 

Gets  the  movie  for  a  data  handler's  current  data  reference,  allowing  the  flags  that 
would  be  passed  to  NewMovi  eFromDataRef  to  be  passed  to  the  handler. 

ComponentResul t  DataHGetMovieWithFlags  ( 

DataHandler  dh. 

Movie  *theMovie, 

short  *id, 

short  flags  ); 

dh 

A  data  handler  component. 
theMovi e 

A  movie  identifier.  This  is  the  same  as  the  identifier  your  application  obtains 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

i  d 

A  pointer  to  the  field  that  specifies  the  resource  containing  the  movie  data, 
fl  ags 

Flags  (see  below)  that  control  movie  characteristics. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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flags  Constants 

newMovi eActi ve 

Controls  whether  the  new  movie  is  active.  Set  this  flag  to  1  to  make  the  new 
movie  active.  You  can  make  a  movie  active  or  inactive  by  calling 
SetMovi  eActi  ve  (III — 1609). 

newMovi e Don t Res o 1 ve Data  Refs 

Controls  how  completely  the  Movie  Toolbox  resolves  data  references  in  the 
movie  resource.  If  you  set  this  flag  to  0,  the  toolbox  tries  to  completely  resolve 
all  data  references  in  the  resource.  This  may  involve  searching  for  files  on 
remote  volumes.  If  you  set  this  flag  to  1,  the  toolbox  only  looks  in  the  specified 
data  reference.  If  the  toolbox  cannot  completely  resolve  all  the  data  references, 
it  still  returns  a  valid  movie  identifier.  In  this  case,  the  toolbox  also  sets  the 
current  error  value  to  coul  dNotResol  veDataRef. 
newMovi  e  Don  t  As  kiln  resol  ved  Data  Refs 

Controls  whether  the  Movie  Toolbox  asks  the  user  to  locate  files.  If  you  set  this 
flag  to  0,  the  toolbox  asks  the  user  to  locate  files  that  it  cannot  find  on  available 
volumes.  If  the  toolbox  cannot  locate  a  file,  even  with  the  user's  help,  the 
function  returns  a  valid  movie  identifier  and  sets  the  current  error  value  to 
coul  dNotResol  veDataRef. 
newMovi eDontAutoAlternate 

Controls  whether  the  Movie  Toolbox  automatically  selects  enabled  tracks  from 
alternate  track  groups.  If  you  set  this  flag  to  1,  the  Movie  Toolbox  does  not 
automatically  select  tracks  for  the  movie;  you  must  enable  and  disable  tracks 
yourself. 

Discussion 

Passing  these  flags  lets  you  control  whether  or  not  the  movie  returned  is  active. 
Additionally,  it  allows  async  movie  loading  to  be  more  efficient. 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

See  Also 

NewMovi  eFromDataRef  (11-1078). 


DataHGetPreferredBlockSize 


Reports  the  block  size  that  it  prefers  to  use  when  accessing  the  current  data 
reference. 
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ComponentResul t 
DataHandl er 
1  ong 


DataHGetPref erredBl ockSi ze 
dh , 

*bl ockSi ze  ); 


( 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component, 
bl  ockSi  ze 

A  pointer  to  a  long  integer.  Your  component  returns  the  size  of  blocks  (in  bytes) 
it  prefers  to  use  when  accessing  the  current  data  reference. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Different  devices  use  different  file  system  block  sizes.  This  function  allows  your 
component  to  report  its  preferred  block  size  to  the  client  program.  Note  that  the 
client  program  is  not  required  to  use  this  block  size  when  making  requests.  Some 
clients  may,  however,  try  to  accommodate  your  component's  preference. 
Applications  may  call  your  component's  DataHGetPref  erredBl  ockSi  ze  function  in 
order  to  determine  how  best  to  interact  with  your  data  handler.  As  is  the  case  with 
DataHSchedul  eData  (1-220),  your  component  calls  the  application's  data-handler 
completion  function  when  you  are  done  with  the  write  request. 

Special  Considerations 

Note  that  some  data  handlers  may  not  support  write  operations.  For  example,  some 
shared  devices,  such  as  a  CD-ROM  "jukebox,"  may  be  read-only  devices.  As  a 
result,  it  is  very  important  that  your  data  handler  correctly  report  its  write 
capabilities  to  client  programs. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Writing  Movie  Data"  (V-2840) 

See  Also 

Data  handlers  provide  two  distinct  write  facilities.  DataHPutData  (1-216)  is  a  simple 
synchronous  interface  that  allows  applications  to  append  data  to  the  end  of  a 
container.  DataHWri  te  (1-232)  is  a  more  capable,  asynchronous  write  function  that  is 
suitable  for  movie  capture  operations.  There  are  several  other  helper  functions  that 
allow  applications  to  prepare  your  data  handler  for  a  movie  capture  operation. 
DataHCreateFi  1  e  (1-180)  asks  your  component  to  create  a  new  container.  The 
DataHSetFi  1  eSi  ze  (1-227)  and  DataHGetFi  1  eSi  ze  (1-194)  functions  work  with  a 
container's  size,  mbytes.  The  DataHGetFreeSpace  (1-198)  function  allows 
applications  to  determine  when  to  make  a  container  larger.  DataHPreextend  (1-214) 


Inside  QuickTime:  Functions  A-H 


1-205 


DataHGetScheduleAheadTime 


asks  your  component  to  make  a  container  larger.  Before  writing  data  to  a  data 
reference,  applications  must  call  your  component's  DataHOpenForWri  te  (1-210) 
function  to  open  a  write  path  to  the  container.  DataHCloseForWrite  (1-177)  closes 
that  write  path. 


DataHGetSchedule  AheadT  ime 


Reports  how  far  in  advance  it  prefers  clients  to  issue  read  requests. 

ComponentResul t  DataHGetScheduleAheadTime  ( 

DataHandler  dh, 

1 ong  *mi 1 1 i secs  ) ; 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component, 
mi  1 1 1  secs 

A  pointer  to  a  long  integer.  Your  component  should  set  this  field  with  a  value 
indicating  the  number  of  milliseconds  you  prefer  to  receive  read  requests  in 
advance  of  the  time  when  the  data  must  be  delivered. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  allows  your  data  handler  to  tell  the  client  program  how  far  in  advance 
it  should  schedule  its  read  requests.  By  default,  the  Movie  Toolbox  issues  scheduled 
read  requests  between  1  and  2  seconds  before  it  needs  the  data  from  those  requests. 
For  some  data  handlers,  however,  this  may  not  be  enough  time.  For  example,  some 
data  handlers  may  have  to  accommodate  network  delays  when  processing  read 
requests.  Client  programs  that  call  DataHGetSchedul  eAheadT i  me  may  try  to  respect 
your  component's  preference. 

Special  Considerations 

Note  that  not  all  client  programs  will  call  DataHGetScheduleAheadTime.  Further,  some 
clients  may  not  be  able  to  accommodate  your  preferred  time  in  all  cases,  even  if  they 
have  asked  for  your  component's  preference.  As  a  result,  your  component  should 
have  a  strategy  for  handling  requests  that  don't  provide  enough  advanced 
scheduling  time.  For  example,  if  your  component  receives  a  DataHSchedul  eData 
(1-220)  request  that  it  cannot  satisfy,  it  can  fail  the  request  with  an  appropriate  error 
code. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Reading  Movie  Data"  (V-2839) 

See  Also 

Data  handler  components  provide  two  basic  read  facilities.  DataHGetData  (1-186) 
function  is  a  fully  synchronous  read  operation,  while  DataHSchedul  eData  (1-220)  is 
asynchronous.  Client  programs  queue  read  requests  by  calling  DataHSchedul  eData 
with  scheduling  information.  When  your  component  processes  the  queued  request, 
it  calls  the  application's  data-handler  completion  function.  By  calling  your 
component's  DataHFi  ni  shData  (1-182)  function,  applications  can  force  your 
component  to  process  queued  read  requests.  Before  any  application  can  read  data 
from  a  data  reference,  it  must  open  read  access  to  that  reference  by  calling  your 
component's  DataHOpenForRead  (1-209)  function.  DataHCl  oseForRead  (1-176)  closes 
that  read  access  path. 


DataHGetVolumeList 


Returns  a  list  of  the  volumes  your  component  can  access,  along  with  flags  indicating 
your  component's  capabilities  for  each  volume. 

ComponentResul t  DataHGetVolumeList  ( 

DataHandler  dh, 

DataHVol  umeLi  st  *vol  umeLi  st  ); 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component, 
vol  umeLi  st 

A  pointer  to  a  field  that  your  data  handler  component  uses  to  return  a  handle 
to  a  volume  list.  Your  component  constructs  the  volume  list  by  allocating  a 
handle  and  filling  it  with  a  series  of  DataHVol  umeLi  stRecord  (IV-2230) 
structures,  one  structure  for  each  volume  your  component  can  access. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

To  reduce  the  delay  that  may  result  from  choosing  an  appropriate  data  handler  for 
a  volume,  the  Movie  Toolbox  maintains  a  list  of  data  handlers  and  the  volumes  they 
support.  The  Movie  Toolbox  uses  DataHGetVol  umeLi  st  to  build  that  list.  Your  data 
handler  may  use  any  facilities  necessary  to  determine  whether  it  can  access  the 
volume,  including  opening  a  container  on  the  volume.  Your  component  should  set 
to  1  as  many  of  the  capability  flags  as  are  appropriate  for  each  volume.  Don't 
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DataHIsStreamingDataHandler 


include  records  for  volumes  your  handler  cannot  support.  For  example,  if  your 
component  supports  networked  multimedia  servers  using  a  special  set  of  protocols, 
your  data  handler  should  set  the  kDataHCanRead  and  kDataHCanSpeci  al  Read  flags  to 
1  for  any  volume  that  is  on  that  server.  In  addition,  if  your  component  can  write  to 
a  volume  on  the  server,  set  the  kDataHCanWri  te  and  kDataHCanSpeci  al  Wri  te  flags  to 
1  (perhaps  along  with  kDataHCanStreami  ngWri  te).  However,  your  component 
should  create  entries  only  for  those  volumes  that  support  your  protocols. 

Special  Considerations 

It  is  the  calling  program's  responsibility  to  dispose  of  the  handle  returned  by  your 
component.  The  Movie  Toolbox  tracks  mounting  and  unmounting  removable 
volumes,  and  keeps  its  volume  list  current.  As  a  result,  the  Movie  Toolbox  may  call 
your  component's  DataHGetVol  umeLi  st  function  whenever  a  removable  volume  is 
mounted.  If  your  data  handler  does  not  process  data  that  is  stored  in  file  system 
volumes,  you  need  not  support  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Selecting  a  Data  Handler"  (V-2838) 


DataHIsStreamingDataHandler 


Determines  if  a  data  handler  handles  streaming  data. 

ComponentResul t  DataHIsStreamingDataHandler  ( 
DataHandler  dh, 

Bool ean  *yes  ) ; 


dh 

A  data  handler  component. 

yes 

Pointer  to  a  Boolean  that  returns  TRUE  if  the  data  handler  handles  streaming 
data,  FALSE  otherwise. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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DataHOpenForRead 

Opens  a  data  handler's  current  data  reference  for  read-only  access. 

ComponentResul t  DataHOpenForRead  ( 

DataHandler  dh  ); 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

After  setting  your  component's  current  data  reference  by  calling  DataHSetDataRef 
(1-224),  client  programs  call  DataHOpenForRead  to  start  reading  from  the  data 
reference.  Your  component  should  open  the  data  reference  for  read-only  access.  If 
the  data  reference  is  already  open  or  cannot  be  opened,  return  an  appropriate  error 
code.  As  is  the  case  with  DataHScheduleData  (1-220),  your  component  calls  the 
application's  data-handler  completion  function  when  you  are  done  with  the  write 
request. 

Special  Considerations 

Note  that  the  Movie  Toolbox  may  try  to  read  data  from  a  data  reference  without 
calling  your  component's  DataHOpenForRead  function.  If  this  happens,  your 
component  should  open  the  data  reference  for  read-only  access,  respond  to  the  read 
request,  and  then  leave  the  data  reference  open  in  anticipation  of  later  read  requests. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Reading  Movie  Data"  (V-2839) 

See  Also 

Data  handler  components  provide  two  basic  read  facilities.  DataHGetData  (1-186) 
function  is  a  fully  synchronous  read  operation,  while  DataHSchedul  eData  (1-220)  is 
asynchronous.  By  calling  your  component's  DataHFi  ni  shData  (1-182)  function, 
applications  can  force  your  component  to  process  queued  read  requests. 
Applications  may  call  your  component's  DataHGetSchedul  eAheadTime  (1-206) 
function  in  order  to  determine  how  far  in  advance  your  component  prefers  to  get 
read  requests.  Before  any  application  can  read  data  from  a  data  reference,  it  must 
open  read  access  to  that  reference  by  calling  your  component's  DataHOpenForRead 
function.  DataHCloseForRead  (1-176)  closes  that  read  access  path. 
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DataHOpenForWrite 


DataHOpenForW  rite 

Opens  your  component's  current  data  reference  for  write-only  access. 

ComponentResul t  DataHOpenForWrite  ( 

DataHandl er  dh  ) ; 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

After  setting  your  component's  current  data  reference  by  calling  DataHSetDataRef 
(1-224),  client  programs  call  DataHOpenForWriteto  start  writing  to  the  data  reference. 
Your  component  should  open  the  data  reference  for  write-only  access.  If  the  data 
reference  is  already  open  or  cannot  be  opened,  return  an  appropriate  error  code.  As 
is  the  case  with  DataHSchedul  eData  (1-220),  your  component  calls  the  application's 
data-handler  completion  function  when  you  are  done  with  the  write  request. 

Special  Considerations 

Note  that  some  data  handlers  may  not  support  write  operations.  For  example,  some 
shared  devices,  such  as  a  CD-ROM  "jukebox,"  may  be  read-only  devices.  As  a 
result,  it  is  very  important  that  your  data  handler  correctly  report  its  write 
capabilities  to  client  programs. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Writing  Movie  Data"  (V-2840) 

See  Also 

Data  handlers  provide  two  distinct  write  facilities.  DataHPutData  (1-216)  is  a  simple 
synchronous  interface  that  allows  applications  to  append  data  to  the  end  of  a 
container.  DataHWriteisa  more  capable,  asynchronous  write  function  that  is 
suitable  for  movie  capture  operations.  There  are  several  other  helper  functions  that 
allow  applications  to  prepare  your  data  handler  for  a  movie  capture  operation. 
DataHCreateFi  1  e  (1-180)  asks  your  component  to  create  a  new  container.  The 
DataHSetFi  1  eSi  ze  (1-227)  and  DataHGetFi  1  eSi  ze  (1-194)  functions  work  with  a 
container's  size,  mbytes.  The  DataHGetFreeSpace  (1-198)  function  allows 
applications  to  determine  when  to  make  a  container  larger.  DataHPreextend  (1-214) 
asks  your  component  to  make  a  container  larger.  Applications  may  call  your 
component's  DataHGetPref  erredBl  ockSi  ze  (1-204)  function  in  order  to  determine 
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how  best  to  interact  with  your  data  handler.  Before  writing  data  to  a  data  reference, 
applications  must  call  your  component's  DataHOpenForWrite  function  to  open  a 
write  path  to  the  container.  DataHCl  oseForWri  te  (1-177)  closes  that  write  path. 


DataHPlaybackHints 


Provides  additional  information  to  your  component  that  you  may  use  to  optimize 
the  operation  of  your  data  handler. 


Component  Res  ill  t  DataHPlaybackHints 


DataHandl er 
1  ong 

unsigned  long 
unsigned  long 
1  ong 


dh , 

fl ags , 

mi n  F i 1 eOf f set , 
maxFi 1 eOf f set , 
bytesPerSecond 


); 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component, 
fl  ags 

Reserved.  Set  this  parameter  to  0. 
mi n  F i 1 eOf f set 

Together  with  the  maxFi  leOffset  parameter,  specifies  the  range  of  data  the 
client  program  anticipates  using  from  the  current  data  reference.  This 
parameter  specifies  the  offset  of  earliest  byte  the  program  expects  to  use  (that 
is,  the  minimum  container  offset  value).  If  the  client  expects  to  access  bytes 
from  the  beginning  of  the  container,  it  should  set  this  parameter  to  0. 

maxFi 1 eOf f set 

The  offset  of  the  latest  byte  the  program  expects  to  use  (that  is,  the  maximum 
container  offset  value).  If  the  client  expects  to  use  bytes  throughout  the 
container,  the  client  should  set  this  parameter  to  -1. 

bytesPerSecond 

The  rate  in  bytes  per  second  at  which  your  data  handler  must  read  data  from 
the  data  reference  in  order  to  keep  up  with  the  client  program's  anticipated 
needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Applications  may  call  your  handler's  DataHPlaybackHints  function  to  provide  you 
with  some  guidelines  about  how  those  applications  plan  to  use  the  current  data 
reference.  Your  component  should  be  prepared  to  have  this  function  called  more 
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than  once  for  a  given  data  reference.  For  example,  the  Movie  Toolbox  calls  this 
function  whenever  a  movie's  playback  rate  changes.  This  is  a  handy  way  for  your 
data  handler  to  track  playback  rate  changes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Managing  Data  Handler  Components"  (V-2841) 


DataHPlaybackHints64 


Provides  a  64-bit  version  of  DataHPI  aybackHi  nts  (1-211). 


ComponentResul t 
DataHandl er 
1  ong 

const  wide 
const  wide 
1  ong 


DataHPI aybackHi nts64 
dh , 

fl ags , 

*mi n  F i 1 eOffset , 
*maxFi 1 eOffset , 
bytesPerSecond  ) ; 


( 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component, 
fl  ags 

Reserved.  Set  this  parameter  to  0. 
mi n  F i 1 eOffset 

Together  with  the  maxFi  1  eOffset  parameter,  specifies  the  range  of  data  the 
client  program  anticipates  using  from  the  current  data  reference.  This 
parameter  points  to  the  offset  of  the  earliest  byte  the  program  expects  to  use 
(that  is,  the  minimum  container  offset  value).  If  the  client  expects  to  access  bytes 
from  the  beginning  of  the  container,  it  should  set  this  parameter  to  0. 
maxFi 1 eOffset 

Pointer  to  the  offset  of  the  latest  byte  the  program  expects  to  use  (that  is,  the 
maximum  container  offset  value).  If  the  client  expects  to  use  bytes  throughout 
the  container,  the  client  should  set  this  parameter  to  -1. 

bytesPerSecond 

The  rate  in  bytes  per  second  at  which  your  data  handler  must  read  data  from 
the  data  reference  in  order  to  keep  up  with  the  client  program's  anticipated 
needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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flags  Constants 
Discussion 

The  only  difference  between  this  function  and  DataHPlaybackHints  (1-211)  is  that  the 
minFileOffset  parameter  andmaxFileOffset  parameter  are  64-bit  integers  instead  of 
32-bit  integers. 

Special  Considerations 

New  applications  should  use  this  function  instead  of  the  32-bit  version. 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

See  Also 

See  DataHPl  aybackHi  nts  (1-211). 


DataHPollRead 


Undocumented 

ComponentResul t  DataHPollRead  ( 
DataHandler  dh, 

void  *dataPtr, 

UInt32  *dataSizeSoFar  ); 


dh 

A  data  handler  component. 
dataPtr 

Undocumented 
dataSi zeSoFar 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 
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DataHPreextend 


Allocates  new  space  for  the  current  data  reference,  enlarging  the  container. 

ComponentResul t  DataHPreextend  ( 

DataHandler  dh, 

unsigned  long  maxToAdd, 

unsigned  long  *spaceAdded  ); 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component. 
maxToAdd 

The  amount  of  space  to  add  to  the  current  data  reference,  in  bytes.  If  the  client 
program  sets  this  parameter  to  0,  your  component  should  add  as  much  space 
as  it  can. 
spaceAdded 

A  pointer  to  an  unsigned  long  integer.  Your  component  returns  the  number  of 
bytes  it  was  able  to  add  to  the  data  reference,  in  bytes. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  asks  your  component  to  make  a  container  larger,  analogous  to  the 
Mac  OS  File  Manager's  PBAllocContig  function.  When  it  is  called,  your  component 
should  allocate  contiguous  free  space.  If  there  is  not  sufficient  contiguous  free  space 
to  satisfy  the  request,  your  component  should  return  adskFulErr  error  code.  Client 
programs  use  this  function  in  order  to  avoid  incurring  any  space-allocation  delay 
when  capturing  movie  data.  As  is  the  case  with  DataHSchedul  eData  (1-220),  your 
component  calls  the  application's  data-handler  completion  function  when  you  are 
done  with  the  write  request. 

Special  Considerations 

Note  that  some  data  handlers  may  not  support  write  operations.  For  example,  some 
shared  devices,  such  as  a  CD-ROM  "jukebox,"  may  be  read-only  devices.  As  a 
result,  it  is  very  important  that  your  data  handler  correctly  report  its  write 
capabilities  to  client  programs. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Writing  Movie  Data"  (V-2840) 
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See  Also 

Data  handlers  provide  two  distinct  write  facilities.  DataHPutData  (1-216)  is  a  simple 
synchronous  interface  that  allows  applications  to  append  data  to  the  end  of  a 
container.  DataHWri  te  (1-232)  is  a  more  capable,  asynchronous  write  function  that  is 
suitable  for  movie  capture  operations.  There  are  several  other  helper  functions  that 
allow  applications  to  prepare  your  data  handler  for  a  movie  capture  operation. 
DataHCreateFi  1  e  (1-180)  asks  your  component  to  create  a  new  container.  The 
DataHSetFi  1  eSi  ze  (1-227)  and  DataHGetFi  1  eSi  ze  (1-194)  functions  work  with  a 
container's  size,  mbytes.  The  DataHGetFreeSpace  (1-198)  function  allows 
applications  to  determine  when  to  make  a  container  larger.  Applications  may  call 
your  component's  DataHGetPreferredBl  ockSi  ze  (1-204)  function  in  order  to 
determine  how  best  to  interact  with  your  data  handler.  Before  writing  data  to  a  data 
reference,  applications  must  call  your  component's  DataHOpenForWri  te  (1-210) 
function  to  open  a  write  path  to  the  container.  DataHCloseForWrite  (1-177)  closes 
that  write  path. 


DataHPreextend64 


Provides  a  64-bit  version  of  DataHPreextend  (1-214). 

ComponentResul t  DataHPreextend64  ( 

DataHandler  dh, 

const  wide  *maxToAdd, 

wide  *spaceAdded  ); 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component. 
maxToAdd 

The  amount  of  space  to  add  to  the  current  data  reference,  in  bytes.  If  the  client 
program  sets  this  parameter  to  0,  your  component  should  add  as  much  space 
as  it  can. 

spaceAdded 

A  pointer  to  a  64-bit  integer.  Your  component  returns  the  number  of  bytes  it 
was  able  to  add  to  the  data  reference,  in  bytes. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  only  difference  between  this  function  and  DataHPreextend  (1-214)  is  that  the 
spaceAdded  parameter  is  a  64-bit  integer  instead  of  a  32-bit  integer. 
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Special  Considerations 

New  applications  should  use  this  function  instead  of  the  32-bit  version. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

See  Also 

See  DataHPreextend  (1-214). 


DataHPutData 


Writes  data  to  a  component's  current  data  reference. 


ComponentResul t 
DataHandl er 
Handl e 
1  ong 
1  ong 
1  ong 


DataHPutData  ( 
dh , 
h , 

hOffset , 
*offset , 
size  ) ; 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component, 
h 

The  handle  that  contains  the  data  to  be  written  to  the  data  reference. 
hOffset 

Identifies  the  offset  into  the  handle  h  to  the  data  to  be  written, 
offset 

A  pointer  to  a  long  integer.  Your  component  returns  the  offset  in  the  data 
reference  at  which  your  component  wrote  the  data. 

si  ze 

The  number  of  bytes  to  write. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  provides  a  high-level  write  interface.  This  is  a  synchronous  write 
operation  that  only  appends  data  to  the  end  of  the  current  data  reference.  That  is, 
the  client  program's  execution  is  blocked  until  your  component  returns  control 
from  this  function,  and  the  client  cannot  control  where  the  data  is  written.  As  a 
result,  most  movie-capture  clients  (for  example,  Apple's  sequence  grabber 
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component)  use  DataHWrite  (1-232)  to  write  data  when  creating  movies.  As  is  the 
case  with  DataHSchedul  eData  (1-220),  your  component  calls  the  application's 
data-handler  completion  function  when  you  are  done  with  the  write  request. 

Special  Considerations 

Note  that  some  data  handlers  may  not  support  write  operations.  For  example,  some 
shared  devices,  such  as  a  CD-ROM  "jukebox,"  may  be  read-only  devices.  As  a 
result,  it  is  very  important  that  your  data  handler  correctly  report  its  write 
capabilities  to  client  programs. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 
Programming  summary:  "Writing  Movie  Data"  (V-2840) 

See  Also 

Data  handlers  provide  two  distinct  write  facilities.  DataHPutData  is  a  simple 
synchronous  interface  that  allows  applications  to  append  data  to  the  end  of  a 
container.  DataHWri  te  (1-232)  is  a  more  capable,  asynchronous  write  function  that  is 
suitable  for  movie  capture  operations.  There  are  several  other  helper  functions  that 
allow  applications  to  prepare  your  data  handler  for  a  movie  capture  operation. 
DataHCreateFi  1  e  (1-180)  asks  your  component  to  create  a  new  container.  The 
DataHSetFi  1  eSi  ze  (1-227)  and  DataHGetFi  1  eSi  ze  (1-194)  functions  work  with  a 
container's  size,  in  bytes.  The  DataHGetFreeSpace  (1-198)  function  allows 
applications  to  determine  when  to  make  a  container  larger.  DataHPreextend  (1-214) 
asks  your  component  to  make  a  container  larger.  Applications  may  call  your 
component's  DataHGetPreferredBl  ockSi  ze  (1-204)  function  in  order  to  determine 
how  best  to  interact  with  your  data  handler.  Before  writing  data  to  a  data  reference, 
applications  must  call  your  component's  DataHOpenForWrite  (1-210)  function  to 
open  a  write  path  to  the  container.  DatallCl  oseForWri  te  (1-177)  closes  that  write 
path.  Client  programs  can  force  your  component  to  write  any  cached  data  by  calling 
your  component's  DataHFlushData  (1-184)  function. 


DataHReadAsync 


Undocumented 


ComponentResul t 
DataHandl er 
void 
UInt32 
const  wide 


DataHReadAsync  ( 
dh , 

*dataPtr, 
dataSi ze , 
*data0f f set , 
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DataHCompl eti onUPP  completion, 

1 ong  refCon  ) ; 


dh 

A  data  handler  component. 
dataPtr 

Undocumented 
dataSi ze 

Undocumented 

dataOffset 

Undocumented 
compl eti on 

A  pointer  to  a  data-handler  completion  callback,  described  in 
DataHCompl  eti  onProc  (III — 2078). 
refCon 

A  reference  constant  to  be  passed  to  your  callback.  Use  this  parameter  to  point 
to  a  data  structure  containing  any  information  your  function  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


DataHResolveDataRef 


Locates  the  container  associated  with  a  given  data  reference. 


ComponentResul t 
DataHandl er 
Handl e 
Bool ean 
Bool ean 


DataHResolveDataRef  ( 
dh , 

theDataRef , 
*wasChanged , 
userlnterfaceAll owed 


) : 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component. 
theDataRef 

The  data  reference  to  be  resolved.  Different  types  of  containers  may  require 
different  types  of  data  references.  For  example,  a  reference  to  a  memory-based 
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movie  may  be  a  handle,  while  a  reference  to  a  file-based  movie  may  be  an  alias. 
Apple's  memory-based  data  handler  for  the  Macintosh  uses  handles  (and  has  a 
subtype  value  of  ’  hndl  ’),  while  the  HFS  data  handler  uses  Alias  Manager 
aliases  (its  subtype  value  is  ’alls’).  See  "Data  References"  (IV-2661). 

wasChanged 

A  pointer  to  a  Bool  ean.  Your  component  should  set  that  Bool  ean  to  TRUE  if,  in 
locating  the  container,  your  data  handler  updates  any  information  in  the  data 
reference. 

userlnterfaceAl 1  owed 

Indicates  whether  your  component  may  interact  with  the  user  when  locating 
the  container.  If  this  parameter  is  set  to  TRUE,  your  component  may  ask  the  user 
to  help  locate  the  container  (for  instance,  by  presenting  a  Find  File  dialog  box). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  permits  your  component  to  locate  a  data  reference's  container.  This 
function  is  equivalent  to  the  Mac  OS  Alias  Manager's  Resol  veAl  i  as  function.  The 
client  program  asks  your  component  to  locate  the  container  that  is  associated  with 
a  given  data  reference.  If  your  component  determines  that  the  data  reference  needs 
to  be  updated  with  more  accurate  location  information,  it  should  put  the  new 
information  in  the  supplied  data  reference  (and  set  the  Boolean  referred  to  by  the 
wasChanged  parameter  to  TRUE).  Client  programs  can  correlate  data  references  with 
data  handlers  by  matching  the  component's  subtype  value  with  the  data  reference 
type;  the  subtype  value  indicates  the  type  of  data  reference  the  component 
supports.  All  data  handlers  with  the  same  subtype  value  must  support  the  same 
data  reference  type. 

Special  Considerations 

Client  programs  may  call  your  data  handler's  DataHResolveDataRef  function  at  any 
time.  Typically,  however,  the  Movie  Toolbox  uses  this  function  as  part  of  its  strategy 
for  opening  and  reading  a  movie  container.  As  such,  you  can  expect  that  the 
supplied  data  reference  will  identify  a  container  that  your  component  can  support. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Identifying  Data  References"  (V-2839) 

See  Also 

DataHSetDataRef  (1-224)  and  DataHGetDataRef  (1-189)  allow  applications  to  assign 
your  data  handler's  current  data  reference.  DataHCompareDataRef  (1-178)  asks  your 
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component  to  compare  a  data  reference  against  the  current  data  reference  and 
indicate  whether  the  references  are  equivalent  (that  is,  refer  to  the  same  container). 


DataHScheduleData 


Reads  data  from  its  current  data  reference,  which  can  be  a  synchronous  read 
operation  or  an  asynchronous  read  operation. 


ComponentResul t  DataHScheduleData  ( 


DataHandl er 
Ptr 
1  ong 
1  ong 
1  ong 

DataHSchedul ePtr 
DataHCompl eti on  U  P  P 


dh , 

PI aceToPutDataPtr , 
FI  1 eOffset , 

DataSi ze , 

RefCon , 
schedul eRec , 

Compl eti onRtn  ) ; 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component. 

PI aceToPutDataPtr 

The  location  in  memory  that  is  to  receive  the  data. 

Fi 1 eOffset 

The  offset  in  the  data  reference  from  which  your  component  is  to  read. 

DataSi ze 

The  number  of  bytes  to  read. 

RefCon 

A  reference  constant  that  your  data  handler  component  should  provide  to  the 
data-handler  completion  function  specified  with  the  Compl  eti  onRtn  parameter. 

schedul eRec 

A  pointer  to  a  DataHSchedul  eRecord  (IV-2229).  If  this  parameter  is  set  to  NIL, 
then  the  client  program  is  requesting  a  synchronous  read  operation  (that  is, 
your  data  handler  must  return  the  data  before  returning  control  to  the  client 
program).  If  this  parameter  is  not  set  to  NIL,  it  must  contain  the  location  of  a 
schedule  record  that  has  timing  information  for  an  asynchronous  read  request. 
Your  data  handler  should  return  control  to  the  client  program  immediately, 
and  then  call  the  client's  data-handler  completion  function  when  the  data  is 
ready. 
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Compl eti onRtn 

A  pointer  to  a  data  handler  completion  function,  described  in 
DataHCompl  eti  on  P roc  (III— 2078).  The  client  program  must  provide  a  completion 
routine  for  all  asynchronous  read  requests  (that  is,  all  requests  that  include  a 
valid  schedule  record).  For  synchronous  requests,  client  programs  should  set 
this  parameter  to  NIL.  However,  if  the  function  is  provided,  your  handler  must 
call  it,  even  after  synchronous  requests.  When  your  data  handler  finishes  with 
the  client  program's  read  request,  your  component  must  call  this  routine  even 
if  the  request  fails.  Your  component  should  pass  the  reference  constant  that  the 
client  program  provided  with  the  Ref  Con  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  provides  both  a  synchronous  and  an  asynchronous  read  interface. 
Synchronous  read  operations  work  like  the  DataHGetData  (1-186)  function;  the  data 
handler  component  returns  control  to  the  client  program  only  after  it  has  serviced 
the  read  request.  Asynchronous  read  operations  allow  client  programs  to  schedule 
read  requests  in  the  context  of  a  specified  QuickTime  time  base.  Your  data  handler 
queues  the  request  and  immediately  returns  control  to  the  calling  program.  After 
your  component  actually  reads  the  data,  it  calls  the  client  program's  data-handler 
completion  function.  If  your  component  cannot  satisfy  the  request  (for  example,  the 
request  requires  data  more  quickly  than  you  can  deliver  it),  your  component  should 
reject  the  request  immediately,  rather  than  queuing  the  request  and  then  calling  the 
client's  data-handler  completion  function. 

typedef  struct  DataHSchedul eRecord  { 

TimeRecord  timeNeededBy ;  /*  schedule  info  */ 
long  extendedID;  /*  type  of  data  */ 
long  extendedVers ;  /*  reserved  */ 

Fixed  priority;  /*  priority  */ 

}  DataHSchedul eRecord ,  *DataHSchedul ePtr ; 

Special  Considerations 

Note  that  the  Movie  Toolbox  may  try  to  read  data  from  a  data  reference  without 
calling  your  component's  DataHOpenForRead  (1-209)  function.  If  this  happens,  your 
component  should  open  the  data  reference  for  read-only  access,  respond  to  the  read 
request,  and  then  leave  the  data  reference  open  in  anticipation  of  later  read  requests. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Reading  Movie  Data"  (V-2839) 

See  Also 

Data  handler  components  provide  two  basic  read  facilities  .DataHGetData  function  is 
a  fully  synchronous  read  operation,  while  DataHScheduleData  is  asynchronous. 
When  your  component  processes  the  queued  request,  it  calls  the  application's 
data-handler  completion  function.  By  calling  your  component's  DataHFinishData 
(1-182)  function,  applications  can  force  your  component  to  process  queued  read 
requests.  Applications  may  call  your  component's  DataHGetSchedul  eAheadT ime 
(1-206)  function  in  order  to  determine  how  far  in  advance  your  component  prefers 
to  get  read  requests.  Before  any  application  can  read  data  from  a  data  reference,  it 
must  open  read  access  to  that  reference  by  calling  your  component's 
DataHOpenForRead  (1-209)  function.  DataHCloseForRead  (1-176)  closes  that  read  access 
path.  Client  programs  can  force  your  component  to  invalidate  any  cached  data  by 
calling  your  component's  DataHFl  ushCache  (1-184)  function. 


DataHScheduleData64 


Provides  a  64-bit  version  of  DataHSchedul  eData  (1-220). 


ComponentResul t  DataHSchedul eData64  ( 


DataHandl er 
Ptr 

const  wide 
1  ong 
1  ong 

DataHSchedul ePtr 
DataHCompl eti onUPP 


dh , 

PI aceToPutDataPtr , 
*Fi 1 eOffset , 

DataSi ze , 

RefCon , 
schedul eRec , 

Compl eti onRtn  ) ; 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component. 
PI aceToPutDataPtr 

The  location  in  memory  that  is  to  receive  the  data. 

Fi 1 eOffset 

A  pointer  to  the  offset  in  the  data  reference  from  which  your  component  is  to 
read. 

DataSi ze 

The  number  of  bytes  to  read. 
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RefCon 

A  reference  constant  that  your  data  handler  component  should  provide  to  the 
data-handler  completion  function  specified  with  the  Compl  eti  onRtn  parameter, 
schedul eRec 

A  pointer  to  a  DataHSchedul  eRecord  (IV-2229).  If  this  parameter  is  set  to  NIL, 
then  the  client  program  is  requesting  a  synchronous  read  operation  (that  is, 
your  data  handler  must  return  the  data  before  returning  control  to  the  client 
program).  If  this  parameter  is  not  set  to  NIL,  it  must  contain  the  location  of  a 
schedule  record  that  has  timing  information  for  an  asynchronous  read  request. 
Your  data  handler  should  return  control  to  the  client  program  immediately, 
and  then  call  the  client's  data-handler  completion  function  when  the  data  is 
ready. 

Compl eti onRtn 

A  pointer  to  a  data  handler  completion  function,  described  in 
DataHCompl  eti  on  P roc  (III— 2078).  The  client  program  must  provide  a  completion 
routine  for  all  asynchronous  read  requests  (that  is,  all  requests  that  include  a 
valid  schedule  record).  For  synchronous  requests,  client  programs  should  set 
this  parameter  to  NIL.  However,  if  the  function  is  provided,  your  handler  must 
call  it,  even  after  synchronous  requests.  When  your  data  handler  finishes  with 
the  client  program's  read  request,  your  component  must  call  this  routine  even 
if  the  request  fails.  Your  component  should  pass  the  reference  constant  that  the 
client  program  provided  with  the  RefCon  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  only  difference  between  this  function  and  DataHSchedul  eData  (1-220)  is  that  the 
Fi  1  eOf  f  set  parameter  is  a  64-bit  integer  instead  of  a  32-bit  integer. 

Special  Considerations 

New  applications  should  use  this  function  instead  of  the  32-bit  version. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

See  Also 

See  DataHSchedul  eData  (1-220). 
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DataHSetCacheSizeLimit 


Sets  the  cache  size  limit  for  a  data  handler  component. 

ComponentResul t  DataHSetCacheSizeLimit  ( 
DataHandler  dh, 

Size  cacheSi zeLi mi t  ); 


dh 

A  data  handler  component. 
cacheSi zeLi mi t 

A  pointer  to  the  cache  size  limit. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

See  Also 

For  the  corresponding  get  function,  see  DataHGetCacheSi  zeLi  mi  t  (1-185). 


DataHSetDataRef 


Assigns  a  data  reference  to  your  data  handler  component. 

ComponentResul t  DataHSetDataRef  ( 

DataHandler  dh, 

Handl e  dataRef  ) ; 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component. 
dataRef 

The  data  reference.  This  parameter  contains  a  handle  to  the  information  that 
identifies  the  container  in  question.  Different  types  of  containers  may  require 
different  types  of  data  references.  For  example,  a  reference  to  a  memory-based 
movie  may  be  a  handle,  while  a  reference  to  a  file-based  movie  may  be  an  alias. 
For  example,  Apple's  memory-based  data  handler  for  the  Macintosh  uses 
handles  (and  has  a  subtype  value  of  '  hndl ' ),  while  the  HFS  data  handler  uses 
Alias  Manager  aliases  (its  subtype  value  is  'alls').  The  client  program  is 
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DataHSetDataRefExtension 


responsible  for  disposing  of  the  handle,  so  your  component  must  make  a  copy 
of  it.  See  "Data  References"  (IV-2661). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  allows  your  application  to  assign  your  data  handler's  current  data 
reference.  All  data  handler  components  use  data  references  to  identify  and  locate  a 
movie's  container.  Client  programs  can  correlate  data  references  with  data  handlers 
by  matching  the  component's  subtype  value  with  the  data  reference  type;  the 
subtype  value  indicates  the  type  of  data  reference  the  component  supports.  All  data 
handlers  with  the  same  subtype  value  must  support  the  same  data  reference  type. 

Special  Considerations 

Note  that  the  type  of  data  reference  always  corresponds  to  the  type  that  your 
component  supports,  and  that  you  specify  in  the  component  subtype  value  of  your 
data  handler.  As  a  result,  the  client  program  does  not  provide  a  data  reference  type 
value  (unlike  the  Movie  Toolbox's  data  reference  functions). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Identifying  Data  References"  (V-2839) 

See  Also 

DataHCompareDataRef  (1-178)  asks  your  component  to  compare  a  data  reference 
against  the  current  data  reference  and  indicate  whether  the  references  are 
equivalent  (that  is,  refer  to  the  same  container).  DataHResolveDataRef  (1-218)  permits 
your  component  to  locate  a  data  reference's  container.  For  the  get  function 
corresponding  to  DataHSetDataRef,  see  DataHGetDataRef  (1-189). 


DataHSetDataRefExtension 


Sets  your  component's  current  data  reference  extension  data. 

ComponentResul t  DataHSetDataRefExtension  ( 

DataHandler  dh. 

Handle  extension, 

OSType  idType  ); 


dh 

A  data  handler  component. 
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extensi on 

A  handle  to  the  extension  data, 
i dType 

A  four-byte  signature  identifying  the  type  of  extension  data. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

See  Also 

For  the  corresponding  get  function,  see  DataHGetDataRef  Extensi  on  (1-191). 


DataHSetDataRef  W  ith  Anchor 


Sets  the  data  reference  and  anchor  data  reference  for  a  data  handler. 


ComponentResul t 
DataHandl er 
Handl e 
OSType 
Handl e 


DataHSetDataRefWithAnchor 
dh , 

anchorDataRef , 
dataRefType , 
dataRef  ) ; 


( 


dh 

A  data  handler  component. 
anchorDataRef 

A  handle  to  the  anchor  data  reference. 
dataRefType 

The  type  of  the  data  reference.  Different  types  of  containers  may  require 
different  types  of  data  references.  For  example,  a  reference  to  a  memory-based 
movie  may  be  a  handle,  while  a  reference  to  a  file-based  movie  may  be  an  alias. 
Apple's  memory-based  data  handler  for  the  Macintosh  uses  handles  (and  has  a 
subtype  value  of  '  hndl ' ),  while  the  HFS  data  handler  uses  Alias  Manager 
aliases  (its  subtype  value  is  '  al  is ').  See  "Data  References"  (IV-2661). 
dataRef 

A  data  reference  handle.  Your  component  should  make  a  copy  of  its  current 
data  reference  in  a  handle  and  return  that  handle  in  this  field.  The  client 
program  is  responsible  for  disposing  of  that  handle. 
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function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

See  Also 

For  the  corresponding  get  function,  see  DataHGetDataRefWi  thAnchor  (1-192). 


DataHSetFileSize 


Sets  the  size,  in  bytes,  of  the  current  data  reference. 

ComponentResul t  DataHSetFileSize  ( 

DataHandler  dh, 

long  fileSize  ); 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component, 
f i 1 eSi ze 

The  new  size  of  the  container  corresponding  to  the  current  data  reference,  in 
bytes. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  operationally  equivalent  to  the  Mac  OS  File  Manager's  Set  EOF 
function.  If  the  client  program  specifies  a  new  size  that  is  greater  than  the  current 
size,  your  component  should  extend  the  container  to  accommodate  that  new  size.  If 
the  client  program  specifies  a  container  size  of  0,  your  component  should  free  all  of 
the  space  occupied  by  the  container. 

Special  Considerations 

Note  that  some  data  handlers  may  not  support  write  operations.  For  example,  some 
shared  devices,  such  as  a  CD-ROM  "jukebox,"  may  be  read-only  devices.  As  a 
result,  it  is  very  important  that  your  data  handler  correctly  report  its  write 
capabilities  to  client  programs. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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DataHSetFileSize64 


Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Writing  Movie  Data"  (V-2840) 

See  Also 

Data  handlers  provide  two  distinct  write  facilities.  DataHPutData  (1-216)  is  a  simple 
synchronous  interface  that  allows  applications  to  append  data  to  the  end  of  a 
container.  DataHWrite  (1-232)  is  a  more  capable,  asynchronous  write  function  that  is 
suitable  for  movie  capture  operations.  As  is  the  case  with  DataHScheduleData  (1-220), 
your  component  calls  the  application's  data-handler  completion  function  when  you 
are  done  with  the  write  request.  There  are  several  other  helper  functions  that  allow 
applications  to  prepare  your  data  handler  for  a  movie  capture  operation. 
DataHCreateFi  1  e  (1-180)  asks  your  component  to  create  a  new  container.  The 
DataHGetFileSize  (1-194)  function  gets  a  container's  size,  in  bytes.  The 
DataFIGetFreeSpace  (1-198)  function  allows  applications  to  determine  when  to  make 
a  container  larger.  DataHPreextend  (1-214)  asks  your  component  to  make  a  container 
larger.  Applications  may  call  your  component's  DataHGetPreferredBl  ockSI  ze 
(1-204)  function  in  order  to  determine  how  best  to  interact  with  your  data  handler. 
Before  writing  data  to  a  data  reference,  applications  must  call  your  component's 
DataHOpenForWri  te  (1-210)  function  to  open  a  write  path  to  the  container. 

DataHCl  oseForWri  te  (1-177)  closes  that  write  path.  For  the  get  function 
corresponding  to  DataHSetFi  1  eSi  ze,  see  DataHGetFi  1  eSi  ze  (1-194). 


DataHSetFileSize64 


Provides  a  64-bit  version  of  DataHSetFi  1  eSi  ze  (1-227). 

ComponentResul t  DataHSetFi 1 eSi ze64  ( 

DataHandler  dh, 

const  wide  *fileSize  ); 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component, 
f i 1 eSi ze 

A  pointer  to  the  new  size  of  the  container  corresponding  to  the  current  data 
reference,  in  bytes. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  only  difference  between  this  function  and  DataHSetFi  1  eSi  ze  (1-227)  is  that  the 
f  i  1  eSi  ze  parameter  is  a  64-bit  integer  instead  of  a  32-bit  integer. 
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Special  Considerations 

New  applications  should  use  this  function  instead  of  the  32-bit  version. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui ckTi  meComponents  .  h 

See  Also 

For  the  corresponding  get  function,  see  DataHGetFi  1  eSi  ze64  (1-195). 


DataHSetMacOSFileType 


Sets  the  Mac  OS  file  type  for  a  data  handler's  current  data  reference. 

ComponentResul t  DataHSetMacOSFileType  ( 

DataHandler  dh, 

OSType  fileType  ); 


dh 

A  data  handler  component, 
f i 1 eType 

A  file  type;  see  "File  Types  and  Creators"  (IV-2668). 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

See  Also 

For  the  corresponding  get  function,  see  DataHGetMacOSFi  1  eType  (1-200). 


DataHSetTimeBase 


Sets  the  time  base  for  a  data  handler  component. 

ComponentResul t  DataHSetTimeBase  ( 

DataHandler  dh, 

TimeBase  tb  ); 
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dh 

A  data  handler  component, 
tb 

Apointer  to  a  TimeBaseRecord  (IV-2481)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


DataHSetT  imeHints 


Undocumented 


ComponentResul t 
DataHandl er 
1  ong 
1  ong 

T i meScal e 
T i meVal ue 
T i meVal ue 


DataHSetTimeHints  ( 
dh , 

fl ags , 

bandwi dthPri ori ty  , 
seal e , 
mi nT i me , 
maxT ime  ) ; 


dh 

A  data  handler  component, 
fl  ags 

Undocumented 
bandwi dthPri ori ty 
Undocumented 
seal  e 

Undocumented 
mi nT i me 

Undocumented 
maxT i me 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 
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Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


DataHTask 

Cedes  processor  time  to  your  data  handler. 

ComponentResul t  DataHTask  ( 

DataHandler  dh  ); 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  essentially  analogous  to  the  Movie  Toolbox's  Movi  esTask  (11-973) 
function.  Client  programs  call  this  function  in  order  to  give  your  data  handler 
component  time  to  do  its  work.  Because  client  programs  will  call  this  function 
frequently,  and  especially  so  during  movie  playback  or  capture,  your  data  handler 
should  return  control  quickly  to  the  client  program. 

Special  Considerations 

Applications  should  call  this  function  often  so  that  your  handler  has  enough  time  to 
do  its  work. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Managing  Data  Handler  Components"  (V-2841) 


DataHUpdateMovie 


Updates  the  movie  for  a  data  handler's  current  data  reference. 


ComponentResul t 
DataHandl er 
Movi  e 
short 


DataHUpdateMovi e 
dh , 

theMovi e , 
id  ) ; 


( 


dh 

A  data  handler  component. 
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DataHWrite 


theMovi e 

A  movie  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e 
(11-1084). 
i  d 

Specifies  the  resource  containing  the  movie  data. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


DataHWrite 


Writes  data  to  its  current  data  reference. 


ComponentResul t  DataHW 
DataHandl er 
Ptr 
1  ong 
1  ong 

DataHCompl eti onUPP 
1  ong 


ri  te  ( 
dh , 
data , 
offset , 
size, 

compl eti on , 
refCon  ) ; 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component. 

data 

Specifies  a  pointer  to  the  data  to  be  written.  Client  programs  should  lock  the 
memory  area  holding  this  data,  allowing  your  component's  DataHWrite 
function  to  move  memory, 
offset 

The  offset  (in  bytes)  to  the  location  in  the  current  data  reference  at  which  to 
write  the  data. 

si  ze 

The  number  of  bytes  to  write, 
compl eti on 

A  pointer  to  a  data-handler  completion  function,  described  in 

DataHCompl  eti  onProc  (III— 2078).  The  client  program  must  provide  a  completion 
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routine  for  all  asynchronous  write  requests.  For  synchronous  requests,  client 
programs  should  set  this  parameter  to  NIL.  When  your  data  handler  finishes 
with  the  client  program's  write  request,  your  component  must  call  this  routine 
even  if  the  request  fails.  Your  component  should  pass  the  reference  constant 
that  the  client  program  provided  with  the  ref  Con  parameter. 

refCon 

A  reference  constant  that  your  data  handler  component  should  provide  to  the 
data-handler  completion  function  specified  with  the  compl  eti  on  parameter.  For 
synchronous  operations,  client  programs  should  set  this  parameter  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  provides  both  a  synchronous  and  an  asynchronous  write  interface. 
Synchronous  write  operations  work  like  the  DataHPutData  (1-216)  function;  the  data 
handler  component  returns  control  to  the  client  program  only  after  it  has  serviced 
the  write  request.  Asynchronous  write  operations  allow  client  programs  to  queue 
write  requests.  Your  data  handler  queues  the  request  and  immediately  returns 
control  to  the  calling  program.  After  your  component  actually  writes  the  data,  it 
calls  the  client  program's  data-handler  completion  function. 

Special  Considerations 

Note  that  some  data  handlers  may  not  support  write  operations.  For  example,  some 
shared  devices,  such  as  a  CD-ROM  "jukebox,"  may  be  read-only  devices.  As  a 
result,  it  is  very  important  that  your  data  handler  correctly  report  its  write 
capabilities  to  client  programs. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Writing  Movie  Data"  (V-2840) 

See  Also 

Data  handlers  provide  two  distinct  write  facilities.  DataHPutData  (1-216)  is  a  simple 
synchronous  interface  that  allows  applications  to  append  data  to  the  end  of  a 
container.  DataHWri  te  is  a  more  capable,  asynchronous  write  function  that  is 
suitable  for  movie  capture  operations.  As  is  the  case  with  DataHScheduleData  (1-220), 
your  component  calls  the  application's  data-handler  completion  function  when  you 
are  done  with  the  write  request.  There  are  several  other  helper  functions  that  allow 
applications  to  prepare  your  data  handler  for  a  movie  capture  operation. 
DataHCreateFi  1  e  (1-180)  asks  your  component  to  create  a  new  container.  The 
DataHSetFi  1  eSi  ze  (1-227)  and  DataHGetFil  eSi  ze  (1-194)  functions  work  with  a 
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container's  size,  mbytes.  The  DataHGetFreeSpace  (1-198)  function  allows 
applications  to  determine  when  to  make  a  container  larger.  DataHPreextend  (1-214) 
asks  your  component  to  make  a  container  larger.  Applications  may  call  your 
component's  DataHGetPreferredBlockSize  (1-204)  function  to  determine  how  best  to 
interact  with  your  data  handler.  Before  writing  data  to  a  data  reference,  applications 
must  call  your  component's  DataHOpenForWrite  (1-2 10)  function  to  open  a  write  path 
to  the  container.  DataHCloseForWrite  (1-177)  closes  that  write  path.  Client  programs 
can  force  your  component  to  write  any  cached  data  by  calling  your  component's 
DataHFl  ushData  (1-184)  function. 


DataHWrite64 


Provides  a  64-bit  version  ofDataHWrite  (1-232). 


ComponentResul t  DataHWrite64  ( 


DataHandl er 
Ptr 

const  wide 
1  ong 

DataHCompl eti onUPP 
1  ong 


dh , 
data , 
*offset , 
size, 

compl eti on , 
refCon  ) ; 


dh 

Identifies  the  calling  program's  connection  to  your  data  handler  component. 

data 

Specifies  a  pointer  to  the  data  to  be  written.  Client  programs  should  lock  the 
memory  area  holding  this  data,  allowing  your  component's  DataHWrite 
function  to  move  memory. 

offset 

A  pointer  to  the  offset  (in  bytes)  of  the  location  in  the  current  data  reference  at 
which  to  write  the  data. 

si  ze 

The  number  of  bytes  to  write, 
compl eti on 

A  pointer  to  a  data-handler  completion  function,  described  in 
DataHCompl  eti  onProc  (III— 2078).  The  client  program  must  provide  a  completion 
routine  for  all  asynchronous  write  requests.  For  synchronous  requests,  client 
programs  should  set  this  parameter  to  NIL.  When  your  data  handler  finishes 
with  the  client  program's  write  request,  your  component  must  call  this  routine 


1-234 


Inside  QuickTime:  Functions  A-H 


Decompresslmage 


even  if  the  request  fails.  Your  component  should  pass  the  reference  constant 
that  the  client  program  provided  with  the  ref  Con  parameter. 

refCon 

A  reference  constant  that  your  data  handler  component  should  provide  to  the 
data-handler  completion  function  specified  with  the  compl  eti  on  parameter.  For 
synchronous  operations,  client  programs  should  set  this  parameter  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  only  difference  between  this  function  and  DataHWri  te  (1-232)  is  that  the  offset 
parameter  is  a  64-bit  integer  instead  of  a  32-bit  integer. 

Special  Considerations 

New  applications  should  use  this  function  instead  of  the  32-bit  version. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

See  Also 

See  DataHWri  te  (1-232). 


Decompresslmage 


Decompresses  a  single-frame  image  into  a  pixel  map  structure. 


OSErr  Decompresslmage  ( 

Ptr  data, 

ImageDescri pti onHandl e  desc, 
PixMapHandle  dst, 

const  Rect  *srcRect, 

const  Rect  *dstRect, 

short  mode, 

RgnHandle  mask  ); 


data 

Points  to  the  compressed  image  data.  This  pointer  must  contain  a  32-bit  clean 
address. 

desc 

A  handle  to  the  ImageDescri  pti  on  (IV-2285)  structure  that  describes  the 
compressed  image. 
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dst 

A  handle  to  the  pixel  map  where  the  decompressed  image  is  to  be  displayed. 
Set  the  current  graphics  port  to  the  port  that  contains  this  pixel  map. 
srcRect 

A  pointer  to  a  rectangle  defining  the  portion  of  the  image  to  decompress.  This 
rectangle  must  lie  within  the  boundary  rectangle  of  the  compressed  image, 
which  is  defined  by  (00)  and  ( (**desc) .  wi  dth(**desc)  .height).  If  you  want  to 
decompress  the  entire  source  image,  set  this  parameter  to  NI L.  If  the  parameter 
is  NIL,  the  rectangle  is  set  to  the  rectangle  structure  of  the  ImageDescription 
(IV-2285)  structure. 

dstRect 

A  pointer  to  the  rectangle  into  which  the  decompressed  image  is  to  be  loaded. 
The  compressor  scales  the  source  image  to  fit  into  this  destination  rectangle. 

mode 

The  transfer  mode  for  the  operation,  as  listed  in  "Graphics  Transfer  Modes" 
(IV-2670). 

mask 

A  handle  to  a  clipping  region  in  the  destination  coordinate  system.  If  specified, 
the  compressor  applies  this  mask  to  the  destination  image.  If  you  do  not  want 
to  mask  bits  in  the  destination,  set  this  parameter  to  NIL. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Note  that  Decompresslmage  is  invoked  through  the  StdPix  (III— 1912)  function.  The 
following  code  sample  illustrates  the  process  of  compressing  and  decompressing  a 
pixel  map. 


//  Decompresslmage  coding  example 
//  See  “Discovering  QuickTime,”  page  286 
PicHandle  GetQTCompressedPi ct  ( PixMapHandl e  hpmlmage) 
{ 


1  ong 
Handl e 
Ptr 

ImageDescriptionHandle 

OSErr 

Pi cHandl e 

Rect 

CodecType 

CodecComponent 


1 MaxCompressedSi ze  =  0; 
hCompressedData  =  NIL; 
pCompressedData ; 
hlmageDesc  =  NIL; 
nErr ; 

hpicPicture  =  NIL; 
rectlmage  =  (**hpmlmage) .bounds ; 
dwCodecType  =  kJPEGCodecType ; 
codec  =  (CodecComponent)anyCodec; 
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CodecQ  dwSpati al Qual i ty  =  codecNormal Qual i ty ; 

short  nDepth  =  0;  //  let  ICM  choose  depth 


nErr  =  GetMaxCompressI onSi ze( hpmlmage ,  &rectlmage,  nDepth, 

dwSpati al Qual i ty , 
dwCodecType , 

( Comp res sorComponent) codec, 
&1 MaxCompressedSi ze) ; 


if  (nErr  !=  noErr) 
return  NIL; 


hlmageDesc  =  ( ImageDescri pti onHandl e)NewHandl e(4) ; 
hCompressedData  =  NewHandl e( 1 MaxCompressedSi ze) ; 
if  ((hCompressedData  !=  NIL)  &&  (hlmageDesc  !=  NIL))  { 
MoveHHi (hCompressedData ) ; 

HLock( hCompressedData ) ; 

pCompressedData  =  Stri pAddress (*hCompressedData  ) ; 


nErr  =  Compress Image( hpmlmage , 

&rectlmage , 
dwSpati al Qual i ty , 
dwCodecType , 
hlmageDesc, 
pCompressedData ) ; 


if  (nErr  ==  noErr)  { 

Cl  ip Rect(& recti mage) ; 

hpicPicture  =  OpenPi cture(&rectlmage) ; 

nErr  =  Decompress Image( pCompressedData  , 

hlmageDesc, 
hpmlmage , 
&rectlmage , 
&rectlmage , 
srcCopy , 
NIL) ; 

Cl osePi cture( ) ; 

} 


if  (theErr  ||  (GetHandl eSi ze( ( Handl e)hpi cPi cture)  == 
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si zeof ( Pi cture ) ) )  { 

Ki  1 1  Pi cturet  hpi cPi cture) ; 
hpicPicture  =  NIL; 

} 

} 

if  (hlmageDesc  !=  NIL) 

DisposeHandle((Handle)hIniageDesc); 

if  ( hCompressedData  !=  NIL) 

DisposeHandlet  hCompressedData) ; 

return  hpicPicture; 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Pixel  Maps"  (V-2789) 

Related  Java  Methods 

qui ckti me . std . i mage . QT Image . decompress ( ) 


DecompressSequenceBegin 


Obsolete.  See  DecompressSequenceBegi  nS  (1-239). 


OSErr  DecompressSequenceBegin 
ImageSequence 
ImageDescriptionHandle 
CGraf Ptr 
GDHandl e 
const  Rect 
Matri xRecordPtr 
short 
RgnHandl e 
CodecFl ags 
CodecQ 

Decomp ressorComponent 


( 

*seqID , 
desc , 
port , 
gdh , 

*srcRect , 
matri x , 
mode , 
mask , 
fl ags , 
accuracy , 
codec  )  ; 
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C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Sequences"  (V-2792) 


DecompressSequenceBeginS 


Sends  a  sample  image  to  a  decompressor. 


OSErr  DecompressSequenceBeginS 
ImageSequence 
ImageDescri pti onHandl e 
Ptr 
1  ong 

CGraf Ptr 
GDHandl e 
const  Rect 
Matri xRecordPtr 
short 
RgnHandl e 
CodecFl  ags 
CodecQ 

Decomp res sorComponent 


( 

*seqID, 
desc , 
data , 
dataSi ze , 
port , 
gdh , 

*srcRect, 
matrix, 
mode , 
mask, 
fl ags , 
accuracy , 
codec  ) ; 


seqlD 

A  pointer  to  a  field  to  receive  the  unique  identifier  for  the  sequence  you  are 
creating.  You  should  use  this  identifier  for  subsequent  calls  relating  to  this 
decompression  sequence. 

desc 

A  handle  to  the  ImageDescri  pti  on  (IV-2285)  structure  that  describes  the 
compressed  image. 

data 

Points  to  the  compressed  image  data.  This  pointer  must  contain  a  32-bit  clean 
address.  Ideally,  you  should  pass  a  pointer  to  the  first  frame  of  the  compressed 
image  data,  which  lets  the  Image  Compression  Manager  do  a  better  job  of 
preflighting  the  decompression  sequence.  If  the  image  data  is  not  available  at 
the  time  of  this  call,  you  can  pass  N I L  for  this  parameter  and  0  for  dataSi  ze.  If 
you  pass  N I L  here,  then  your  first  call  to  DecompressSequenceFrameWhen  (1-245) 
may  require  more  setup  time. 

dataSi ze 

The  size  of  the  data  buffer,  or  0  if  you  passed  NI L  in  the  data  parameter. 
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port 

Points  to  the  CGraf  Port  (IV-2168)  structure  for  the  destination  image, 
gdh 

A  handle  to  the  GDevi  ce  (IV-2264)  structure  for  the  destination  image.  You  can 
pass  N I L  if  the  GDev i  ce  is  implicit  in  the  port  selection  (for  example,  if  it  is  an 
offscreen  graphics  world). 

srcRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  defines  the  portions  of  the  image  to 
decompress.  Pass  N I L  if  you  want  to  decompress  the  entire  source  image.  You 
can  call  SetDSequenceSrcRect  (III— 1589)  to  change  the  source  rectangle  for  an 
active  decompression  sequence, 
matri x 

Points  toaMatrixRecord  (IV-2304)  structure  that  specifies  how  to  transform  the 
image  during  decompression.  Pass  N I L  to  use  the  identity  matrix.  Your 
application  can  change  the  matrix  for  an  active  sequence  by  calling 
SetDSequenceMatrix  (III — 1587). 

mode 

The  transfer  mode  for  the  operation.  See  "Graphics  Transfer  Modes"  (IV-2670). 
Your  application  can  change  the  transfer  mode  for  an  active  sequence  by  calling 
SetDSequenceT ransferMode  (III — 1591). 

mask 

A  handle  to  a  clipping  region  in  the  destination  coordinate  system.  If  specified, 
the  compressor  applies  this  mask  to  the  destination  image.  If  you  do  not  want 
to  mask  bits  in  the  destination,  set  this  parameter  to  NIL.  Your  application  can 
change  the  clipping  mask  for  an  active  sequence  by  calling  SetDSequenceMask 
(III— 1586). 

fl  ags 

Buffer  allocation  flags  (see  below), 
accuracy 

A  constant  (see  below)  that  defines  the  desired  compression  accuracy, 
codec 

A  decompressor  identifier.  Specify  a  particular  decompressor  by  setting  this 
parameter  to  its  identifier.  Alternatively,  you  may  use  a  special  identifier  (see 
below).  Specifying  a  component  instance  maybe  useful  if  you  have  previously 
set  some  parameter  on  a  specific  instance  of  a  codec  field  and  want  to  make  sure 
that  the  specified  instance  is  used  for  that  operation. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  codecWoul  dOf  f  screenErr  if 
codecFl  agDontUselmageBuffer  is  set  and  the  codec  requires  an 
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offscreen  buffer  to  decompress  to  the  destination  port.  Returns  n  o  E  r  r 
if  there  is  no  error. 

flags  Constants 

codec  FI  agllseScreenBuf  fer 
Obsolete;  do  not  use. 
codecFlagllselmageBuffer 

Controls  whether  the  decompressor  allocates  an  offscreen  buffer  for 
decompressing  the  image.  Some  decompression  sequences  can  normally  go 
directly  to  the  screen,  so  passing  1  for  this  flag  will  force  an  offscreen  buffer  to 
be  created.  In  other  circumstances  codecs  may  require  an  offscreen  buffer,  and 
one  will  be  created  regardless  of  the  setting  of  this  flag.  You  can  pass 
codecFl  agDontllseNewImageBuf  fer  to  prevent  an  offscreen  buffer  from  being 
created. 

codecFlagDontUselmageBuffer 

Prevents  the  Image  Compression  Manager  from  creating  an  offscreen  buffer  for 
the  decompression  sequence.  Some  codecs  require  an  offscreen  buffer  to 
decompress  to  the  destination  port  successfully;  if  this  is  the  case  and  you  set 
this  flag,  the  function  returns  codecWoul  dOf  f  screenErr. 

accuracy  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 
codecNormal Quality 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 

codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field, 
codec Los  si essQual i ty 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

codec  Constants 

anyCodec 

The  first  compressor  or  decompressor  of  the  specified  type. 


Inside  QuickTime:  Functions  A-H 


1-241 


DecompressSequenceFrame 


bestSpeedCodec 

The  fastest  compressor  or  decompressor  of  the  specified  type. 
bestFi del i tyCodec 

The  most  accurate  compressor  or  decompressor  of  the  specified  type. 

Discussion 

This  function  lets  you  pass  a  compressed  sample  so  a  codec  can  perform 
preflighting  before  the  first  DecompressSequenceFrameWhen  (1-245)  call.  To 
decompress  a  series  of  images,  call  it  once  to  preflight  the  decompressor,  make  calls 
to  DecompressSequenceFrameWhen  to  decompress  each  image  in  the  sequence,  then 
call  CDSequenceEnd  (1-77)  when  you  are  done. 

Version  Notes 

Introduced  in  QuickTime  1.6.1. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Sequences"  (V-2792) 

Related  Java  Methods 

quicktime.std.image.DSequence.DSequencet) 


See  Also 

Use  SetDSequenceDataProc  (III— 1584)  to  assign  a  data-loading  function  to  the 
sequence.  Use  SetDSequenceMatte  (III— 1588)  to  assign  a  blend  matte  to  the  sequence. 


DecompressSequenceFrame 


Obsolete.  See  DecompressSequenceFrameS  (1-243). 


OSErr  DecompressSequenceFrame  ( 
ImageSequence 
Ptr 

CodecFl ags 
CodecFl ags 

ICMCompl etionProcRecordPtr 


seqlD , 
data , 
i  n FI  ags  , 

*outFl ags , 

asyncCompl etl onProc  ); 


Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Sequences"  (V-2792) 
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Queues  a  frame  for  decompression  and  specifies  the  size  of  the  compressed  data; 
new  applications  should  use  DecompressSequenceFrameWhen. 

OSErr  DecompressSequenceFrameS  ( 

ImageSequence 
Ptr 
1  ong 

CodecFl  ags 
CodecFl  ags 

ICMCompl eti onProcRecordPtr 
seqlD 

Contains  the  unique  sequence  identifier  that  was  returned  by  the 
DecompressSequenceBegi  n  (1-238)  function. 

data 

Points  to  the  compressed  image  data.  This  pointer  must  contain  a  32-bit  clean 
address. 
dataSi ze 

The  size  of  the  data  buffer, 
i  n  FI  ags 

Contains  flags  (see  below)  that  provide  further  control  information. 
outFl  ags 

Contains  status  flags  (see  below).  The  decompressor  updates  these  flags  at  the 
end  of  the  decompression  operation. 
asyncCompl eti on P roc 

Points  to  an  ICMCompl  eti  onProc  Record  (IV-2279)  structure.  The  compressor  calls 
your  completion  function  when  an  asynchronous  decompression  operation  is 
complete.  You  can  cause  the  decompression  to  be  performed  asynchronously 
by  specifying  a  completion  function.  If  you  specify  asynchronous  operation, 
you  must  not  read  the  decompressed  image  until  the  decompressor  indicates 
that  the  operation  is  complete  by  calling  your  completion  function.  Set 
asyncCompl  eti  onProc  to  NI L  to  specify  synchronous  decompression.  If  you  set 
asyncCompl  eti  onProc  to  -l,  the  operation  is  performed  asynchronously  but  the 
decompressor  does  not  call  your  completion  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


seqlD, 
data , 
dataSi ze , 
i  n FI  ags  , 

*outFl ags , 

asyncCompl eti onProc  ); 
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inFlags  Constants 

codecFlagNoScreenllpdate 

Controls  whether  the  decompressor  updates  the  screen  image.  If  you  set  this 
flag  to  1,  the  decompressor  does  not  write  the  current  frame  to  the  screen,  but 
does  write  the  frame  to  its  offscreen  image  buffer  (if  one  was  allocated).  If  you 
set  this  flag  to  0,  the  decompressor  writes  the  frame  to  the  screen. 

codec  FI agDon tOff screen 

Controls  whether  the  decompressor  uses  the  offscreen  buffer  during  sequence 
decompression.  This  flag  is  only  used  with  sequences  that  have  been 
temporally  compressed.  If  this  flag  is  set  to  1,  the  decompressor  does  not  use 
the  offscreen  buffer  during  decompression.  Instead,  the  decompressor  returns 
an  error.  This  allows  your  application  to  refill  the  offscreen  buffer.  If  this  flag  is 
set  to  0,  the  decompressor  uses  the  offscreen  buffer  if  appropriate. 
codecFlagOnlyScreenllpdate 

Controls  whether  the  decompressor  decompresses  the  current  frame.  If  you  set 
this  flag  to  1,  the  decompressor  writes  the  contents  of  its  offscreen  image  buffer 
to  the  screen,  but  does  not  decompress  the  current  frame.  If  you  set  this  flag  to 
0,  the  decompressor  decompresses  the  current  frame  and  writes  it  to  the  screen. 
You  can  set  this  flag  to  1  only  if  you  have  allocated  an  offscreen  image  buffer 
for  use  by  the  decompressor. 

outFlags  Constants 

codec  FI  a  gllsed  New  I  mage  Buffer 

Indicates  to  your  application  that  the  decompressor  used  the  offscreen  image 
buffer  for  the  first  time  when  it  processed  this  frame.  If  this  flag  is  set  to  1,  the 
decompressor  used  the  image  buffer  for  this  frame  and  this  is  the  first  time  the 
decompressor  used  the  image  buffer  in  this  sequence. 

codec  FI  a  gllsed  I  mage  Buffer 

Indicates  whether  the  decompressor  used  the  offscreen  image  buffer.  If  the 
decompressor  used  the  image  buffer  during  the  decompress  operation,  it  sets 
this  flag  to  1.  Otherwise,  it  sets  this  flag  to  0. 

codec  FI  a gDont Use New I mage Buffer 

This  input  flag  forces  an  error  to  be  returned  when  a  new  image  buffer  would 
have  to  be  allocated  instead  of  allocating  the  new  buffer. 
codecFlaglnterlacellpdate 

This  input  flag  updates  the  screen  interlacing  even  and  odd  scan  lines  to  reduce 
tearing  artifacts  (if  the  decompressor  supports  this  mode). 
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codecFl  agCatchllpDi  ff 

This  input  flag  notifies  the  codec  that  the  currently  displayed  frame  is  being 
displayed  late  in  an  attempt  to  "catch  up"  to  the  current  frame,  which  only 
happens  with  compression  formats  that  support  frame  differencing. 

Discussion 

This  function  accepts  the  same  parameters  as  the  DecompressSequenceFrame  (1-242) 
function,  with  the  addition  of  the  dataSi  ze  parameter. 

Special  Considerations 

New  applications  should  use  DecompressSequenceFrameWhen. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Sequences"  (V-2792) 

Related  Java  Methods 

qui ckti me . std . image . DSequence . decomp res s Frames ( ) 


DecompressSequenceFrameWhen 


Queues  a  frame  for  decompression  and  specifies  the  time  at  which  decompression 
will  begin. 

OSErr  DecompressSequenceFrameWhen 
ImageSequence 
Ptr 
1  ong 

CodecFl ags 
CodecFl ags 

ICMCompl eti onProcRecordPtr 
const  ICMFrameTimeRecord 

seqlD 

Contains  the  unique  sequence  identifier  that  was  returned  by  the 
DecompressSequenceBegi  n  (1-238)  function. 

data 

Points  to  the  compressed  image  data.  This  pointer  must  contain  a  32-bit  clean 
address. 
dataSi ze 

The  size  of  the  data  buffer. 


( 

seqlD, 
data , 
dataSi ze , 
i  n FI  ags  , 

*outFl  ags , 

asyncCompl eti on P roc , 
*frameTime  ); 
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i  n FI  ags 

Contains  flags  (see  below)  that  provide  further  control  information. 
outFl  ags 

Contains  status  flags  (see  below).  The  decompressor  updates  these  flags  at  the 
end  of  the  decompression  operation. 

asyncCompl etionProc 

Points  to  an  ICMCompl  eti  on  P  roc  Record  (IV-2279)  structure.  The  compressor  calls 
your  completion  function  when  an  asynchronous  decompression  operation  is 
complete.  You  can  cause  the  decompression  to  be  performed  asynchronously 
by  specifying  a  completion  function.  If  you  specify  asynchronous  operation, 
you  must  not  read  the  decompressed  image  until  the  decompressor  indicates 
that  the  operation  is  complete  by  calling  your  completion  function.  Set 
asyncCompl  eti  onProc  to  NI L  to  specify  synchronous  decompression.  If  you  set 
asyncCompl  eti  onProc  to  -1,  the  operation  is  performed  asynchronously  but  the 
decompressor  does  not  call  your  completion  function, 
f rameT i me 

Points  to  an  ICMFrameT i meRecord  (IV-2281)  structure,  which  contains  the 
frame's  time  information,  including  the  time  at  which  the  frame  should  be 
displayed,  its  duration,  and  the  movie's  playback  rate.  This  parameter  can  be 
N I L,  in  which  case  the  decompression  operation  will  happen  immediately. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inFlags  Constants 

codecFlagNoScreenllpdate 

Controls  whether  the  decompressor  updates  the  screen  image.  If  you  set  this 
flag  to  1,  the  decompressor  does  not  write  the  current  frame  to  the  screen,  but 
does  write  the  frame  to  its  offscreen  image  buffer  (if  one  was  allocated).  If  you 
set  this  flag  to  0,  the  decompressor  writes  the  frame  to  the  screen. 

codec  FI agDon tOff screen 

Controls  whether  the  decompressor  uses  the  offscreen  buffer  during  sequence 
decompression.  This  flag  is  only  used  with  sequences  that  have  been 
temporally  compressed.  If  this  flag  is  set  to  1,  the  decompressor  does  not  use 
the  offscreen  buffer  during  decompression.  Instead,  the  decompressor  returns 
an  error.  This  allows  your  application  to  refill  the  offscreen  buffer.  If  this  flag  is 
set  to  0,  the  decompressor  uses  the  offscreen  buffer  if  appropriate. 
codecFlagOnlyScreenUpdate 

Controls  whether  the  decompressor  decompresses  the  current  frame.  If  you  set 
this  flag  to  1,  the  decompressor  writes  the  contents  of  its  offscreen  image  buffer 
to  the  screen,  but  does  not  decompress  the  current  frame.  If  you  set  this  flag  to 
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0,  the  decompressor  decompresses  the  current  frame  and  writes  it  to  the  screen. 
You  can  set  this  flag  to  1  only  if  you  have  allocated  an  offscreen  image  buffer 
for  use  by  the  decompressor. 

outFlags  Constants 

codecFlagllsedNewImageBuffer 

Indicates  to  your  application  that  the  decompressor  used  the  offscreen  image 
buffer  for  the  first  time  when  it  processed  this  frame.  If  this  flag  is  set  to  1,  the 
decompressor  used  the  image  buffer  for  this  frame  and  this  is  the  first  time  the 
decompressor  used  the  image  buffer  in  this  sequence. 

codecFlagllsedlmageBuffer 

Indicates  whether  the  decompressor  used  the  offscreen  image  buffer.  If  the 
decompressor  used  the  image  buffer  during  the  decompress  operation,  it  sets 
this  flag  to  1.  Otherwise,  it  sets  this  flag  to  0. 
codecFlagDontUseNewImageBuffer 

This  input  flag  forces  an  error  to  be  returned  when  a  new  image  buffer  would 
have  to  be  allocated  instead  of  allocating  the  new  buffer, 
codec  FI  aglnterl  a  cell  pd  ate 

This  input  flag  updates  the  screen  interlacing  even  and  odd  scan  lines  to  reduce 
tearing  artifacts  (if  the  decompressor  supports  this  mode). 

codecFl  agCatchllpDi  ff 

This  input  flag  notifies  the  codec  that  the  currently  displayed  frame  is  being 
displayed  late  in  an  attempt  to  "catch  up"  to  the  current  frame,  which  only 
happens  with  compression  formats  that  support  frame  differencing. 

Discussion 

The  following  code  snippet  shows  this  function  being  used  to  execute  one  frame  of 
a  visual  effect. 

//  DecompressSequenceFrameWhen  coding  example 
//  See  “Discovering  QuickTime,”  page  310 
//  Decompress  a  single  step  of  the  effect  sequence. 

OSErr  RunEffectdimeVal ue  ITime,  int  nNumberOf Steps ) 

{ 

OSErr  nErr  =  noErr; 

ICMFrameTimeRecord  ftr; 

//  Set  the  timebase  time  to  the  step  of  the  sequence  to  be  rendered 
SetTimeBaseVal ue(timeBase,  ITime,  nNumberOf Steps ) ; 
ftr . val ue . 1 o  =  1  Time ; 

ftr. value. hi  =0; 
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ftr . seal e 

ftr . base 

ftr . durati on 

ftr . rate 

ftr . recordSi ze 

ftr . f rameNumber 

ftr . f 1 ags 

ftr.virtualStartTime.lo 
ftr.vi rtualStartTime.hi 
ftr . vi rtual Durati on 


nNumberOfSteps ; 

0; 

nNumberOfSteps ; 

0; 

si zeof ( ftr )  ; 

1; 

i cmFrameT imeHasVi rtual Star tTi meAndDurati on  ; 
=  0; 

=  0; 

=  nNumberOfSteps; 


HLock(hEffectDesc) ; 

DecompressSequenceFrameWhen ( g Effect Sequen cel D , 

StripAddress(*hEffectDesc) , 

GetHandleSizet  hEffectDesc) , 

0, 

0, 

NIL, 

&ftr) ; 

HUn lock (hEffectDesc) ; 

} 

Special  Considerations 

If  the  current  decompressor  component  does  not  support  scheduled  asynchronous 
decompression,  the  Image  Compression  Manager  returns  an  error  code  of 
codecCantWhenErr.In  this  case,  the  application  will  need  to  reissue  the  request  with 
the  f  rameT i  me  parameter  set  to  N I L.  If  the  decompressor  cannot  service  your  request 
at  a  particular  time  (for  example,  if  its  queue  is  full),  the  Image  Compression 
Manager  returns  an  error  code  of  codecCantQueueErr.  The  best  way  to  determine 
whether  a  decompressor  component  supports  this  function  is  to  call  the  function 
and  test  the  result  code.  A  decompressor's  ability  to  honor  the  request  may  change 
based  on  screen  depth,  clipping  settings,  and  so  on. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Sequences"  (V-2792) 

Related  Java  Methods 

quicktime.std.image.DSequence. decomp ressFrameWhen ( ) 
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See  Also 

See  DecompressSequenceFrameS  (1-243). 


DelegateComponentCall 


Provides  an  efficient  mechanism  for  passing  on  requests  to  a  specified  component. 

long  DelegateComponentCall  ( 

Component  Parameters  *origi nal Pa  rams , 

Componentlnstance  ci  ); 

ori gi nal  Params 

The  ComponentParameters  (IV-2216)  structure  provided  to  the  calling 
component  by  the  Component  Manager, 
ci 

A  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

function  result  The  component  result  returned  by  the  specified  component. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 


DeleteMovieFile 


Deletes  a  movie  file. 

OSErr  DeleteMovieFile  ( 

const  FSSpec  *fileSpec  ); 

f i 1 eSpec 

A  pointer  to  the  file  system  specification  for  the  movie  file  to  be  deleted. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Movie  Functions"  (V-2713) 

Related  Java  Methods 

qui ckti me . i o . QTFi 1 e . del ete( ) 


DeleteMovieSegment 

Removes  a  specified  segment  from  a  movie. 

OSErr  DeleteMovieSegment  ( 

Movie  theMovie, 

TimeVal ue  startTi me , 

TimeValue  duration  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

startTime 

A  time  value  specifying  the  starting  point  of  the  segment  to  be  deleted, 
durati on 

A  time  value  that  specifies  the  duration  of  the  segment  to  be  deleted. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

You  identify  the  segment  to  remove  by  specifying  its  starting  time  and  duration. 
The  following  code  snippet  shows  Del  eteMovi  eSegment  being  used  while  adding  a 
modifier  track  to  a  movie. 

//  DeleteMovieSegment  coding  example 


//  See 

“Discovering  QuickTime,”  page  363 

Movi  e 

movi el ; 

T i meVal 

ue 

1 01 dDurati on ; 

Movi  e 

movi e2 ; 

1  ong 

llndex,  1 Ori gTrackCount ,  1 Referencelndex 

T  rack 

track,  trackSprite; 
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//  get  the  first  track  in  original  movie  and  position  at  the  start 
trackSprite  =  GetMovi elndTracklmovi el ,  1); 

SetMovi eSel ecti onlmovi el ,  0 ,  0) ; 

//  remove  all  tracks  except  video  in  modifier  movie 
for  (llndex  =  1;  llndex  <=  GetMovi eTrackCountlmovi e2 ) ;  llndex++)  { 
Track  track  =  GetMovieIndTrack(movie2,  llndex); 

OSType  dwType; 

GetMedi aHandl erDescri pti on(GetT  rackMedi a ( track) , 

&dwType ,  NIL,  NIL); 
if  (dwType  !=  VideoMedi aType)  { 

Di sposeMovi eTrackl track) ; 

1  Index- - ; 

} 

} 

//  add  the  modifier  track  to  original  movie 
lOldDuration  =  GetMovi eDurationlmoviel ) ; 

AddMovi eSel ecti on (movi el ,  movi e2 ) ; 

Di sposeMovi e(movi e2 ) ; 

//  truncate  the  movie  to  the  length  of  the  original  track 
Del eteMovi eSegment(movi el,  lOldDuration, 

GetMovi eDuration(moviel)  -  lOldDuration); 

//  associate  the  modifier  track  with  the  original  sprite  track 
track  =  GetMovi elndTracklmovi el ,  1 Ori gTrackCount  +  1); 

AddT rackReferencel trackSpri te ,  track,  kTrackModi f i er Reference , 

&1 Referencelndex) ; 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Low-Level  Movie  Editing  Functions"  (V-2749) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . del eteSegment( ) 
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DeleteT  rackRef  erence 


Removes  a  track  reference  from  a  track. 

OSErr  DeleteTrackReference  ( 

Track  theTrack, 

OSType  refType, 

1 ong  i ndex  ) ; 

theT  rack 

Identifies  the  track  for  this  operation.  Your  application  obtains  this  track 
identifier  from  such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack 
(1-497). 
refType 

The  type  of  reference, 
i  ndex 

The  index  value  of  the  reference  to  be  deleted.  You  obtain  this  index  value  when 
you  create  the  track  reference. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

This  function  deletes  a  track  reference  from  a  track.  If  there  are  additional  track 
references  with  higher  index  values,  the  toolbox  automatically  renumbers  those 
references,  decrementing  their  index  values  by  1. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Track  References"  (V-2737) 

Related  Java  Methods 

qu ickti me. std. mo vies. Track. delete Reference!) 


DeleteT  rackSegment 


Removes  a  specified  segment  from  a  track. 

OSErr  Del eteTrackSegment  ( 

Track  theTrack, 
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TimeValue  startTime, 

TimeValue  duration  ); 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 
startTime 

A  time  value  specifying  the  starting  point  of  the  segment  to  be  deleted.  This 
time  value  must  be  expressed  in  the  time  scale  of  the  movie  that  contains  the 
source  track, 
durati on 

A  time  value  that  specifies  the  duration  of  the  segment  to  be  deleted.  This  time 
value  must  be  expressed  in  the  time  scale  of  the  movie  that  contains  the  source 
track. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

You  identify  the  segment  to  remove  by  specifying  its  starting  time  and  duration. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Editing  Tracks"  (V-2750) 

Related  Java  Methods 

qui ckti me . std .movi es . Track. del eteSegmenti ) 


Dequeue 


Removes  a  queue  element  from  a  Windows  QHdr  (IV-2345)  structure. 

OSErr  Dequeue  ( 

QElemPtr  qElement, 

QHdrPtr  qHeader  ); 


q El  ement 

A  pointer  to  a  QE1  em  (IV-2344)  structure. 


Inside  QuickTime:  Functions  A-H 


1-253 


DestroyPortAssociation 


qHeader 

A  pointer  to  a  QHdr  (IV-2345)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Present  in  QuickTime  3  and  later  releases. 

Programming  Info 

C  interface  file:  OSUti  1  s .  h 


DestroyPortAssociation 

Removes  the  graphics  port  associated  with  an  onscreen  window. 

void  DestroyPortAssociation  ( 

CGraf Ptr  cgp  ) ; 


cgp 

A  pointer  to  the  CGraf  Port  (IV-2168)  structure  associated  with  a  native 
window. 

Discussion 

This  function  removes  the  graphics  port  associated  with  an  onscreen  native 
window.  This  association  was  established  previously  via  the 

CreatePortAssoci  ati  on  (1-148)  call.  The  DestroyPortAssoci  ati  on  function  unhooks 
the  native  window's  W  n  d  P  r  o  c  and  deallocates  and  window  storage,  as  shown  below. 
You  must  call  this  function  before  you  destroy  the  native  window. 


//  DestroyPortAssociation  coding  example 
//  See  “Discovering  QuickTime,”  page  229 


LRESULT  CALLBACK  WndProc 
( HWND  hwnd , 

UINT  i Msg , 
WPARAM  wParam, 
LPARAM  IParam) 


//  Handle  to  window 
//  Message  type 

//  Message-dependent  parameter 
//  Message-dependent  parameter 


{ 


switch  ( i Ms g )  { 
case  WM_CL0SE: 

DestroyPortAssoci ation(GetHWNDPort( hwnd ) ) ; 
break ; 
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}  //  end  switch  ( i M s g ) 

}  //  end  WndProc 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML .  h 


DisposeActionsUPP 


Disposes  of  an  Acti  onsLIPP  pointer. 

void  DisposeActionsUPP  ( 

ActionsUPP  userUPP  ); 


userUPP 

An  Acti  onsUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Movi  es  .  h 


DisposeAllSprites 

Disposes  of  all  sprites  associated  with  a  sprite  world. 

void  DisposeAllSprites  ( 

SpriteWorld  theSpri  teWorl  d  ); 

theSpri teWorl d 

The  sprite  world  for  this  operation. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 
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Discussion 

This  function  calls  Di  sposeSpri  te  (1-296)  for  each  sprite  associated  with  the  sprite 
world. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi es .  h 

Programming  summary:  "Working  with  Sprite  Worlds"  (V-2900) 


DisposeCallBack 

Disposes  of  a  callback  event. 

void  DisposeCallBack  ( 

QTCal 1  Back  cb  ) ; 


cb 

The  callback  event  for  the  operation.  You  obtain  this  value  from  NewCall  Back 
(11-1053). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Discussion 

You  should  call  this  function  when  you  are  done  with  each  callback  event. 

Special  Considerations 

Don't  call  this  function  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Time  Base  Callback  Functions"  (V-2763) 


DisposeCharDataHandlerUPP 


Disposes  of  a  CharDataHandl  erUPP  pointer. 

void  DisposeCharDataHandlerUPP  ( 

CharDataHandl erUPP  userUPP  ); 


1-256 


Inside  QuickTime:  Functions  A-H 


DisposeCodecNameList 


userUPP 

ACharDataHandlerUPP  pointer. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


DisposeCodecNameList 


Disposes  of  the  compressor  name  list  structure  you  obtained  by  calling 
GetCodecNameLi  st  (1-386). 

OSErr  DisposeCodecNameList  ( 

CodecNameSpecLi stPtr  list  ); 


list 

Points  to  the  compressor  name  list  to  be  disposed  of.  You  obtain  the  compressor 
list  by  calling  GetCodecNameLi  st  (1-386). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Getting  Information  About  Compressor  Components" 
(V-2788) 

DisposeCommentHandlerUPP 

Disposes  of  a  CommentHandl  erUPP  pointer. 

void  DisposeCommentHandlerUPP  ( 

CommentHandl erUPP  userUPP  ); 

userUPP 

A  CommentHandl  erUPP  pointer. 

Version  Notes 

Introduced  in  QuickTime  5. 
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Programming  Info 

C  interface  file:  QuickTimeComponents.h 


DisposeComponentFunctionUPP 

Disposes  of  a  ComponentFuncti  onUPP  pointer. 

void  DisposeComponentFunctionUPP  ( 

ComponentFuncti onUPP  userUPP  ); 


userUPP 

A  ComponentFuncti  onUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Components .  h 


DisposeComponentMPWorkFunctionUPP 

Disposes  of  a  ComponentMPWorkFuncti  onUPP  pointer. 

void  Di sposeComponentMPWorkFuncti  onUPP  ( 

ComponentMPWorkFuncti onUPP  userUPP  ); 


userUPP 

A  ComponentMPWorkFuncti  onUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1-A9A). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Components .  h 
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DisposeComponentRoutineUPP 


DisposeComponentRoutineUPP 

Disposes  of  a  ComponentRouti  nellPP  pointer. 

void  DisposeComponentRoutineUPP  ( 

ComponentRouti neUPP  userUPP  ); 


userUPP 

A  ComponentRouti  neUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Components .  h 


DisposeDataHCompletionUPP 


Disposes  of  a  DataHCompl  eti  onUPP  pointer. 

void  DisposeDataHCompletionUPP  ( 

DataHCompl eti onUPP  userUPP  ); 


userUPP 

A  DataHCompl  eti  onUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


DisposeDoMCActionUPP 


Disposes  of  a  DoMCActi  onUPP  pointer. 

void  DisposeDoMCActionUPP  ( 

DoMCActi onUPP  userUPP  ); 
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DisposeEndDocumentHandlerUPP 


userUPP 

A  DoMCActi  onUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (\-A9A). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Movi  es .  h 


DisposeEndDocumentHandlerUPP 

Disposes  of  an  EndDocumentHandl  erLIPP  pointer. 

void  DisposeEndDocumentHandlerUPP  ( 

EndDocumentHandl erUPP  userUPP  );  QuickTimeComponents.h 

userUPP 

An  EndDocumentHandl  erUPP  pointer. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


DisposeEndElementHandlerUPP 

Disposes  of  an  EndEl  ementHandl  erUPP  pointer. 

void  DisposeEndElementHandlerUPP  ( 

EndEl ementHandl erUPP  userUPP  ); 

userUPP 

An  EndEl  ementHandl  erUPP  pointer. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 
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DisposeFilePlayCompletionUPP 


DisposeFilePlayCompletionUPP 


Deprecated. 

void  DisposeFilePlayCompletionUPP  ( 

Fi 1 ePl ayCompl eti onUPP  userUPP  ); 


Version  Notes 

Introduced  in  QuickTime  4.1.  Macintosh  Note:  Not  supported  by  CarbonLib. 

Programming  Info 

C  interface  file:  Sound .  h 


DisposeGetMissingComponentResourceUPP 


Disposes  of  a  GetMi  ssi  ngComponentResourceUPP  pointer. 

void  Di sposeGetMi ssi ngComponentResourceUPP  ( 

GetMi ssi ngComponentResourceUPP  userUPP  ); 


userUPP 

A  GetMi  ssi  ngComponentResourceUPP  pointer.  See  "Universal  Procedure 
Pointers"  (IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Components .  h 


DisposeGetMovieUPP 


Disposes  ofaGetMovieUPP  pointer. 

void  DisposeGetMovieUPP  ( 

GetMovieUPP  userUPP  ); 


userUPP 

A  GetMovi eUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 
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DisposeGWorld 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es .  h 


DisposeGWorld 

Disposes  of  an  offscreen  graphics  world. 

void  DisposeGWorld  ( 

GWorldPtr  offscreenGWorl d  ); 

offscreenGWorl d 

A  pointer  to  an  offscreen  graphics  world. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

When  you  dispose  of  a  graphics  world  using  this  function,  the  graphics  world's 
pixel  map  is  not  disposed,  because  QuickTime  does  not  know  how  its  pixels  were 
originally  allocated.  It  is  the  caller's  responsibility  to  dispose  of  the  pixel  map. 

Version  Notes 

Part  of  the  Mac  OS. 

Programming  Info 

C  interface  file:  QDOf  fscreen .  h 


DisposelCMAlignmentUPP 

Disposes  of  an  ICMA1  i  gnmentUPP  pointer. 

void  DisposelCMAlignmentUPP  ( 

ICMA1 i gnmentUPP  userUPP  ); 

userUPP 

An  ICMA1  i  gnmentUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94). 
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DisposelCMCompletionUPP 


Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


DisposelCMCompletionUPP 


Disposes  of  an  ICMCompl  eti  onllPP  pointer. 

void  DisposelCMCompletionUPP  ( 

ICMCompl etionUPP  userUPP  ); 


userUPP 

An  ICMCompl  eti  onUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


DisposelCMConvertDataFormatUPP 


Disposes  of  an  ICMConvertData  FormatUPP  pointer. 

void  DisposelCMConvertDataFormatUPP  ( 

ICMConvertDataFormatUPP  userUPP  ); 


userUPP 

An  ICMConvertDataFormatUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  ImageCompressi  on .  h 
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DisposelCMCursorShieldedUPP 


DisposelCMCursorShieldedUPP 


Disposes  of  an  ICMCursorShi  el  dedUPP  pointer. 

void  DisposelCMCursorShieldedUPP  ( 

ICMCursorShi el dedUPP  userUPP  ); 


userUPP 

An  ICMCursorShi  el  dedUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


DisposelCMDataUPP 

Disposes  of  an  ICMDataUPP  pointer. 

void  DisposelCMDataUPP  ( 

ICMDataUPP  userUPP  ); 


userUPP 

An  ICMDataUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


DisposelCMFlushUPP 

Disposes  of  an  ICMFlushUPP  pointer, 
void  DisposelCMFlushUPP  ( 
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ICMFl ushUPP  userUPP  ); 


userUPP 

An  ICMFl  ushUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


DisposelCMMemoryDisposedUPP 


Disposes  of  an  ICMMemoryDi  sposedUPP  pointer. 

void  DisposelCMMemoryDisposedUPP  ( 

ICMMemoryDi sposedUPP  userUPP  ); 


userUPP 

An  ICMMemoryDi  sposedUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


DisposelCMProgressUPP 


Disposes  of  an  ICMProgressUPP  pointer. 

void  DisposelCMProgressUPP  ( 

ICMProgressUPP  userUPP  ); 


userUPP 

An  ICMProgressUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 
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DisposelmageCodecDrawBandCompleteUPP 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


DisposelmageCodecDrawBandCompleteUPP 


Disposes  of  an  ImageCodecDrawBandCompl  etellPP  pointer. 

void  Di  sposelmageCodecDrawBandCompl  etellPP  ( 

ImageCodecDrawBandCompl  etellPP  userUPP  ); 

userUPP 

An  ImageCodecDrawBandCompl  eteUPP  pointer. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  ImageCodec.  h 


DisposelmageCodecMPDrawBandUPP 

Disposes  of  an  ImageCodecMPDrawBandUPP  pointer. 

void  DisposelmageCodecMPDrawBandUPP  ( 

ImageCodecMPDrawBandUPP  userUPP  ); 

userUPP 

An  ImageCodecMPDrawBandUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  ImageCodec.  h 
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DisposelmageCodecTimeTriggerUPP 


DisposelmageCodecT  imeT  riggerUPP 

Disposes  of  an  ImageCodecTi meT riggerUPP  pointer. 

void  Di sposelmageCodecTimeTri ggerUPP  ( 

ImageCodecTimeTriggerUPP  userUPP  ); 


userUPP 

An  ImageCodecTimeTri  ggerUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  ImageCodec.h 


DisposeMatte 


Disposes  of  a  matte  obtained  from  the  GetTrackMatte  (1-534)  function. 

void  DisposeMatte  ( 

PixMapHandle  theMatte  ); 

theMatte 

Handle  to  the  matte  to  be  disposed.  Your  application  obtains  this  handle  from 
GetTrackMatte  (1-534). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 
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DisposeMCActionFilterUPP 


DisposeMCActionFilterUPP 


Disposes  of  a  MCActi  onFi  1  terUPP  pointer. 

void  DisposeMCActionFilterUPP  ( 

MCActi onFi 1 terUPP  userUPP  ); 


userUPP 

A  MCActi  onFi  1  terUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es .  h 


DisposeMCActionFilterWithRefConUPP 

Disposes  of  a  MCActi  onFi  1  terWi  thRefConUPP  pointer. 

void  Di sposeMCActi onFi 1 terWi thRefConUPP  ( 

MCActi onFi 1 terWi thRefConUPP  userUPP  ); 

userUPP 

A  MCActi  onFi  1  terWi  thRefConUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es .  h 


DisposeMovie 

Frees  any  memory  being  used  by  a  movie,  including  the  memory  used  by  the 
movie's  tracks  and  media  structures. 


1-268 


Inside  QuickTime:  Functions  A-H 


DisposeMovie 


void  DisposeMovie  ( 

Movie  theMovie  ); 

theMovi e 

Identifies  the  movie  to  be  freed.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  or 
NewMovi  eFromHandl  e  (11-1084). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Discussion 

Your  application  should  call  this  function  when  it  is  done  working  with  a  movie,  as 
shown  in  the  following  example: 

//  DisposeMovie  coding  example 

//  See  “Discovering  QuickTime,”  page  85 

void  CreateMyCool Movi e  (void) 

{ 

StandardFi 1 eReply  sfr; 

Movie  movie  =  NIL; 

FSSpec  fss; 

short  nFileRefNum  =  0; 

short  nResID  =  movielnDataForkResID; 

StandardPutFi 1 e( "\pEnter  movie  file  name:",  "\punti tl ed .mov" ,  &sfr); 
if  ( ! sf r . sfGood ) 
return ; 

CreateMovi eFile(&sfr.sfFile, 

F0UR_CHAR_C0DE( 'TV0D' ) , 
smCurrentScri pt , 
createMovi eFi 1 eDel eteCurFi 1 e  | 
createMovi eFi 1 eDontC reate Res Fi  1  e , 

&nFi 1 eRefNum, 

&movi e) ; 

CreateMyVideoTrack(movie) ;  //  See  “Creating  a  Track,”  below 

AddMovi eResource(movi e ,  nFileRefNum,  &nResID,  NIL); 
if  ( n F i 1 eRefNum  !=  0) 

Cl oseMovi eFi 1 e( n  F i 1 eRef Num) ; 

Di sposeMovie( movie) ; 
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} 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Movie  Functions"  (V-2713) 


DisposeMovieController 

Disposes  of  a  movie  controller. 

void  DisposeMovieController  ( 
Componentlnstance  me  ); 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from  the 
Component  Manager's  OpenComponent  (11-1130)  or  OpenDefaul  tComponent 
(11-1131)  function,  or  from  the  NewMovi  eControl  1  er  (11-1071)  function. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94). 

Discussion 

This  function  is  implemented  by  the  Movie  Toolbox,  not  by  movie  controller 
components.  If  you  are  creating  your  own  movie  controller  component,  you  do  not 
have  to  support  this  function.  The  following  code  snippet  illustrates  its  use: 

//  DisposeMovieController  coding  example 
//  See  “Discovering  QuickTime,”  page  221 
//  Resource  identifiers 
#define  IDM_0PEN  101 

char  szMovi eFi 1 e[MAX_PATH] ; 

Movie  movie; 

Movi eControl! er  me; 


//  Name  of  movie  file 
//  Movie  object 
//  Movie  controller 


int  WINAPI  WinMain 
{ 


(HINSTANCE  hlnstance,  HINSTANCE  hPrevInstance , 
LPSTR  IpCmdLine,  int  nCmdShow) 
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Ini ti al i zeQTML(O) ; 

EnterMovi es ( ) ; 

//  Main  message  loop 

Exi tMovi es ( ) ; 

Termi nateQTMLC ) ; 

}  //  end  WinMain 

// 

LRESULT  CALLBACK  WndProc  ( HWND  hwnd, 

{ 

MSG  msg; 

EventRecord  er; 


//  Initialize  QuickTime 
//  Initialize  Toolbox 


//  Terminate  Toolbox 
//  Terminate  QuickTime 


UINT  i Msg ,  WPARAM  wParam,  LPARAM  IParam) 


...  //  Fill  in  contents  of  MSG  structure 

Wi  nEventToMacEvent(&msg ,  &er);  //  Convert  message  to  a 

QT  event 

MCIsPl ayerEvent(mc ,  (const  EventRecord  *)&er);  //  Pass  event  to  movie 

control  1 er 

switch  (iMsg)  { 

case  WM_CREATE : 

CreatePortAssoci ati on( hwnd ,  NIL,  OL);  //  Register  window  with  QT 
break; 

case  WM_COMMAND: 

switch  ( LOWORD(wParam) )  { 
case  I DM_0PEN : 

MyCl oseMovi e( ) ;  //  Close  previous  movie,  if  any 

if  (MyGetFi  1  e( szMovi eFi 1 e ) )  //  Get  file  name  from  user 

MyOpenMovi e( hwnd  ,  szMovieFi 1 e) ;  //  Open  the  movie 
break; 

def  aul  t : 

return  DefWi ndowProc( hwnd ,  iMsg,  wParam,  IParam); 

}  //  end  switch  ( LOWORD(wParam) ) 

break; 

case  WM_CL0SE: 

DestroyPortAssoci ati on(GetNati veWi ndowPort ( hwnd ));  //  Unregister 

wi ndow 
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break ; 
defaul t : 

return  DefWi ndowProc( hwnd ,  iMsg,  wParam,  IParam); 

}  //  end  switch  (iMsg) 

return  0; 

}  //  end  WndProc 

// 

BOOL  MyGetFile  (char  *1 pszMovi eFi 1 e ) 

{ 

OPENFILENAME  ofn ; 

//  Fill  in  contents  of  OPENFILENAME  structure 


if  (GetOpenFileName(&ofn) )  //  Let  user  select  file 

return  TRUE; 

el  se 

return  FALSE; 

}  //  end  MyGetFile 

// 

void  MyOpenMovie  (HWND  hwnd,  char  szFi 1 eName[255] ) 

{ 

short  nFileRefNum  =  0; 

FSSpec  fss; 


SetGWorld( ( CGraf Pt r ) Get Nati veWi ndowPort( hwnd) , 

port 

NativePathNameToFSSpec(szFileName,  &fss,  0); 
make  FSSpec 

OpenMovi eFi 1 e( &fss ,  &nFileRefNum,  fsRdPerm); 
NewMovieFromFilet&movie,  nFi 1 eRefNum ,  NIL, 

NIL,  newMovi eActi ve  ,  NIL); 
CloseMovieFile(nFileRefNum) ; 


NIL);  //  Set  graphi cs 

//  Convert  pathname  and 

//  Open  movie  file 
//  Get  movie  from  file 

//  Close  movie  file 


me  =  NewMovi eControl 1 er(movi e ,  ...); 


//  Make  movie  controller 
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}  //  end  MyOpenMovie 

// 

void  MyCloseMovie  (void) 

{ 

if  (me)  //  Destroy  movie  controller,  if  any 

Di  sposeMovi  eControl 1 er(mc) ; 

if  (movie)  //  Destroy  movie  object,  if  any 

Di sposeMovi e(movi e) ; 

}  //  end  MyCloseMovie 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Associating  Movies  With  Controllers"  (V-2774) 


DisposeMovieDrawingCompleteUPP 

Disposes  of  a  Movi  eDrawi  ngCompl  eteUPP  pointer. 

void  DisposeMovieDrawingCompleteUPP  ( 

Movi eDrawi ngCompl eteUPP  userUPP  ); 


userUPP 

A  Movi  eDrawi  ngCompl  eteUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


DisposeMovieEditState 

Disposes  of  an  edit  state. 
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DisposeMovieExecuteWiredActionsUPP 


OSErr  Di sposeMovi eEdi tState  ( 

Movi eEdi tState  state  ); 

state 

The  edit  state  for  this  operation.  Your  application  obtains  this  edit  state 
identifier  when  you  create  the  edit  state  by  calling  NewMovi  eEdi  tState  (11-1073). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Special  Considerations 

You  must  dispose  of  a  movie's  edit  states  before  you  dispose  of  the  movie  itself. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Undo  for  Movies"  (V-2748) 


DisposeMovieExecuteWiredActionsUPP 

Disposes  of  a  Movi  eExecuteWi  redActi  onsUPP  pointer. 

void  Di sposeMovi eExecuteWi redActi onsUPP  ( 

Movi eExecuteWi redActi onsUPP  userUPP  ); 


userUPP 

A  Movi  eExecuteWi  redActi  onsUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94). 

Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Movi  es .  h 


DisposeMovieExportGetDataUPP 

Disposes  of  a  Movi  eExportGetDataUPP  pointer. 
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DisposeMovieExportGetPropertyUPP 


void  Di sposeMovi eExportGetDataUPP  ( 

Movi  eExportGetDataUPP  userUPP  ); 


userUPP 

A  Movi  eExportGetDataUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


DisposeMovieExportGetPropertyUPP 

Disposes  of  a  Movi  eExportGetPropertyUPP  pointer. 

void  Di sposeMovi eExportGetPropertyUPP  ( 

Movi eExportGetPropertyUPP  userUPP  ); 


userUPP 

A  Movi  eExportGetPropertyUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 


DisposeMoviePrePrerollCompleteUPP 


Disposes  of  a  Movi  ePrePrerol  1  Compl  eteUPP  pointer. 

void  Di sposeMovi ePrePrerol 1 Compl eteUPP  ( 

Movi ePrePrerol 1 Compl eteUPP  userUPP  ); 


Inside  QuickTime:  Functions  A-H 
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DisposeMoviePreviewCallOutUPP 


userUPP 

A  Movi  ePrePrerol  1  Compl  eteUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Movi  es .  h 


DisposeMoviePreviewCallOutUPP 

Disposes  of  a  Movi  ePrevi  ewCal  1  OutUPP  pointer. 

void  DisposeMoviePreviewCallOutUPP  ( 

Movi ePrevi ewCal 1 OutUPP  userUPP  ); 


userUPP 

A  Movi  ePrevi  ewCal  1  OutUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Movi  es .  h 


DisposeMovieProgressUPP 

Disposes  of  a  Movi  eProgressUPP  pointer. 

void  DisposeMovieProgressUPP  ( 

Movi eProgressUPP  userUPP  ); 

userUPP 

A  Movi  eProgressUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 
function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
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Inside  QuickTime:  Functions  A-H 


DisposeMovieRgnCoverUPP 


(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


DisposeMovieRgnCoverUPP 

Disposes  of  a  Movi  eRgnCoverUPP  pointer. 

void  DisposeMovieRgnCoverUPP  ( 

Movi eRgnCoverUPP  userUPP  ); 


userUPP 

A  Movi  eRgnCoverUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Movi  es  .  h 


DisposeMoviesErrorUPP 

Disposes  of  a  Movi esErrorUPP  pointer. 

void  DisposeMoviesErrorUPP  ( 

MoviesErrorUPP  userUPP  ); 


userUPP 

A  Movi  esErrorUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


Inside  QuickTime:  Functions  A-H 
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DisposeMovieTrack 


DisposeMovieT  rack 

Removes  a  track  from  a  movie. 

void  DisposeMovieTrack  ( 

T rack  theT rack  ) ; 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1—494). 

Discussion 

The  following  code  snippet  illustrates  the  use  of  Di  sposeMovi  eT  rack: 

//  DisposeMovieTrack  coding  example 
//  See  “Discovering  QuickTime,”  page  363 
Movie  moviel; 

TimeValue  1 01 dDurati on ; 

Movie  movie2; 

long  llndex,  1 Ori gTrackCount ,  1  Referencelndex ; 

Track  track,  trackSprite; 

//  get  the  first  track  in  original  movie  and  position  at  the  start 
trackSprite  =  GetMovi elndTracktmovi el ,  1); 

SetMovi eSel ecti on (movi el ,  0,  0); 

//  remove  all  tracks  except  video  In  modifier  movie 

for  (llndex  =  1;  llndex  <=  GetMovieTrackCount(movie2) ;  llndex++)  { 

Track  track  =  GetMovi elndTracktmovi e2 ,  llndex); 

OSType  dwType; 

GetMedi aHandlerDescrlptiontGetT  rackMedi a ( track) , 

&dwType ,  NIL,  NIL); 
if  (dwType  !=  Vi deoMedi aType )  { 

Di sposeMovi eTrackt  track) ; 

1  Index- - ; 

} 

} 

//  add  the  modifier  track  to  original  movie 
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Inside  QuickTime:  Functions  A-H 


DisposeMusicMIDIReadHookUPP 


lOldDuration  =  GetMovi eDurati on(moviel ) ; 

AddMovi eSel ecti onlmovi el ,  movi e2 ) ; 

Di sposeMovi e(movi e2) ; 

//  truncate  the  movie  to  the  length  of  the  original  track 
Del eteMovi eSegmentlmovi el,  lOldDuration, 

GetMovi eDuration(moviel)  -  lOldDuration); 

//  associate  the  modifier  track  with  the  original  sprite  track 
track  =  GetMovi elndTracklmovi el ,  1 Ori gTrackCount  +  1); 

AddT rackReferencel trackSpri te ,  track,  kTrackModi f i er Reference , 

&1 Referencelndex) ; 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Creating  Tracks  and  Media  Structures"  (V-2726) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . removeT  rack( ) 


DisposeMusicMIDIReadHookUPP 


Disposes  of  a  Musi  cMIDIReadHookUPP  pointer. 

void  DisposeMusicMIDIReadHookUPP  ( 

MusicMIDIReadHookUPP  userUPP  ); 


userUPP 

A  Musi  cMIDIReadHookUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  QuickTimeMusic.h 


Inside  QuickTime:  Functions  A-H 
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DisposeMusicMIDISendUPP 


DisposeMusicMIDISendUPP 


Disposes  of  a  Musi  cMIDISendUPP  pointer. 

void  DisposeMusicMIDISendUPP  ( 

Musi cMIDISendUPP  userUPP  ); 


userUPP 

A  Musi  cMIDISendUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 


DisposeMusicOfflineDataUPP 


Disposes  of  a  Musi  cOf  f  1  i  neDataUPP  pointer. 

void  DisposeMusicOfflineDataUPP  ( 

Musi cOffl i neDataUPP  userUPP  ); 


userUPP 

A  Musi  cOffl  i  neDataUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 


DisposePrePrerollCompleteUPP 


Disposes  of  a  PrePrerol  1  Compl  eteUPP  pointer. 

void  DisposePrePrerollCompleteUPP  ( 

PrePrerol 1 Compl eteUPP  userUPP  ); 
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DisposePreprocessInstructionHandlerUPP 


userUPP 

A  PrePrerol  1  Compl  eteUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


DisposePreprocessInstructionHandlerUPP 


Disposes  of  a  Preprocess  Instruct i  on HandlerUPP  pointer. 

void  DisposePreprocess Instruct ion HandlerUPP  ( 

PreprocessInstructionHandlerUPP  userUPP  ); 

userUPP 

A  P reprocess  I  nstructionHandlerUPP  pointer. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


DisposeQDPixUPP 

Disposes  of  a  QDPixUPP  pointer. 

void  DisposeQDPixUPP  ( 

QDPixUPP  userUPP  ); 


userUPP 

A  QDPixUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Inside  QuickTime:  Functions  A-H 
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DisposeQTBandwidthNotificationUPP 


Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


DisposeQTBandwidthNotificationUPP 

Disposes  of  a  QTBandwi  dthNoti  f  i  cati  onUPP  pointer. 

void  Di sposeQTBandwi dthNoti fi cati onUPP  ( 

QTBandwi dthNoti fi cati onUPP  userUPP  ); 

userUPP 

A  QTBandwi  dthNoti  f  i  cati  onUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es .  h 


DisposeQTCallBackUPP 

Disposes  of  a  QTCal  1  BackUPP  pointer. 

void  DisposeQTCallBackUPP  ( 

QTCal 1 BackUPP  userUPP  ); 


userUPP 

A  QTCal  1  BackUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^94). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Movi  es .  h 
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DisposeQTSNotificationUPP 


DisposeQTSNotificationUPP 


Disposes  of  a  QTSNoti  f  i  cati  onUPP  pointer. 

void  DisposeQTSNotificationUPP  ( 

QTSNoti fi cati onUPP  userUPP  ); 


userUPP 

A  QTSNoti  fi  cati  onUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Qui ckTi  meStreami  ng .  h 


DisposeQTSModalFilterUPP 

Disposes  of  a  QTSModal  Fi  1  terUPP  pointer. 

void  DisposeQTSModalFilterUPP  ( 

QTSModal FilterUPP  userUPP  ); 

userUPP 

A  QTSModal  Fi  1  terUPP  pointer. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi  meStreami  ng .  h 


DisposeQTSPanelFilterUPP 


Disposes  of  a  QTSPanel  Fi  1  terUPP  pointer. 

void  DisposeQTSPanelFilterUPP  ( 

QTSPanel Fi 1 terUPP  userUPP  ); 


Inside  QuickTime:  Functions  A-H 
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DisposeQTSyncTaskUPP 


userUPP 

A  QTSPanel  Fi  1  terUPP  pointer. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


DisposeQTSyncT  askUPP 


Disposes  of  a  QTSyncTaskUPP  pointer. 

void  DisposeQTSyncTaskUPP  ( 

QTSyncTaskUPP  userUPP  ); 


userUPP 

A  QTSyncTaskUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es .  h 


DisposeQTVRBackBufferlmagingUPP 


Disposes  of  a  QTVRBackBuf  f  erlmagi  ngUPP  pointer. 

void  Di sposeQTVRBackBufferlmagi ngUPP  ( 

QTVRBackBufferlmagi ngUPP  userUPP  ); 

userUPP 

A  QTVRBackBufferlmagi  ngUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 
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Inside  QuickTime:  Functions  A-H 


DisposeQTVREnteringNodeUPP 


Programming  Info 

C  interface  file:  QuickTimeVR.h 


DisposeQTVREnteringNodeUPP 


Disposes  of  a  QTVREnteri  ngNodellPP  pointer. 

void  DisposeQTVREnteringNodeUPP  ( 

QTVREnteri ngNodeUPP  userUPP  ); 


userUPP 

A  QTVREnteri  ngNodeUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  QuickTimeVR.h 


DisposeQTVRImagingCompleteUPP 


Disposes  of  a  QTVRImagi  ngCompl  eteUPP  pointer. 

void  DisposeQTVRImagingCompleteUPP  ( 

QTVRImagi ngCompl eteUPP  userUPP  ); 

userUPP 

A  QTVRImagi  ngCompl  eteUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 


Inside  QuickTime:  Functions  A-H 
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DisposeQTVRInterceptUPP 


DisposeQTVRInterceptUPP 


Disposes  of  a  QTVRInterceptUPP  pointer. 

void  DisposeQTVRInterceptUPP  ( 

QTVRInterceptUPP  userUPP  ); 


userUPP 

A  QTVRInterceptUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 


DisposeQTVRLeavingNodeUPP 


Disposes  of  a  QTVRLeavi  ngNodeUPP  pointer. 

void  DisposeQTVRLeavingNodeUPP  ( 

QTVRLeavi ngNodeUPP  userUPP  ); 


userUPP 

A  QTVRLeavi  ngNodeUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 


DisposeQTVRMouseOverHotSpotUPP 


Disposes  of  a  QTVRMouseOverHotSpotUPP  pointer. 

void  DisposeQTVRMouseOverHotSpotUPP  ( 

QTVRMouseOverHotSpotUPP  userUPP  ); 
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DisposeRTPMPDataReleaseUPP 


userUPP 

A  QTVRMouseOverHotSpotUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 


DisposeRTPMPDataReleaseUPP 


Disposes  of  an  RTPMPDataRel  easellPP  pointer. 

void  DisposeRTPMPDataReleaseUPP  ( 

RTPMPDataRel easeUPP  userUPP  ); 


userUPP 

An  RTPMPDataRel  easeUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  QTStreami  ngComponents  .  h 


DisposeRTPPB  CallbackUPP 

Disposes  of  an  RTPPBCal  1  backUPP  pointer. 

void  Di sposeRTPPBCall backUPP  ( 

RTPPBCal 1 backUPP  userUPP  ); 

userUPP 

An  RTPPBCal  1  backUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 
function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 


Inside  QuickTime:  Functions  A-H 
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DisposeSCModalFilterUPP 


(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


DisposeSCModalFilterUPP 

Disposes  of  an  SCModal  Fi  1  terllPP  pointer. 

void  DisposeSCModalFilterUPP  ( 

SCModal Fi 1 terUPP  userUPP  ); 


userUPP 

An  SCModal  Fi  1  terUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


DisposeSCModalHookUPP 

Disposes  of  an  SCModal  HookUPP  pointer. 

void  DisposeSCModalHookUPP  ( 

SCModal HookUPP  userUPP  ); 


userUPP 

An  SCModal  HookUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 
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DisposeSGAddFrameBottleUPP 


DisposeSGAddFrameBottleUPP 

Disposes  of  an  SGAddFrameBottl  ellPP  pointer. 

void  DisposeSGAddFrameBottleUPP  ( 

SGAddFrameBottl eUPP  userUPP  ); 


userUPP 

An  SGAddFrameBottl  eUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


DisposeSGCompressBottleUPP 

Disposes  of  an  SGCompressBottl  eUPP  pointer. 

void  DisposeSGCompressBottleUPP  ( 

SGCompressBottl eUPP  userUPP  ); 


userUPP 

An  SGCompressBottl  eUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 


DisposeSGCompressCompleteBottleUPP 


Disposes  of  an  SGCompressCompl  eteBottl  eUPP  pointer. 


Inside  QuickTime:  Functions  A-H 
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DisposeSGDataUPP 


void  Di sposeSGCompressCompl eteBottl  eUPP  ( 

SGCompressCompl eteBottl eUPP  userUPP  ); 

userUPP 

An  SGCompressCompl  eteBottl  eUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


DisposeSGDataUPP 

Disposes  of  an  SGDataUPP  pointer. 

void  DisposeSGDataUPP  ( 

SGDataUPP  userUPP  ); 


userUPP 

An  SGDataUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Qui ckTi meComponents. h 


DisposeSGDisplayBottleUPP 


Disposes  of  an  SGDi  spl  ayBottl  eUPP  pointer. 

void  DisposeSGDisplayBottleUPP  ( 

SGDi spl ayBottl eUPP  userUPP  ); 

userUPP 

An  SGDi  spl  ayBottl  eUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 
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DisposeSGDisplayCompressBottleUPP 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


DisposeSGDisplayCompressBottleUPP 

Disposes  of  an  SGDi  s pi  ayCompressBottl  eUPP  pointer. 

void  Di sposeSGDi spl ayCompressBottl eUPP  ( 

SGDi  s  pi  ayCompressBottl  eUPP  userllPP  ); 

userllPP 

An  SGDi  spl  ayCompressBottl  eUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 


DisposeSGGrabBottleUPP 

Disposes  of  an  SGGrabBottl  eUPP  pointer. 

void  DisposeSGGrabBottleUPP  ( 

SGGrabBottl eUPP  userUPP  ); 


userUPP 

An  SGGrabBottl  eUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 
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DisposeSGGrabCompleteBottleUPP 


Programming  Info 

C  interface  file:  QuickTimeComponents.h 


DisposeSGGrabCompleteBottleUPP 

Disposes  of  an  SGGrabCompl  eteBottl  eliPP  pointer. 

void  DisposeSGGrabCompleteBottleUPP  ( 

SGGrabCompl eteBottl eUPP  userUPP  ); 


userUPP 

An  SGGrabCompl  eteBottl  eUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


DisposeSGGrabCompressCompleteBottleUPP 


Disposes  of  an  SGGrabCompressCompl  eteBottl  eUPP  pointer. 

void  Di sposeSGGrabCompressCompl eteBottl eUPP  ( 

SGGrabCompressCompl eteBottl eUPP  userUPP  ); 


userUPP 

An  SGGrabCompressCompl  eteBottl  eUPP  pointer.  See  "Universal  Procedure 
Pointers"  (IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1-A9A). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 
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DisposeSGModalFilterUPP 


DisposeSGModalFilterUPP 

Disposes  of  an  SGModal  Fi  1  terUPP  pointer. 

void  DisposeSGModalFilterUPP  ( 

SGModal Fi 1 terUPP  userUPP  ); 


userUPP 

An  SGModal  Fi  1  terUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


DisposeSGTransferFrameBottleUPP 


Disposes  of  an  SGT ransferFrameBottl  eUPP  pointer. 

void  Di sposeSGTransferFrameBottl eUPP  ( 

SGTransferFrameBottl eUPP  userUPP  ); 


userUPP 

An  SGTransferFrameBottl  eUPP  pointer.  See  "Universal  Procedure  Pointers" 
(IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 


DisposeSICompletionUPP 

Disposes  of  an  SICompI  eti  onUPP  pointer, 
void  DisposeSICompletionUPP  ( 
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DisposeSIInterruptUPP 


SICompI eti onUPP  userUPP  ); 


userUPP 

An  SICompI  eti  onUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Sound .  h 


DisposeSIInterruptUPP 


Disposes  of  an  SI  InterruptUPP  pointer. 

void  DisposeSIInterruptUPP  ( 

SI InterruptUPP  userUPP  ); 


userUPP 

An  SI  InterruptUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Sound .  h 


DisposeSndCallBackUPP 

Disposes  of  a  SndCal  1  BackUPP  pointer. 

void  DisposeSndCallBackUPP  ( 

SndCal 1 BackUPP  userUPP  ); 

userUPP 

A  SndCal  1  BackUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 
function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
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DisposeSndDoubleBackUPP 


(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Sound .  h 


DisposeSndDoubleBackUPP 


Deprecated. 

void  DisposeSndDoubleBackUPP  ( 

SndDoubl eBackUPP  userUPP  ); 


Version  Notes 

Introduced  in  QuickTime  4.1.  Macintosh  Note:  Not  supported  by  CarbonLib. 

Programming  Info 

C  interface  file:  Sound .  h 


DisposeSoundConverterFillBufferDataUPP 


Disposes  of  a  SoundConverterFi  1 1  BufferDataUPP  pointer. 

void  Di sposeSoundConverterFi 1 1  But f erDataUPP  ( 

SoundConverterFi 1 1  Buff erDataUPP  userUPP  ); 


userUPP 

A  SoundConverterFi  1 1  BufferDataUPP  pointer.  See  "Universal  Procedure 
Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Sound .  h 
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DisposeSoundParamUPP 


DisposeSoundParamUPP 


Disposes  of  a  SoundParamUPP  pointer. 

void  DisposeSoundParamUPP  ( 

SoundParamUPP  userUPP  ); 


userUPP 

A  SoundParamUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Sound .  h 


DisposeSprite 

Disposes  of  a  sprite. 

void  DisposeSprite  ( 

Spri te  theSpri te  ) ; 

theSpri te 

The  sprite  to  be  disposed  of. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Discussion 

You  call  this  function  to  dispose  of  a  sprite  created  by  NewSpri te  (11-1113).  The 
image  description  handle  and  image  data  pointer  associated  with  the  sprite  are  not 
disposed  of  by  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Creating  and  Manipulating  Sprites"  (V-2901) 

Related  Java  Methods 

qu i c kti me. std. an im. Sprite. remove ( ) 
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DisposeSprite  World 


DisposeSpriteWorld 

Disposes  of  a  sprite  world. 

void  DisposeSpriteWorld  ( 

SpriteWorld  theSpri  teWorl  d  ); 

theSpri teWorl d 

The  sprite  world  to  dispose  of.  It  is  safe  to  pass  N I L  to  this  function. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Discussion 

You  call  this  function  to  dispose  of  a  sprite  world  created  by  NewSpri  teWorl  d 
(11-1114).  This  function  also  disposes  of  all  of  the  sprites  associated  with  the  sprite 
world.  This  function  does  not  dispose  of  the  graphics  worlds  associated  with  the 
sprite  world.  Here  is  an  example  of  using  it: 

//  DisposeSpriteWorld  coding  example 
//  See  “Discovering  QuickTime,”  page  347 
#define  kNumSprites  4 

#define  kNumSpaceShi plmages  24 

SpriteWorld  gSpriteWorld  =  NIL; 

Sprite  gSprites[kNumSprites] ; 

Handl e  gCompressedPi ctu res [kNumSpaceShi plmages] ; 

ImageDescri pti onHandl e  glmageDescri pti on s [kNumSpaceShi plmages] ; 

void  MyDi sposeEverythi ng  (void) 

{ 

short  nlndex; 

//  dispose  of  the  sprite  world  and  associated  graphics  world 
if  (gSpriteWorld) 

DisposeSpri teWorl d(gSpriteWorld); 

//  dispose  of  each  sprite’s  image  data 
for  (nlndex  =  0;  nlndex  <  kNumSprites;  nlndex++)  { 
i f  (gCompressedPi ctures [nlndex] ) 

DisposeHandl e( gCompressedPi ctures [nlndex] ) ; 
if  ( glmageDescri pti ons[n I ndex] ) 

DisposeHandle( (Handl e)g!mageDescriptions[nIndex]); 


Inside  QuickTime:  Functions  A-H 


1-297 


DisposeStartDocumentHandlerUPP 


} 

DisposeGWorld(spritePlane) ; 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  with  Sprite  Worlds"  (V-2900) 


DisposeStartDocumentHandlerUPP 


Disposes  of  a  StartDocumentHandl  erllPP  pointer. 

void  DisposeStartDocumentHandlerUPP  ( 

StartDocumentHandl erUPP  userUPP  ); 

userUPP 

A  StartDocumentHandl  erUPP  pointer. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


DisposeStartElementHandlerUPP 

Disposes  of  a  StartEl  ementHandl  erUPP  pointer. 

void  DisposeStartElementHandlerUPP  ( 

StartEl ementHandl erUPP  userUPP  ); 

userUPP 

A  StartEl  ementHandl  erUPP  pointer. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 
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DisposeStdPixUPP 


DisposeStdPixUPP 

Disposes  of  a  StdPixUPP  pointer. 

void  DisposeStdPixUPP  ( 

StdPixUPP  userUPP  ); 


userUPP 

A  StdPixUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


DisposeTextMediaUPP 


Disposes  of  a  TextMedi  aUPP  pointer. 

void  DisposeTextMediaUPP  ( 

TextMedi aUPP  userUPP  ); 


userUPP 

A  TextMedi  aUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4.1. 


Programming  Info 

C  interface  file:  Movi  es  .  h 


DisposeTimeBase 

Disposes  of  a  time  base  once  you  are  finished  with  it. 

void  DisposeTimeBase  ( 

TimeBase  tb  ); 
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DisposeTrackEditState 


The  time  base  for  this  operation.  Your  application  obtains  this  time  base 
identifier  from  NewTimeBase  (11-1119). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94). 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Creating  and  Disposing  of  Time  Bases"  (V-2759) 


DisposeT  rackEditState 

Disposes  of  a  movie's  track  edit  state. 

OSErr  DisposeTrackEditState  ( 

TrackEdi tState  state  ); 

state 

The  edit  state  for  this  operation.  Your  application  obtains  this  edit  state 
identifier  when  you  create  the  edit  state  by  calling  the  NewT  rackEditState 
(11-1119)  function. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

Your  application  must  dispose  of  any  edit  states  you  create.  You  create  an  edit  state 
by  calling  NewTrackEdi  tState  (11-1119). 

Special  Considerations 

You  must  dispose  of  a  movie's  track  edit  states  before  you  dispose  of  the  track  or 
the  movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Undo  for  Tracks"  (V-2751) 
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DisposeTrackMedia 


DisposeTrackMedia 

Removes  a  media  from  a  track. 

void  DisposeTrackMedia  ( 

Media  theMedia  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535)  and. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Discussion 

This  function  does  not  remove  the  track  from  its  movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Creating  Tracks  and  Media  Structures"  (V-2726) 

Related  Java  Methods 

qui ckti me . std .movi  es . Track. removeMedi a( ) 


DisposeT  rackT  ransf  erUPP 


Disposes  of  a  T rackT ransferUPP  pointer. 

void  Di sposeTrackTransferUPP  ( 

TrackTransferUPP  userUPP  ); 


userUPP 

A  TrackTransferUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es  .  h 
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DisposeTuneCallBackUPP 


DisposeTuneCallBackUPP 


Disposes  of  a  T uneCal  1  BackUPP  pointer. 

void  DisposeTuneCallBackUPP  ( 

TuneCall BackUPP  userUPP  ); 


userUPP 

A  TuneCal  1  BackUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 


DisposeTunePlayCallBackUPP 


Disposes  of  a  T unePl  ayCal  1  BackUPP  pointer. 

void  DisposeTunePlayCallBackUPP  ( 

TunePl ayCal 1 BackUPP  userUPP  ); 


userUPP 

A  T unePl  ayCal  1  BackUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 


DisposeT  weenerDataUPP 


Disposes  of  a  TweenerDataUPP  pointer. 

void  Di sposeTweenerDataUPP  ( 

TweenerDataUPP  userUPP  ); 
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DisposeUserData 


userUPP 

A  TweenerDataUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


DisposeUserData 


Disposes  of  a  user  data  structure  created  by  NewUserData  (11-1124). 

OSErr  DisposeUserData  ( 

UserData  theUserData  ); 

theUserData 

The  user  data  structure  that  is  to  be  disposed  of.  It  is  acceptable  but  unnecessary 
to  pass  NI L  in  this  parameter. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  User  Data"  (V-2743) 


DisposeVdiglntUPP 

Disposes  of  a  VdiglntUPP  pointer. 

void  DisposeVdiglntUPP  ( 

VdiglntUPP  userUPP  ); 

userUPP 

A  VdiglntUPP  pointer.  See  "Universal  Procedure  Pointers"  (IV-2641). 
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DragAlignedGrayRgn 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


DragAlignedGrayRgn 


Drags  a  specified  gray  region  along  an  optimal  alignment  grid. 

long  DragAlignedGrayRgn  ( 

RgnHandl e 
Poi  nt 
Rect 
Rect 
short 

Uni versal ProcPtr 
Rect 

ICMAlignmentProcRecordPtr 
theRgn 

A  handle  to  the  specified  region  for  this  operation.  When  the  user  holds  down 
the  mouse  button,  DragAlignedGrayRgnpullsagray  outline  of  the  region  around 
following  the  movement  of  the  mouse  until  the  mouse  button  is  released. 

startPt 

The  point  where  the  mouse  button  was  originally  pressed  in  the  local 
coordinates  of  the  current  graphics  port. 

boundsRect 

A  pointer  to  the  boundary  rectangle  of  the  current  graphics  port.  The  offset 
point  follows  the  mouse  location  except  that  DragAlignedGrayRgn  never  moves 
the  offset  point  outside  this  rectangle.  This  limits  the  travel  of  the  region's 
outline,  not  the  movements  of  the  mouse, 
si opRect 

A  pointer  to  the  slop  rectangle  that  completely  encloses  the  boundary  rectangle 
so  that  the  user  is  allowed  some  flexibility  in  moving  the  mouse. 

axi  s 

Allows  you  to  constrain  the  region's  motion  to  only  one  axis  (see  constants 
below). 


theRgn , 
startPt , 
*boundsRect , 

*sl opRect , 
axi  s , 

acti onProc , 

*al i gnmentRect , 
al i gnmentProc  ) ; 
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DragAlignedGrayRgn 


acti onProc 

Points  to  a  function  that  defines  some  action  to  be  performed  repeatedly  as  long 
as  the  user  holds  down  the  mouse  button.  The  function  should  have  no 
parameters.  If  the  acti  onProc  parameter  is  NIL,  DragAl  i gnedGrayRgn  simply 
retains  control  until  the  mouse  button  is  released, 
al i gnmentRect 

A  pointer  to  a  rectangle  within  the  bounds  of  the  region  specified  in  the 
parameter  t  h  e  Rg  n .  Pass  N I L  to  align  using  the  bounds  of  the  parameter  t  h  e  Rg  n . 

al i gnmentProc 

A  pointer  to  your  alignment  behavior  function;  see  I  CM  Al  i  gnmentProc  (III— 2086). 
Pass  N I L  to  use  the  standard  behavior. 

function  result  The  difference  between  the  point  where  the  mouse  button  was 

pressed  and  the  offset  point;  that  is,  the  point  in  the  region  whose 
horizontal  and  vertical  offsets  from  the  upper-left  comer  of  the 
region's  enclosing  rectangle  are  the  same  as  the  offsets  of  the  starting 
point  when  the  user  pressed  the  mouse  button.  The  vertical 
difference  between  the  starting  point  and  the  offset  point  is  stored  in 
the  high-order  word  of  the  return  value  and  the  horizontal  difference 
is  stored  in  the  low-order  word. 

axis  Constants 

0x0000 

No  constraint. 

0x0001 

Constraint  along  the  horizontal  axis. 

0x0002 

Constraint  along  the  vertical  axis. 

Discussion 

This  function  limits  the  movement  of  the  region  defined  by  theRgn  according  to  the 
constraints  set  by  the  boundsRect  and  si  opRect  parameters.  While  the  cursor  is 
inside  the  boundsRect  rectangle,  the  region's  outline  follows  it  normally.  If  the 
mouse  button  is  released  while  the  cursor  is  within  this  rectangle,  the  return  value 
reflects  the  simple  distance  that  the  cursor  moved  in  each  dimension.  When  the 
cursor  moves  outside  the  boundsRect  rectangle,  the  offset  point  stops  at  the  edge  of 
the  boundsRect  rectangle.  If  the  mouse  button  is  released  while  the  cursor  is  outside 
the  boundsRect  rectangle  but  inside  the  si  opRect  rectangle,  the  return  value  reflects 
only  the  difference  between  the  starting  point  and  the  offset  point,  regardless  of 
how  far  outside  of  the  boundsRect  rectangle  the  cursor  may  have  moved.  (Note  that 
part  of  the  region  can  fall  outside  the  boundsRect  rectangle,  but  not  the  offset  point.) 
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When  the  cursor  moves  outside  the  si  opRect  rectangle,  the  region's  outline 
disappears  from  the  screen.  DragAl  i  gnedGrayRgn  continues  to  track  the  cursor, 
however,  and  if  the  cursor  moves  back  into  the  si  opRect  rectangle,  the  outline 
reappears.  If  the  mouse  button  is  released  while  the  cursor  is  anywhere  inside  the 
si  opRect  rectangle,  the  window  is  redrawn  in  its  new  location,  calculated  from  the 
value  returned  by  DragAl  i  gnedGrayRgn  If  the  mouse  button  is  released  while  the 
cursor  is  outside  the  si  opRect  rectangle,  both  words  of  the  return  value  are  set  to 
0x8000  and  the  window  does  not  move  from  its  original  location. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Aligning  Windows"  (V-2797) 


DragAlignedWindow 


Drags  the  specified  window  along  an  optimal  alignment  grid. 


void  DragAlignedWindow  ( 

Wi ndowPtr 
Poi  nt 
Rect 
Rect 

ICMA1 i gnmentProcRecordPtr 


wp , 

startPt , 
*boundsRect , 

*al i gnmentRect , 
al i gnmentProc  ) ; 


wp 

A  window  pointer  to  the  window  to  be  dragged. 
startPt 

A  point  that  is  equal  to  the  point  where  the  mouse  button  was  pressed  (in  global 
coordinates,  as  stored  in  the  where  field  of  the  event  structure). 

DragAl  i  gnedWi  ndow  pulls  a  gray  outline  of  the  window  around  the  screen, 
following  the  movements  of  the  mouse  until  the  button  is  released. 

boundsRect 

Points  to  the  boundary  rectangle  in  global  coordinates.  If  the  mouse  button  is 
released  when  the  mouse  position  is  outside  the  limits  of  the  boundary 
rectangle,  DragAl  i  gnedWi  ndow  returns  without  moving  the  window  or  making  it 
the  active  window.  For  a  document  window,  the  boundary  rectangle  typically 
is  four  pixels  in  from  the  menu  bar  and  from  the  other  edges  of  the  screen,  to 
ensure  that  there  won't  be  less  than  a  four-pixel-square  area  of  the  title  bar 
visible  on  the  screen. 
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al i gnmentRect 

Points  to  a  rectangle  in  window  coordinates  that  allows  you  to  align  the 
window  to  a  rectangle  within  the  window.  Set  this  parameter  to  N I L  to  align 
using  the  bounds  of  the  window, 
al i gnmentProc 

A  pointer  to  your  alignment  behavior  function;  see  I  CM  Al  i  gnmentProc  (III— 2086). 
Pass  N I L  to  use  the  standard  behavior. 

Discussion 

The  following  code  sample  illustrates  the  use  of  DragAl  i  gnedWi  ndow: 

//  DragAlignedWindow  coding  example 
//  See  “Discovering  QuickTime,”  page  265 
Boolean  IsQuickTimelnstal 1 ed  (void) 

{ 

OSErr  nErr; 

long  IResult; 

nErr  =  Gestal t( gestal tQui ckTime ,  & 1  Res u 1 1 ) ; 
return  (nErr  ==  noErr); 

} 

void  Mylnitialize  (void) 

{ 

InitGraf(&qd.thePort) ; 

InitFonts( ) ; 

InitWindows( ) ; 

InitMenus( ) ; 

TEIni t( ) ; 

Ini t Di al ogs(NIL) ; 

MaxAppl Zone( ) ; 

EnterMovi es ( ) ; 

} 


WindowPtr  MakeMyWindow  (void) 

{ 

WindowPtr  pMacWnd; 

Rect  rectWnd  =  {0,  0,  120,  160}; 

Rect  rectBest; 
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//  figure  out  the  best  monitor  for  the  window 
GetBest Device RecttNIL,  &rectBest) ; 

//  put  the  window  in  the  top  left  corner  of  that  monitor 
OffsetRectt&rectWnd,  rectBest . 1  eft  +  10,  rectBest.top  +  50) 

//  create  the  window 

pMacWnd  =  NewCWindowtNIL,  &rectWnd,  "\pGrabber", 

TRUE,  noGrowDocProc ,  ( Wi ndowPtr ) - 1 , 
TRUE,  0); 

//  set  the  port  to  the  new  window 
SetPort(pMacWnd) ; 

return  pMacWnd; 


main  (void) 

{ 

Wi ndowPtr 
SeqGrabComponent 
SGChannel 
Bool ean 
OSErr 

Mylni ti a  1 i ze ( ) ; 
pMacWnd  =  MakeMyWi ndow( ) ; 
seqGrab  =  MakeMySequenceGrabber(pMacWnd) ; 
if  (seqGrab  ==  NIL) 
return ; 

MakeMyGrabChannelstseqGrab,  &sgchanVi deo  ,  &sgchanSound , 
&pMacWnd->portRect ,  FALSE); 

nErr  =  SGStartPreview(seqGrab) ; 

while  ( ! bDone)  { 

ICMA1 i gnmentProcRecord  apr; 
short  nPart; 

WindowPtr  pWhichWnd; 

EventRecord  er; 


pMacWnd ; 
seqGrab ; 

sgchanVideo,  sgchanSound; 
bDone  =  FALSE; 
nErr ; 
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GetNextEventCeveryEvent,  &er); 
switch  (er.what)  { 

case  nullEvent:  //  give  the  sequence  grabber  time 

nErr  =  SGIdl e(seqGrab) ; 
if  (nErr  !=  noErr) 
bDone  =  TRUE; 
break; 

case  updateEvt: 

if  (er. message  ==  (1 ong)pMacWnd)  { 

//  inform  the  sequence  grabber  of  the  update 
SGUpdate( seqGrab , ( (Wi ndowPeek) 

pMacWnd ) ->updateRgn ) ; 

//  and  swallow  the  update  event 
Begi n Update ( pMacWnd ) ; 

End Update! pMacWnd ) ; 

} 

break; 

case  mouseDown: 

nPart  =  Fi ndWi ndow(er .where ,  &pWhichWnd); 
if  (pWhichWnd  !=  pMacWnd) 
break; 

switch  (nPart)  { 
case  inContent: 

//  pause  until  mouse  button  is  released 
SGPauseC seqGrab ,  TRUE); 
while  ( St i 1 1  Down ( ) ) 

SGPauseC seqGrab ,  FALSE); 
break; 
case  inGoAway: 

bDone  =  TrackGoAway( pMacWnd ,  er. where); 
break; 


case  inDrag: 

//  pause  when  dragging  window  so  video 
//  doesn't  draw  in  the  wrong  place 
SGPauseC seqGrab ,  TRUE); 
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SGGetAl i gnmentProct seqGrab ,  &apr ) ; 
DragAl i gnedWi ndow( pMacWnd , 

er .where , 

&screenBits. bounds, 
NIL,  &al  i gnProc) ; 
SGPause(seqGrab,  FALSE); 
break; 


//  clean  up 
SGStop(seqGrab) ; 

CloseComponent(seqGrab) ; 

DisposeWindow(pMacWnd) ; 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Aligning  Windows"  (V-2797) 


DrawPictureFile 


Draws  an  image  from  a  specified  picture  file  in  the  current  graphics  port. 

OSErr  DrawPictureFile  ( 
short 

const  Rect 

ICMProgressProcRecordPtr 
ref Num 

A  file  reference  number  for  the  source  PICT  file, 
frame 

A  pointer  to  the  rectangle  into  which  the  image  is  to  be  loaded.  The  compressor 
scales  the  source  image  to  fit  into  this  destination  rectangle. 


ref Num , 

*f rame , 

progressProc  ) ; 
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progressProc 

Points  to  an  ICMProgressProc  (III— 2093)  callback.  During  the  operation,  the 
draw  function  may  occasionally  call  a  function  you  provide  in  order  to  report 
its  progress;  see  ICMProgressProc  Record  (IV-2284).  If  you  have  not  provided  a 
progress  function,  set  this  parameter  to  NIL.  If  you  pass  a  value  of  -1, 
QuickTime  provides  a  standard  progress  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  draws  the  picture  that  it  finds  in  the  picture  file  specified  by  the 
ref  Num  parameter  within  the  rectangle  specified  by  the  frame  parameter.  The  Image 
Compression  Manager  performs  any  spooling  that  maybe  necessary  when  reading 
the  picture  file.  Specify  a  clipping  region  appropriate  for  your  picture  before 
drawing  it.  If  the  clipping  region  is  very  large  (as  it  is  when  a  graphics  port  is 
initialized)  and  you  want  to  scale  the  picture,  the  clipping  region  can  become 
invalid  when  DrawPictureFile  scales  the  clipping  region,  in  which  case  your  picture 
will  not  be  drawn.  On  the  other  hand,  if  the  graphics  port  specifies  a  small  clipping 
region,  part  of  your  drawing  may  be  clipped  when  DrawPi  ctureFi  1  e  draws  it. 
Setting  a  clipping  region  equal  to  the  port  rectangle  of  the  current  graphics  port 
always  sets  a  valid  clipping  region. 

Special  Considerations 

When  it  scales  fonts,  DrawPi  ctureFi  le  changes  the  size  of  the  font  instead  of  scaling 
the  bits.  However,  the  widths  used  by  bitmap  fonts  are  not  always  linear.  For 
example,  the  12-point  width  isn't  exactly  1  /2  of  the  24-point  width.  This  can  cause 
lines  of  text  to  become  slightly  longer  or  shorter  as  the  picture  is  scaled.  The  easiest 
way  to  avoid  such  problems  is  to  specify  a  destination  rectangle  that  is  the  same  size 
as  the  bounding  rectangle  for  the  picture. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Pictures  and  PICT  Files"  (V-2790) 


DrawT  rimmedPicture 


Draws  an  image  that  is  stored  as  a  picture  into  the  current  graphics  port  and  trims 
that  image  to  fit  a  specified  region. 

OSErr  DrawTrimmedPicture  ( 

PicHandle  srcPicture, 
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const  Rect  *frame, 

RgnHandle  trimMask, 

short  doDither, 

ICMProgressProcRecordPtr  progressProc  ); 

srcPi cture 

A  handle  to  the  source  image,  stored  as  a  picture, 
frame 

A  pointer  to  the  rectangle  into  which  the  decompressed  image  is  to  be  loaded, 
tri mMask 

A  handle  to  a  clipping  region  in  the  destination  coordinate  system.  The 
decompressor  applies  this  mask  to  the  destination  image  and  ignores  any 
image  data  that  fall  outside  the  specified  region.  Set  this  parameter  to  N I L  if  you 
do  not  want  to  clip  the  source  image. 
doDi ther 

Indicates  whether  to  dither  the  image.  Use  this  parameter  if  you  want  the 
image  to  be  dithered  when  it  is  displayed  on  a  lower-resolution  screen  (see 
below). 
progressProc 

A  pointer  to  an  ICMProgressProc  (III— 2093)  callback.  During  the  compression 
operation,  the  compressor  may  occasionally  call  a  function  you  provide  in 
order  to  report  its  progress.  If  you  have  not  provided  a  progress  function,  set 
this  parameter  to  N I L.  If  you  pass  a  value  of  -1,  QuickTime  provides  a  standard 
progress  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

doDither  Constants 

defaul tDi ther 

The  dithering  in  the  source  file  is  to  be  respected. 
forceDi ther 

The  specified  image  should  be  dithered  whether  the  source  uses  dithering  or 
not. 

suppressDi ther 

Dithering  should  not  be  used  in  any  case.  The  ability  to  suppress  dithering  can 
be  useful  if,  for  example,  you  have  a  32-bit,  color  JPEG  image  drawn  into  an 
8-bit  buffer  with  a  custom  color  table  from  the  image.  In  that  case,  dithering 
would  not  be  necessary  and  probably  not  desirable,  particularly  if  the  buffer 
were  to  be  compressed  with  the  graphics  compressor. 
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Discussion 

This  function  works  with  compressed  image  data;  the  source  data  stays 
compressed.  The  function  trims  the  image  to  fit  the  specified  clipping  region.  Note 
that  if  you  just  use  a  clip  while  making  a  picture,  the  data  (though  not  visible)  is  still 
stored  in  the  picture. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Pictures  and  PICT  Files"  (V-2790) 

Related  Java  Methods 

qui cktime . qd . Pi ct . drawTri mmed( ) 


DrawT  rimmedPictureFile 


Draws  an  image  that  is  stored  as  a  picture  file  into  the  current  graphics  port  and 
trims  that  image  to  fit  a  specified  region. 


OSErr  DrawTrimmedPictureFile 
short 

const  Rect 
RgnHandl e 
short 

ICMProgressProcRecordPtr 


srcRefnum, 

*f rame , 
trimMask, 
doDi ther , 
progressProc  ); 


srcRefnum 

A  file  reference  number  for  the  source  PICT  file, 
frame 

A  pointer  to  the  rectangle  into  which  the  decompressed  image  is  to  be  loaded. 
trimMask 

A  handle  to  a  clipping  region  in  the  destination  coordinate  system.  The 
decompressor  applies  this  mask  to  the  destination  image  and  ignores  any 
image  data  that  fall  outside  the  specified  region.  Set  this  parameter  to  N I L  if  you 
do  not  want  to  clip  the  source  image.  In  this  case,  this  function  acts  like 
DrawPi  ctureFi  1  e  (1-310). 

doDi ther 

Indicates  whether  to  dither  the  image.  Use  this  parameter  if  you  want  the 
image  to  be  dithered  when  it  is  displayed  on  a  lower-resolution  screen  (see 
below). 
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progressProc 

A  pointer  to  an  ICMProgressProc  (III— 2093)  callback.  During  the  compression 
operation,  the  compressor  may  occasionally  call  a  function  you  provide  in 
order  to  report  its  progress.  If  you  have  not  provided  a  progress  function,  set 
this  parameter  to  N I L.  If  you  pass  a  value  of  -1,  QuickTime  provides  a  standard 
progress  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

doDither  Constants 

defaul tDi ther 

The  dithering  in  the  source  file  is  to  be  respected. 
forceDi ther 

The  specified  image  should  be  dithered  whether  the  source  uses  dithering  or 
not. 

suppressDi ther 

Dithering  should  not  be  used  in  any  case.  The  ability  to  suppress  dithering  can 
be  useful  if,  for  example,  you  have  a  32-bit,  color  JPEG  image  drawn  into  an 
8-bit  buffer  with  a  custom  color  table  from  the  image.  In  that  case,  dithering 
would  not  be  necessary  and  probably  not  desirable,  particularly  if  the  buffer 
were  to  be  compressed  with  the  graphics  compressor. 

Discussion 

You  can  use  this  function  to  save  part  of  a  picture,  since  the  image  data  that  is  not 
within  the  trim  region  is  ignored  and  is  not  included  in  the  destination  picture  file. 
All  the  remaining  objects  in  the  resulting  object  are  clipped. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Pictures  and  PICT  Files"  (V-2790) 


E 


EndFullScreen 


Ends  full-screen  mode  for  a  graphics  device. 
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OSErr  EndFullScreen  ( 

Ptr  fullState, 

long  flags  ); 

f ul 1  State 

The  pointer  to  private  state  information  returned  by  a  previous  call  to 
Begi  nFull  Screen  (1-52). 

fl  ags 

Reserved.  Set  this  parameter  to  NIL. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

This  function  restores  the  graphics  device  and  other  settings  to  the  state  specified  by 
the  private  state  information  pointed  to  by  the  fullState  parameter.  The  resulting 
state  is  that  that  was  in  effect  prior  to  the  immediately  previous  call  to 
BeginFul  1  Screen  (1-52).  The  following  code  illustrates  its  use: 

OSErr  QTFul 1 Screen_RestoreScreen  (void) 

{ 

OSErr  myErr  =  noErr; 

#if  TARGET_0S_WIN32 

DestroyPortAssoci ation((CGrafPtr)gFull ScreenWi ndow) ; 

#endi f 

Di sposeMovi eControl 1 er(gMC) ; 

myErr  =  EndFul 1 Screen(gRestoreState,  OL); 

return(myErr) ; 

} 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Using  the  Full  Screen"  (V-2717) 

Related  Java  Methods 

qui cktime . std .movi es . Ful 1  Screen . end( ) 
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Endianl6_Swap 

Changes  the  endian  format  of  an  unsigned  16-bit  integer. 

UIntl6  Endi anl6_Swap  ( 

UIntl6  val ue  ) ; 

val  ue 

An  unsigned  16-bit  integer  input. 
function  result  The  unsigned  16-bit  integer  result. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Endi  an .  h 


Endian32_Swap 

Changes  the  endian  format  of  an  unsigned  32-bit  integer. 

UInt32  Endi an32_Swap  ( 

UInt32  val ue  ) ; 

val  ue 

An  unsigned  32-bit  integer  input. 
function  result  The  unsigned  32-bit  integer  result. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Endi  an .  h 


Endian64_Swap 

Changes  the  endian  format  of  an  unsigned  64-bit  integer. 

UInt64  Endi an64_Swap  ( 

UInt64  val ue  )  ; 
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val  ue 

An  unsigned  64-bit  integer  input. 
function  result  The  unsigned  64-bit  integer  result. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Endi  an .  h 

EndianS16_BtoL 

Converts  a  signed  16-bit  big-endian  value  to  the  equivalent  little-endian  value. 

SIntl6  Endi anS16_BtoL  ( 

SIntl6  value  ); 

val  ue 

A  signed  16-bit  big-endian  value. 
function  result  The  equivalent  little-endian  value. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an  .  h 

EndianS16_BtoN 

Converts  a  signed  16-bit  big-endian  value  to  the  equivalent  value  in  the  computer's 
native  format. 

SIntl6  Endi anS16_BtoN  ( 

SIntl6  value  ); 

val  ue 

A  signed  16-bit  big-endian  value. 

function  result  The  equivalent  value  in  the  computer's  native  format. 

Version  Notes 

Introduced  in  QuickTime  4. 
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Programming  Info 

C  interface  file:  Endi  an .  h 


EndianS16_LtoB 

Converts  a  signed  16-bit  little-endian  value  to  the  equivalent  big-endian  value. 

SIntl6  Endi anS16_LtoB  ( 

SIntl6  value  ) ; 

val  ue 

A  signed  16-bit  little-endian  value. 

function  result  The  equivalent  big-endian  value. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 


EndianS16_LtoN 

Converts  a  signed  16-bit  little-endian  value  to  the  equivalent  value  in  the 
computer's  native  format. 

SIntl6  Endi anS16_LtoN  ( 

SIntl6  value  ) ; 

val  ue 

A  signed  16-bit  little-endian  value. 
function  result  The  equivalent  value  in  the  computer's  native  format. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 
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EndianS16_NtoB 

Converts  a  signed  16-bit  value  in  the  computer's  native  format  to  the  equivalent 

big-endian  value. 

SIntl6  Endi anS16_NtoB  ( 

SIntl6  value  ); 


val  ue 

A  signed  16-bit  value  in  the  computer's  native  format. 
function  result  The  equivalent  big-endian  value. 

Discussion 

The  following  code  illustrates  the  use  of  Endi  anS16_NtoB: 


//  Endi anS16_NtoB  coding  example 

//  See  “Discovering  QuickTime,"  page  338 

void  QTMusi c_UseMIDI Input  (void) 

{ 


ComponentResul  t 
MIDI InputExampl  e 
NoteRequest 
MusicMIDIReadHookUPP 


1  Err  =  noErr ; 
mi  e ; 

noteRequest ; 
pfReadHook  =  NIL; 


//  open  the  note  allocator  component 

mi e . f NoteAl locator  =  OpenDefaul tComponent( kNoteAl 1  oca torComponent Type , 

if  (mi e . f NoteAl 1 ocator  ==  NIL) 
goto  bail  ; 


noteRequest . i nfo . fl ags  =  0; 
noteRequest . i nfo . reserved  =  0; 

//  simultaneous  tones 

*(short  *) (&noteRequest . i nfo . polyphony )  =  Endi anS16_NtoB( 2 ) ; 
*(Fixed  *) (&noteRequest . i nfo . typi cal  Polyphony )  = 

Endi anU32_NtoB(0x00010000) ; 


lErr  =  NAStuf fToneDescri pti on(mi e . f NoteAl  1  ocator , 
kInst_Acousti cGrandPiano, 

&note Request. tone) ; 

if  (lErr  !=  noErr) 
goto  bai 1 ; 
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//  allocate  a  note  channel 

lErr  =  NANewNoteChannel (mi e . f NoteAl 1 ocator  ,  &noteRequest , 

&mi e . f NoteChannel ) ; 
if  ( 1 E r r  !=  noErr) 
goto  bail ; 

pfReadHook  =  NewMusicMIDIReadHookProc(QTMusic_ReadHook) ; 

NAUseDefaul tMIDIInputtmie.fNoteAllocator, 

NewMusicMIDIReadHookProc(pfReadHook) ,  (long)&mie,  OL); 
while  ( ! Button ( ) )  ; 

NA Lose Defaul tMIDIInputtmie.fNoteAllocator); 


bail  : 

if  (pfReadHook  !=  NIL) 

Di s pose Rout i neDescri pt or (pfReadHook) ; 
if  (mi e . f NoteAl 1 ocator  !=  NIL) 

Cl oseComponent (mi e . f NoteAl 1 ocator ) ;  //  disposes  note  channel  too 

} 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 


EndianS16_NtoL 

Converts  a  signed  16-bit  value  in  the  computer's  native  format  to  the  equivalent 

little-endian  value. 

SIntl6  Endi anS16_NtoL  ( 

SIntl6  value  ) ; 

val  ue 

A  signed  16-bit  value  in  the  computer's  native  format. 
function  result  The  equivalent  little-endian  value. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 
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EndianS32_BtoL 

Converts  a  signed  32-bit  big-endian  value  to  the  equivalent  little-endian  value. 

SInt32  Endi anS32_BtoL  ( 

SInt32  value  ); 

val  ue 

A  signed  32-bit  big-endian  value. 
function  result  The  equivalent  little-endian  value. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an  .  h 


EndianS32_BtoN 

Converts  a  signed  32-bit  big-endian  value  to  the  equivalent  value  in  the  computer's 
native  format. 

SInt32  Endi anS32_BtoN  ( 

SInt32  value  ); 

val  ue 

A  signed  32-bit  big-endian  value. 

function  result  The  equivalent  value  in  the  computer's  native  format. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 


EndianS32_LtoB 

Converts  a  signed  32-bit  little-endian  value  to  the  equivalent  big-endian  value. 

SInt32  Endi anS32_LtoB  ( 

SInt32  value  ); 
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val  ue 

A  signed  32-bit  little-endian  value. 

function  result  The  equivalent  big-endian  value. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 


EndianS32_LtoN 

Converts  a  signed  32-bit  little-endian  value  to  the  equivalent  value  in  the 
computer's  native  format. 

SInt32  Endi anS32_LtoN  ( 

SInt32  value  ) ; 

val  ue 

A  signed  32-bit  little-endian  value. 
function  result  The  equivalent  value  in  the  computer's  native  format. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 


EndianS32_NtoB 

Converts  a  signed  32-bit  value  in  the  computer's  native  format  to  the  equivalent 

big-endian  value. 

SInt32  Endi anS32_NtoB  ( 

SInt32  value  ) ; 

val  ue 

A  signed  32-bit  value  in  the  computer's  native  format. 
function  result  The  equivalent  big-endian  value. 

Version  Notes 

Introduced  in  QuickTime  4. 
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Programming  Info 

C  interface  file:  Endi  an  .  h 


EndianS32_N  toL 

Converts  a  signed  32-bit  value  in  the  computer's  native  format  to  the  equivalent 

little-endian  value. 

SInt32  Endi anS32_NtoL  ( 

SInt32  value  ); 

val  ue 

A  signed  32-bit  value  in  the  computer's  native  format. 
function  result  The  equivalent  little-endian  value. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an  .  h 


EndianS64_BtoL 

Converts  a  signed  64-bit  big-endian  value  to  the  equivalent  little-endian  value. 

SInt64  Endi anS64„BtoL  ( 

SInt64  value  ); 

val  ue 

A  signed  64-bit  big-endian  value. 
function  result  The  equivalent  little-endian  value. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 
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EndianS64_BtoN 

Converts  a  signed  64-bit  big-endian  value  to  the  equivalent  value  in  the  computer's 
native  format. 

SInt64  Endi anS64_BtoN  ( 

SInt64  value  ) ; 

val  ue 

A  signed  64-bit  big-endian  value. 

function  result  The  equivalent  value  in  the  computer's  native  format. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 


EndianS64_LtoB 

Converts  a  signed  64-bit  little-endian  value  to  the  equivalent  big-endian  value. 

SInt64  Endi anS64_LtoB  ( 

SInt64  value  ) ; 

val  ue 

A  signed  64-bit  little-endian  value. 

function  result  The  equivalent  big-endian  value. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 


EndianS64_LtoN 

Converts  a  signed  64-bit  little-endian  value  to  the  equivalent  value  in  the 
computer's  native  format. 

SInt64  Endi anS64_LtoN  ( 

SInt64  value  ) ; 
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val  ue 

A  signed  64-bit  little-endian  value. 
function  result  The  equivalent  value  in  the  computer's  native  format. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 


EndianS64_NtoB 

Converts  a  signed  64-bit  value  in  the  computer's  native  format  to  the  equivalent 

big-endian  value. 

SInt64  Endi anS64_NtoB  ( 

SInt64  value  ); 

val  ue 

A  signed  64-bit  value  in  the  computer's  native  format. 
function  result  The  equivalent  big-endian  value. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an  .  h 


EndianS64_N  toL 


Converts  a  signed  64-bit  value  in  the  computer's  native  format  to  the  equivalent 

little-endian  value. 

SInt64  Endi anS64_NtoL  ( 

SInt64  value  ); 

val  ue 

A  signed  64-bit  value  in  the  computer's  native  format. 
function  result  The  equivalent  little-endian  value. 

Version  Notes 

Introduced  in  QuickTime  4. 
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Programming  Info 

C  interface  file:  Endi  an .  h 


EndianU16_BtoL 


Converts  an  unsigned  16-bit  big-endian  value  to  the  equivalent  little-endian  value. 

UIntl6  Endi anU16_BtoL  ( 

UIntl6  val ue  ) ; 

val  ue 

An  unsigned  16-bit  big-endian  value. 
function  result  The  equivalent  little-endian  value. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 


EndianU16_BtoN 

Converts  an  unsigned  16-bit  big-endian  value  to  the  equivalent  value  in  the 
computer's  native  format. 

UIntl6  Endi  anlll6_BtoN  ( 

UIntl6  val ue  )  ; 

val  ue 

An  unsigned  16-bit  big-endian  value. 
function  result  The  equivalent  value  in  the  computer's  native  format. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 


EndianU16_LtoB 


Converts  an  unsigned  16-bit  little-endian  value  to  the  equivalent  big-endian  value. 
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UIntl6  EndianU16_LtoB  ( 

UIntl6  value  ); 

val  ue 

An  unsigned  16-bit  little-endian  value. 
function  result  The  equivalent  big-endian  value. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 


EndianU16_LtoN 

Converts  an  unsigned  16-bit  little-endian  value  to  the  equivalent  value  in  the 
computer's  native  format. 

UIntl6  Endi anU16_LtoN  ( 

UIntl6  value  ); 

val  ue 

An  unsigned  16-bit  little-endian  value. 
function  result  The  equivalent  value  in  the  computer's  native  format. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 


EndianU16_NtoB 

Converts  an  unsigned  16-bit  value  in  the  computer's  native  format  to  the  equivalent 

big-endian  value. 

UIntl6  Endi anU16_NtoB  ( 

UIntl6  value  ); 

val  ue 

An  unsigned  16-bit  value  in  the  computer's  native  format. 
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function  result  The  equivalent  big-endian  value. 

Discussion 

The  following  code  sample  illustrates  the  use  of  Endi  anU16_NtoB: 

//  Endi  anlll6_NtoB  coding  example 

//  See  “Discovering  QuickTime,”  page  360 

if  (bWi thBackgroundPi cture )  { 

QTAtomContai ner  qtacTrackProperties; 

RGBColor  rgbcBackCol or ; 

rgbcBackCol or . red  =  EndianU16„NtoB(0x8000) ; 
rgbcBackCol or . green  =  EndianU16_NtoB(0) ; 
rgbcBackCol or . bl ue  =  EndianU16_NtoB0(xffff ) ; 

//  create  a  new  atom  container  for  sprite  track  properties 
QTNewAtomContai ner(&qtacTrackProperties) ; 

//  add  an  atom  for  the  background  color  property 
QTInsertChildt qtacTrackProperties,  0, 

kSpri teTrackPropertyBackgroundCol or ,  1,  1,  si zeof ( RGBCol or ) , 
&rgbcBackCol or ,  NIL); 

//  set  the  sprite  track's  properties 

nErr  =  SetMediaPropertyAtom(media ,  qtacTrackProperties); 

QTDi sposeAtomContai ner (qtacTrackProperties) ; 

} 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 


EndianU  16_N  toL 


Converts  an  unsigned  16-bit  value  in  the  computer's  native  format  to  the  equivalent 

little-endian  value. 

UIntl6  Endi anU16_NtoL  ( 

UIntl6  value  )  ; 
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val  ue 

An  unsigned  16-bit  value  in  the  computer's  native  format. 
function  result  The  equivalent  little-endian  value. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an  .  h 

EndianU32_B  toL 

Converts  an  unsigned  32-bit  big-endian  value  to  the  equivalent  little-endian  value. 

UInt32  Endi anU32_BtoL  ( 

UInt32  value  ); 

val  ue 

An  unsigned  32-bit  big-endian  value. 
function  result  The  equivalent  little-endian  value. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 

EndianU32_B  toN 

Converts  an  unsigned  32-bit  big-endian  value  to  the  equivalent  value  in  the 
computer's  native  format. 

UInt32  Endi anU32_BtoN  ( 

UInt32  value  ); 

val  ue 

An  unsigned  32-bit  big-endian  value. 
function  result  The  equivalent  value  in  the  computer's  native  format. 

Version  Notes 

Introduced  in  QuickTime  4. 
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Programming  Info 

C  interface  file:  Endi  an .  h 


EndianU32_LtoB 

Converts  an  unsigned  32-bit  little-endian  value  to  the  equivalent  big-endian  value. 

UInt32  Endi  anll32_LtoB  ( 

UInt32  val ue  )  ; 

val  ue 

An  unsigned  32-bit  little-endian  value. 
function  result  The  equivalent  big-endian  value. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 


EndianU32_LtoN 

Converts  an  unsigned  32-bit  little-endian  value  to  the  equivalent  value  in  the 
computer's  native  format. 

UInt32  Endi  anll32_LtoN  ( 

UInt32  val ue  ) ; 

val  ue 

An  unsigned  32-bit  little-endian  value. 
function  result  The  equivalent  value  in  the  computer's  native  format. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 
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EndianU32_N  toB 

Converts  an  unsigned  32-bit  value  in  the  computer's  native  format  to  the  equivalent 

big-endian  value. 

UInt32  Endi anU32_NtoB  ( 

UInt32  value  ); 


val  ue 

An  unsigned  32-bit  value  in  the  computer's  native  format. 
function  result  The  equivalent  big-endian  value. 

Discussion 

The  following  code  sample  illustrates  the  use  of  Endi  anll32_NtoB: 


//  Endi anU32_NtoB  coding  example 
//  See  “Discovering  QuickTime,"  page  369 
{ 

QTAtomContai ner  qtacTrackProperties; 

RGBColor  rgbcBackCol or ; 


rgbcBackCol or . red 
rgbcBackCol or. green 
rgbcBackCol or . bl ue 


=  Endi  a  nil  16_NtoB(  0x8000) ; 
=  Endi  anlll6_NtoB(0) ; 

=  Endi anU16_NtoB( Oxf f f f ) ; 


QTNewAtomContai ner(&qtacTrackProperties); 
QTInsertChild(qtacTrackProperties,  0, 

kSpri teTrackPropertyBackgroundCol or ,  1,  1,  sizeof ( RGBCol or) , 
&rgbcBackCol or ,  NIL); 


//  tell  the  movie  controller  that  this  sprite  track  has  actions 
hasActions  =  TRUE; 

QTInsertChi 1 dlqtacTrackProperti es  ,  0, 

kSpri teT rackPropertyHasActi ons  , 

1 ,  1 ,  si zeof ( hasActi ons ) ,  &hasActi ons  ,  NIL); 


//  tell  the  Sprite  Track  to  generate  QTIdleEvents 
idl eEventFrequency  =  EndianU32_NtoB(60) ; 

QTInsertChildlqtacTrackProperties,  0, 

kSpri teTrackPropertyQTIdl eEventsFrequency ,  1,  1, 
si zeof ( i dl eEventFrequency ) ,  &i dl eEventFrequency ,  NIL); 
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Set Med i aPropertyAtom(medi a,  qtacTrackProperties); 

QTDi sposeAtomContai ner( qtacTrackProperties) ; 

} 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 

EndianU32_NtoL 

Converts  an  unsigned  32-bit  value  in  the  computer's  native  format  to  the  equivalent 

little-endian  value. 

UInt32  Endi  antl32_NtoL  ( 

UInt32  val ue  )  ; 

val  ue 

An  unsigned  32-bit  value  in  the  computer's  native  format. 
function  result  The  equivalent  little-endian  value. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 

EndianU64_BtoL 

Converts  an  unsigned  64-bit  big-endian  value  to  the  equivalent  little-endian  value. 

UInt64  Endi anU64_BtoL  ( 

UInt64  val ue  )  ; 

val  ue 

An  unsigned  64-bit  big-endian  value. 
function  result  The  equivalent  little-endian  value. 
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Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 


EndianU64_BtoN 

Converts  an  unsigned  64-bit  big-endian  value  to  the  equivalent  value  in  the 
computer's  native  format. 

UInt64  Endi anU64_BtoN  ( 

UInt64  value  ); 

val  ue 

An  unsigned  64-bit  big-endian  value. 
function  result  The  equivalent  value  in  the  computer's  native  format. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an  .  h 


EndianU64_LtoB 

Converts  an  unsigned  64-bit  little-endian  value  to  the  equivalent  big-endian  value. 

UInt64  Endi anU64„LtoB  ( 

UInt64  value  ); 

val  ue 

An  unsigned  64-bit  little-endian  value. 
function  result  The  equivalent  big-endian  value. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 
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EndianU64_LtoN 

Converts  an  unsigned  64-bit  little-endian  value  to  the  equivalent  value  in  the 
computer's  native  format. 

UInt64  EndianU64_LtoN  ( 

UInt64  val ue  ) ; 

val  ue 

An  unsigned  64-bit  little-endian  value. 
function  result  The  equivalent  value  in  the  computer's  native  format. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 


EndianU  64_N  toB 

Converts  an  unsigned  64-bit  value  in  the  computer's  native  format  to  the  equivalent 

big-endian  value. 

UInt64  Endi  anll64_NtoB  ( 

UInt64  val ue  ) ; 

val  ue 

An  unsigned  64-bit  value  in  the  computer's  native  format. 
function  result  The  equivalent  big-endian  value. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 


EndianU  64_N  toL 

Converts  an  unsigned  64-bit  value  in  the  computer's  native  format  to  the  equivalent 

little-endian  value. 

UInt64  Endi anU64_NtoL  ( 
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UInt64  value  ); 
val  ue 

An  unsigned  64-bit  value  in  the  computer's  native  format. 
function  result  The  equivalent  little-endian  value. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Endi  an .  h 


EndMediaEdits 


Ends  a  media-editing  session. 

OSErr  EndMediaEdits  ( 

Media  theMedia  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

The  following  code  sample  illustrates  the  use  of  EndMedi  aEdi  ts: 

//  EndMediaEdits  coding  example 

//  See  “Discovering  QuickTime,"  page  89 

void  CreateMyVideoTrack  (Movie  movie) 

{ 

Track  track; 

Media  media; 

Rect  rect  =  {0,  0,  100,  320}; 

track  =  NewMovi eTrack(movi e , 

FixRati  o(  rect .  ri  ght ,  1), 

FixRati o( rect . bottom,  1), 
kNoVol ume) ; 
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media  =  NewTrackMedi a ( track , 

Vi deoMedi aType , 

600,  //  video  time  scale 

NIL,  NIL) ; 

Beg in Med i a  Edits (media) ; 

My Add Vi deoSamp lesToMediat media,  &rect); 

EndMedi a  Edits (media) ; 

InsertMedialntoTrackttrack, 

0, 

0, 

GetMediaDuration(media) , 
kFixl) ; 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 
Programming  summary:  "Adding  Samples  to  Media  Structures"  (V-2752) 

Related  Java  Methods 

qui ckti me . std .movi es .medi a . Medi a . endEdi ts ( ) 


Enqueue 

Inserts  a  queue  element  into  a  Windows  QHdr  (IV-2345)  structure. 

void  Enqueue  ( 

QElemPtr  qElement, 

QHdrPtr  qHeader  ) ; 

q  E 1  ement 

A  pointer  to  a  QE1  em  (IV-2344)  structure. 
qHeader 

A  pointer  to  a  QHdr  (IV-2345)  structure. 

Version  Notes 

Present  in  QuickTime  3  and  later  releases. 

Programming  Info 

C  interface  file:  OSUti  1  s .  h 


//  assemble  data 

//  track  start  time 
//  media  start  time 

//  normal  speed 
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EnterMovies 


Initializes  the  Movie  Toolbox  and  creates  a  private  storage  area  for  your  application. 
OSErr  EnterMovies  (  void  ); 

function  result  Be  sure  to  check  the  value  returned  by  this  function  before  using  any 
other  facilities  of  the  Movie  Toolbox.  See  "Error  Codes"  (IV-2663). 
Returns  noErr  if  there  is  no  error. 

Discussion 

Before  calling  any  Movie  Toolbox  functions,  you  must  use  EnterMovi  es  to  initialize 
the  toolbox.  Your  application  may  call  EnterMovi  es  multiple  times.  The  following 
code  sample  demonstrates  how  your  application  can  call  the  Gestalt  Manager  to 
determine  whether  the  Movie  Toolbox  is  installed,  using  the  selector 
gestal  tQui ckTime  ( ' qti m ' ), before  calling  EnterMovies: 

//Using  the  Gestalt  Manager  with  the  Movie  Toolbox 

#include  <Gestal tEqu . h> 

#include  <Movies.h> 

Boolean  IsQuickTimelnstal 1 ed  (void) 

1 

short  error; 
long  result; 

error  =  Gestalt  (gestal tQui ckTime ,  &result); 
return  (error  ==  noErr); 

} 

void  main  (void) 

{ 

Boolean  qtlnstalled; 


qtlnstalled  =  IsQuickTimelnstal 1 ed  (); 

} 

//  EnterMovies  coding  example 

//  See  “Discovering  QuickTime,”  page  242 
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void  Mylni tMovi eTool box  (void) 

{ 

InitGraft&qd.thePort) ; 

Ini tFonts ( ) ; 

Ini tWi ndows ( ) ; 

Ini tMenus ( ) ; 

TEInitt ) ; 

InitDialogs(NIL) ; 

EnterMovi es ( ) ; 

} 

void  main  (void) 

{ 

Mylni tMovi eTool box( ) ; 

CreateMyCoolMoviet); 

} 

Special  Considerations 

You  should  initialize  any  other  Macintosh  managers  your  application  uses  before 
calling  EnterMovi  es.  You  do  not  need  to  balance  calls  to  EnterMovi  es  with  calls  to 
Exi  tMovi  es  (1-340);  you  need  to  call  Exi  tMovi  es  only  if  you  finish  with  the  Movie 
Toolbox  long  before  your  application  is  ready  to  quit. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Initializing  the  Movie  Toolbox"  (V-2712) 

Related  Java  Methods 

qui ckti me . QTSessi on . open ( ) , 
qui cktime.QTSessi on . enterMovi es ( ) 

EqualMatrix 

Compares  two  matrices  and  returns  a  result  that  indicates  whether  the  matrices  are 
equal. 

Boolean  EqualMatrix  ( 

const  MatrlxRecord  *ml, 

const  MatrixRecord  *m2  ); 
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ml 

A  pointer  to  one  matrix  for  the  compare  operation. 
m2 

A  pointer  to  the  other  matrix  for  the  compare  operation. 
function  result  TRUE  if  the  matrices  are  equal,  FALSE  otherwise. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Matrices"  (V-2764) 

Related  Java  Methods 

qui ckti me . std . image . Matrix. equal s ( ) 


ExecuteCallBack 


Called  by  a  clock  component  when  it  determines  that  it  is  time  to  execute  a  callback 
function. 

void  ExecuteCallBack  ( 

QTCallBack  cb  ); 


cb 

Specifies  the  callback  event  for  the  operation.  Your  clock  component  obtains 
this  value  from  the  parameters  passed  to  your  Cl  ockCal  1  MeWhen  (1-91)  function. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Discussion 

Before  calling  the  application's  function,  the  ExecuteCal  1  Back  function  cancels  the 
callback  event.  In  this  manner,  the  callback  event  is  prevented  from  executing  twice 
in  succession.  It  is  up  to  the  application,  or  the  callback  function  itself,  to  reschedule 
the  callback  event. 

Special  Considerations 

Your  clock  component  should  not  release  the  memory  associated  with  the  callback 
event  at  this  time.  You  should  do  so  only  with  Cl  ockDi  sposeCal  1  Back  (1-94).  This  is 
particularly  important  when  a  callback  function  cannot  execute  at  interrupt  time, 
since  the  Movie  Toolbox  schedules  such  functions  for  invocation  at  a  later  time. 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Movie  Toolbox  Clock  Support  Functions"  (V-2869) 


ExitMovies 


Automatically  called  when  an  application  quits, 
void  ExitMovies  (  void  ); 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94). 

Discussion 

You  only  need  to  call  this  function  if  you  finish  with  the  Movie  Toolbox  long  before 
your  application  is  ready  to  quit.  When  you  call  Exi  tMovi  es,  the  Movie  Toolbox 
releases  the  private  storage  (which  may  be  significant)  that  was  allocated  when  you 
called  EnterMovi  es  (1-337).  As  a  general  rule,  your  application  seldom  uses  this 
function;  the  following  code  illustrates  an  exception: 

//  ExitMovies  coding  example 

//  See  “Discovering  QuickTime,”  page  225 

int  WINAPI  WinMain  (HINSTANCE  hlnstance,  HINSTANCE  hPrevInstance , 

LPSTR  lpCmdLine,  int  nCmdShow) 

{ 

MSG  msg; 

HANDLE  hAccelTable; 

if  (! hPrevInstance )  //  Is  there  a  previous  instance? 

if  (!( Ini tAppl i cati on ( hlnstance )) )  //  Register  window  class 

return  FALSE;  //  Report  failure 

if  (Initiali zeQTM L ( 0 )  !=  0)  {  //  Initialize  QTML 

MessageBoxt hwnd ,  "QuickTime  not  available",  //  Notify  user 

MB_0K) ; 

return  FALSE;  //  Report  failure 

}  //  end  if  (InitializeQTML(O)  !=  0) 

if  ( EnterMovi es ( )  !=  0)  {  //  Initialize  QuickTime 
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MessageBox! hwnd ,  "QuickTime  not  available",  //  Notify  user 

MB_0K) ; 


return  FALSE; 

}  //  end  if  ( EnterMovi es ( )  !=  0) 


//  Report  failure 


if  ( ! ( Ini tlnstance! hlnstance ,  nCmdShow))) 
return  FALSE; 


//  Create  main  window 
//  Report  failure 


hAccelTable  =  LoadAccel erators(hInstance,  //  Load  accelerator  table 
MAKE  I  NT RESOURCE! IDR_ACCELSIMPLESDI ) ) ; 


//  Main  message  loop 

while  (GetMessage(&msg ,  NIL,  0,  0))  //  Retrieve  next  message 

if  ( ! Transl ateAccel erator(msg . hwnd ,  //  Check  for  kbd  accelerator 

hAccelTable,  &msg))  { 

Transl ateMessage(&msg) ;  //  Convert  virtual  key  to  character 

DispatchMessage(&msg) ;  //  Send  message  to  window  procedure 

}  //  end  if  (! Transl ateAccel erator(msg . hwnd ,  hAccelTable,  &msg)) 

ExitMovies!);  //  Terminate  Toolbox 

Termi nateQTML! ) ;  //  Terminate  QuickTime 

return  msg.wParam; 

}  //  end  WinMain 

Special  Considerations 

Before  calling  Exi  tMovi  es,  be  sure  that  you  have  closed  your  connections  to  any 
components  that  use  the  Movie  Toolbox,  such  as  movie  controllers,  sequence 
grabbers,  and  so  on. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Initializing  the  Movie  Toolbox"  (V-2712) 

Related  Java  Methods 

qui ckti me . QTSessi on . exi tMovi es ( ) 
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Explto3 


Expands  3-to-l  compressed  sound  samples  to  their  original  size.  Use 
SoundConverterConvertBuffer  (III— 1862)  instead,  if  possible. 

void  Explto3  ( 
const  void 
voi  d 

unsigned  long 
StateBl ockPtr 
StateBl ockPtr 
unsigned  long 
unsigned  long 

i nBuffer 

A  pointer  to  a  buffer  of  samples  to  be  compressed. 
outBuffer 

A  pointer  to  a  buffer  where  the  samples  are  to  be  written. 

cnt 

The  number  of  samples  to  compress, 
i nState 

A  pointer  to  a  128-byte  buffer  from  which  the  input  state  of  the  algorithm  is 
read,  or  NIL.  This  buffer  should  be  filled  with  zeros  to  initialize  the  algorithm. 
outState 

A  pointer  to  a  128-byte  buffer  to  which  the  output  state  of  the  algorithm  is 
written,  or  NIL.  This  buffer  may  be  the  same  as  that  specified  by  the  instate 
parameter. 

numChannel s 

The  number  of  channels  in  the  buffer  pointed  to  by  the  i  nBuffer  parameter, 
whi chChannel 

The  channel  to  compress  when  numChannel  s  is  greater  than  1.  The  value  of  this 
parameter  must  be  in  the  range  1  to  numChannel  s. 

Discussion 

This  function  expands  cnt  packets  of  sound  stored  in  the  buffer  specified  by 
i  nBuffer  and  places  the  result  in  the  buffer  specified  by  outBuffer,  whose  size  must 
be  at  least  cnt  packets  times  2  bytes  per  packet  times  3,  or  cnt  *  6  bytes.  If 
numChannel  s  is  greater  than  1,  then  the  compressed  sound  must  be  stored  in 
interleaved  format  on  a  packet  basis. 

If  you  expand  compressed  sound  data  that  includes  multiple  sound  channels,  you 


*i nBuffer , 
*outBuffer , 
cnt , 

i nState , 
outState , 
numChannel s , 
whi chChannel  ) ; 
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retain  only  one  channel  of  sound,  which  you  specify  in  the  whichChannel  parameter. 
Thus,  if  you  use  the  Explto3  procedure  to  expand  three-channel  sound,  the  output 
buffer  will  be  the  same  size  as  the  input  buffer  since  only  one  channel  is  retained. 
To  retain  multiple  channels  of  sound  after  expansion,  you  must  call  the  Explto3 
procedure  for  each  channel  to  be  expanded  and  then  interleave  the  expanded  sound 
data  on  a  sample  basis. 

The  Explto3  procedure  expands  every  packet  of  sampled-sound  data  to  exactly  6 
bytes.  You  can  use  the  instate  and  outState  parameters  to  allow  the  MACE 
compression  routines  to  preserve  information  about  algorithms  across  calls. 
Alternatively,  you  may  pass  N I L  state  buffers  and  let  the  Sound  Manager  allocate 
the  buffers  internally. 

Special  Considerations 

Because  the  Explto3  procedure  might  allocate  memory,  you  should  not  call  it  at 
interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  4.  Macintosh  Note:  Not  available  in  CarbonLib,  but 
available  if  InterfaceLib  7.1  or  later  is  installed. 

Programming  Info 

C  interface  file:  Sound .  h 


Explto6 


Expands  6-to-l  compressed  sound  samples  to  their  original  size.  Use 
SoundConverterConvertBuf f er  (III— 1862)  instead,  if  possible. 

void  Explto6  ( 
const  void 
void 

unsigned  long 
StateBl ockPtr 
StateBl ockPtr 
unsigned  long 
unsigned  long 

i nBuf fer 

A  pointer  to  a  buffer  of  samples  to  be  compressed. 
outBuf fer 

A  pointer  to  a  buffer  where  the  samples  are  to  be  written. 


*i nBuf fer , 
*outBuf fer , 
cnt , 

i nState , 
outState , 
numChannel s , 
whichChannel  ); 
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cnt 

The  number  of  samples  to  compress, 
i nState 

A  pointer  to  a  128-byte  buffer  from  which  the  input  state  of  the  algorithm  is 
read,  or  NIL.  This  buffer  should  be  filled  with  zeros  to  initialize  the  algorithm. 

outState 

A  pointer  to  a  128-byte  buffer  to  which  the  output  state  of  the  algorithm  is 
written,  or  N I L.  This  buffer  may  be  the  same  as  that  specified  by  the  instate 
parameter. 
numChannel s 

The  number  of  channels  in  the  buffer  pointed  to  by  the  i  nBuf  f  er  parameter, 
whi chChannel 

The  channel  to  compress  when  numChannel  s  is  greater  than  1.  The  value  of  this 
parameter  must  be  in  the  range  1  to  numChannel  s. 

Discussion 

This  function  expands  cnt  packets  of  sound  stored  in  the  buffer  specified  by 
i  n  Buffer  and  places  the  result  in  the  buffer  specified  by  out  Buffer,  whose  size  must 
be  at  least  cnt  packets  times  1  byte  per  packet  times  6,  or  cnt  *  6  bytes.  If 
numChannel  s  is  greater  than  1,  then  the  compressed  sound  must  be  stored  in 
interleaved  format  on  a  packet  basis.  The  Exp  lto6  procedure  works  just  like  Explto3 
(1-342),  but  expands  1-byte  packets  rather  than  2-byte  packets. 

Special  Considerations 

Because  Explto6  might  allocate  memory,  you  should  not  call  it  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  4.  Macintosh  Note:  Not  available  in  CarbonLib,  but 
available  if  InterfaceLib  7.1  or  later  is  installed. 

Programming  Info 

C  interface  file:  Sound .  h 


F 


FCompressImage 

Compresses  a  single-frame  image  that  is  currently  stored  as  a  pixel  map  structure, 
with  added  control  over  the  compression  process. 
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OSErr  FCompressImage  ( 

Pi xMapHandl e 
const  Rect 
short 
CodecQ 
CodecType 

Comp res sorComponent 
CTabHandl e 
CodecFl  ags 
1  ong 

ICMFlushProcRecordPtr 
ICMProgressProcRecordPtr 
ImageDescri pti onHandl e 
Ptr 


src, 

*srcRect, 
col orDepth , 
quality, 
cType , 
codec , 
ctabl e , 
fl ags , 
but ferSi ze , 
f 1 ushProc , 
progressProc, 
desc , 
data  ); 


src 

A  handle  to  the  image  to  be  compressed.  The  image  must  be  stored  in  a  pixel 
map  structure. 

srcRect 

A  pointer  to  a  rectangle  defining  the  portion  of  the  image  to  compress, 
col orDepth 

The  depth  at  which  the  image  is  likely  to  be  viewed.  Compressors  may  use  this 
as  an  indication  of  the  color  or  grayscale  resolution  of  the  compressed  image.  If 
you  set  this  parameter  to  0,  the  Image  Compression  Manager  determines  the 
appropriate  value  for  the  source  image.  Values  of  1,  2, 4, 8, 16,  24,  and  32 
indicate  the  number  of  bits  per  pixel  for  color  images.  Values  of  34, 36,  and  40 
indicate  2-bit,  4-bit,  and  8-bit  grayscale,  respectively,  for  grayscale  images.  Your 
program  can  determine  which  depths  are  supported  by  a  given  compressor  by 
examining  the  compressor  information  structure  returned  by  the  GetCodecInfo 
(1-385)  function. 

quality 

A  constant  (see  below)  that  defines  the  desired  compressed  image  quality. 
cType 

A  compressor  type.  You  must  set  this  parameter  to  a  valid  compressor  type 
constant, 
codec 

A  compressor  identifier.  Specify  a  particular  compressor  by  setting  this 
parameter  to  its  compressor  identifier.  Alternatively,  you  may  use  a  special 
identifier  (see  below).  Specifying  a  component  instance  may  be  useful  if  you 
have  previously  set  some  parameter  on  a  specific  instance  of  a  codec  field  and 
want  to  make  sure  that  the  specified  instance  is  used  for  that  operation. 
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ctabl e 

A  handle  to  a  custom  color  lookup  table.  Your  program  may  use  this 
parameter  to  indicate  a  custom  color  lookup  table  to  be  used  with  this  image.  If 
the  value  of  the  colorDepth  parameter  is  less  than  or  equal  to  8  and  the  custom 
color  lookup  table  is  different  from  that  of  the  source  pixel  map  (that  is,  the 
ctSeed  field  values  differ  in  the  two  pixel  maps),  the  compressor  remaps  the 
colors  of  the  image  to  the  custom  colors.  If  you  set  the  colorDepth  parameter  to 
16, 24,  or  32,  the  compressor  stores  the  custom  color  table  with  the  compressed 
image.  The  compressor  may  use  the  table  to  specify  the  best  colors  to  use  when 
displaying  the  image  at  lower  bit  depths.  The  compressor  ignores  the  ctabl  e 
parameter  when  col  or  Depth  is  set  to  33, 34,  36,  or  40.  If  you  set  this  parameter 
to  NIL,  the  compressor  uses  the  color  lookup  table  from  the  source  pixel  map. 
fl  ags 

Contains  a  flag  (see  below)  that  indicates  whether  or  not  the  image  was 
previously  compressed. 
bufferSi ze 

The  size  of  the  buffer  to  be  used  by  the  data-unloading  function  specified  by  the 
flushProc  parameter.  If  you  have  not  specified  a  data-unloading  function,  set 
this  parameter  to  0. 
f 1 ushProc 

Points  to  an  ICMDataProc  (III— 2090)  data-unloading  callback.  If  there  is  not 
enough  memory  to  store  the  compressed  image,  the  compressor  calls  a  function 
you  provide  that  unloads  some  of  the  compressed  data.  If  you  have  not 
provided  a  data-unloading  callback,  set  this  parameter  to  N I L.  In  this  case,  the 
compressor  writes  the  entire  compressed  image  into  the  memory  location 
specified  by  the  data  parameter. 
progressProc 

Points  to  an  ICMProgressProc  (III— 2093)  progress  callback.  During  the 
compression  operation,  the  compressor  may  occasionally  call  a  function  you 
provide  in  order  to  report  its  progress.  If  you  have  not  provided  a  progress 
callback,  set  this  parameter  to  NIL.  If  you  pass  a  value  of  -1,  QuickTime 
provides  a  standard  progress  function. 

desc 

A  handle  that  is  to  receive  a  formatted  ImageDescri  pti  on  (IV-2285)  structure. 
The  Image  Compression  Manager  resizes  this  handle  for  the  returned 
ImageDescri  pti  on  (IV-2285)  structure.  Your  application  should  store  this  image 
description  with  the  compressed  image  data. 
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data 

Points  to  a  location  to  receive  the  compressed  image  data.  It  is  your  program's 
responsibility  to  make  sure  that  this  location  can  receive  at  least  as  much  data 
as  indicated  by  the  GetMaxCompressi  onSi  ze  (1-420)  function.  If  there  is  not 
sufficient  memory  to  store  the  compressed  image,  you  may  choose  to  write  the 
compressed  data  to  mass  storage  during  the  compression  operation.  Use  the 
flushProc  parameter  to  identify  your  data-unloading  function  to  the 
compressor.  This  pointer  must  contain  a  32-bit  clean  address.  The  Image 
Compression  Manager  places  the  actual  size  of  the  compressed  image  into  the 
dataSi  ze  field  of  the  ImageDescri  pti  on  (IV-2285)  structure  referenced  by  the 
desc  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

quality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 
codecNormal Quality 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 

codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field, 
codec Los  si essQual  i  ty 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

codec  Constants 

anyCodec 

The  first  compressor  or  decompressor  of  the  specified  type. 
bestSpeedCodec 

The  fastest  compressor  or  decompressor  of  the  specified  type. 
bestFi del i tyCodec 

The  most  accurate  compressor  or  decompressor  of  the  specified  type. 
bestCompressi onCodec 

The  compressor  that  produces  the  smallest  resulting  data. 
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flags  Constants 

codec  FI  a gWas Compressed 

Indicates  to  the  compressor  that  the  image  to  be  compressed  has  been 
compressed  before.  This  information  may  be  useful  to  compressors  that  can 
compensate  for  the  image  degradation  that  may  otherwise  result  from  repeated 
compression  and  decompression  of  the  same  image.  Set  this  flag  to  1  to  indicate 
that  the  image  was  previously  compressed.  Set  this  flag  to  0  if  the  image  was 
not  previously  compressed. 

Discussion 

This  function  acts  like  Compress  Image  (1-113),  but  gives  your  application  additional 
control  over  the  parameters  that  guide  the  compression  operation. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Pixel  Maps"  (V-2789) 

Related  Java  Methods 

qui ckti me . std . i mage . QT Image . f Compress ( ) 


FCompressPicture 

Compresses  a  single-frame  image  stored  as  a  picture  structure  and  places  the  result 
in  another  picture,  with  added  control  over  the  compression  process. 

OSErr  FCompressPicture  ( 

Pi cHandl e 
Pi cHandl e 
short 

CTabHandl e 
CodecQ 
short 
short 

ICMProgressProcRecordPtr 
CodecType 

CompressorComponent 
srcPi cture 

A  handle  to  the  source  image,  stored  as  a  picture. 


srcPi cture , 
dstPi cture , 
col orDepth , 
ctabl e , 
qual i ty , 
doDi ther , 
compressAgai n , 
progressProc , 
cType , 
codec  ) ; 
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dstPi cture 

A  handle  to  the  destination  for  the  compressed  image.  The  compressor  resizes 
this  handle  for  the  result  data, 
col orDepth 

The  depth  at  which  the  image  is  to  be  compressed.  If  you  set  this  parameter  to 
0,  the  Image  Compression  Manager  determines  the  appropriate  value  for  the 
source  image.  Values  of  1,  2, 4, 8, 16, 24,  and  32  indicate  the  number  of  bits  per 
pixel  for  color  images.  Values  of  34,  36,  and  40  indicate  2-bit,  4-bit,  and  8-bit 
grayscale,  respectively,  for  grayscale  images.  Your  program  can  determine 
which  depths  are  supported  by  a  given  compressor  by  examining  the 
compressor  information  structure  returned  by  the  GetCodecInfo  (1-385) 
function. 

ctabl e 

A  handle  to  a  custom  color  lookup  table.  Your  program  may  use  this 
parameter  to  indicate  a  custom  color  lookup  table  to  be  used  with  this  image.  If 
the  value  of  the  col  orDepth  parameter  is  less  than  or  equal  to  8  and  the  custom 
color  lookup  table  is  different  from  that  of  the  source  pixel  map  (that  is,  the 
ctSeed  field  values  differ  in  the  two  pixel  maps),  the  compressor  remaps  the 
colors  of  the  image  to  the  custom  colors.  If  you  set  the  col  orDepth  parameter  to 
16, 24,  or  32,  the  compressor  stores  the  custom  color  table  with  the  compressed 
image.  The  compressor  may  use  the  table  to  specify  the  best  colors  to  use  when 
displaying  the  image  at  lower  bit  depths.  The  compressor  ignores  the  ctabl  e 
parameter  when  col  orDepth  is  set  to  33,  34, 36,  or  40.  If  you  set  this  parameter 
to  NIL,  the  compressor  uses  the  color  lookup  table  from  the  source  pixel  map. 
quality 

A  constant  that  defines  the  desired  compressed  image  quality. 
doDi ther 

A  constant  (see  below)  that  indicates  whether  to  dither  the  image.  Use  this 
parameter  to  indicate  whether  you  want  the  image  to  be  dithered  when  it  is 
displayed  on  a  lower-resolution  screen. 

compressAgai n 

Indicates  whether  to  recompress  compressed  image  data  in  the  picture.  Use  this 
parameter  to  control  whether  any  compressed  image  data  that  is  in  the  source 
picture  should  be  decompressed  and  then  recompressed  using  the  current 
parameters.  Set  the  value  of  this  parameter  to  TRU  E  to  recompress  such  data.  Set 
the  value  of  the  parameter  to  FALSE  to  leave  the  data  as  it  is.  Note  that 
recompressing  the  data  may  have  undesirable  side  effects,  including  image 
quality  degradation. 
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progressProc 

Points  to  an  ICMProgressProc  (III— 2093)  callback.  During  the  compression 
operation,  the  compressor  may  occasionally  call  a  function  you  provide  in 
order  to  report  its  progress.  If  you  have  not  provided  a  progress  callback,  set 
this  parameter  to  N I L.  If  you  pass  a  value  of  -1,  QuickTime  provides  a  standard 

progress  function. 

cType 

A  compressor  type.  You  must  set  this  parameter  to  a  valid  compressor  type 
constant;  see  "Codec  Identifiers"  (IV-2655).  If  the  value  passed  in  is  0,  or  '  raw  ' , 
the  resulting  picture  is  not  compressed  and  does  not  require  QuickTime  to  be 
displayed. 

codec 

A  compressor  identifier.  Specify  a  particular  compressor  by  setting  this 
parameter  to  its  compressor  identifier.  Alternatively,  you  may  use  a  special 
identifier  (see  below). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

quality  Constants 

codecMi nQual 1 ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 

codec Normal  Qua  1 i ty 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 
codecMaxQual i ty 

Maximum  standard  value  for  a  CodecQ  field. 
codecLosslessQuality 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

doDither  Constants 

defaul tDi ther 

The  dithering  in  the  source  file  is  to  be  respected. 
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f orceDi ther 

The  specified  image  should  be  dithered  whether  the  source  uses  dithering  or 
not. 

suppressDi ther 

Dithering  should  not  be  used  in  any  case.  The  ability  to  suppress  dithering  can 
be  useful  if,  for  example,  you  have  a  32-bit,  color  JPEG  image  drawn  into  an 
8-bit  buffer  with  a  custom  color  table  from  the  image.  In  that  case,  dithering 
would  not  be  necessary  and  probably  not  desirable,  particularly  if  the  buffer 
were  to  be  compressed  with  the  graphics  compressor. 

codec  Constants 

anyCodec 

The  first  compressor  or  decompressor  of  the  specified  type. 
bestSpeedCodec 

The  fastest  compressor  or  decompressor  of  the  specified  type. 
bestFi del i tyCodec 

The  most  accurate  compressor  or  decompressor  of  the  specified  type. 
bestCompressi onCodec 

The  compressor  that  produces  the  smallest  resulting  data. 

Discussion 

If  a  picture  with  multiple  pixel  maps  and  other  graphical  objects  is  passed,  the  pixel 
maps  will  be  compressed  individually  and  the  other  graphic  objects  will  not  be 
affected.  FCompressPi  cture  compresses  only  image  data.  Any  other  types  of  data  in 
the  picture,  such  as  text,  graphics  primitives,  and  previously  compressed  images, 
are  not  modified  in  any  way  and  are  passed  through  to  the  destination  picture.  This 
function  supports  parameters  governing  image  quality,  compressor  type,  image 
depth,  custom  color  tables,  and  dithering. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Pictures  and  PICT  Files"  (V-2790) 

Related  Java  Methods 

qui ckti me . qd . Pi ct . fCompress ( ) 
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FCompressPictureFile 


Compresses  a  single-frame  image  stored  as  a  picture  file  and  places  the  result  in 
another  picture  file,  with  added  control  over  the  compression  process. 

OSErr  FCompressPictureFile  ( 
short 
short 
short 

CTabHandl e 
CodecQ 
short 
short 

ICMProgressProcRecordPtr 
CodecType 

CompressorComponent 
srcRefNum 

A  file  reference  number  for  the  source  PICT  file. 
dstRef Num 

A  file  reference  number  for  the  destination  PICT  file.  Note  that  the  compressor 
overwrites  the  contents  of  the  file  referred  to  by  dstRef  Num.  You  must  open  this 
file  with  write  permissions.  The  destination  file  may  be  the  same  as  the  source 
file  specified  by  the  srcRefNum  parameter. 

col orDepth 

The  depth  at  which  the  image  is  to  be  compressed.  If  you  set  this  parameter  to 
0,  the  Image  Compression  Manager  determines  the  appropriate  value  for  the 
source  image.  Values  of  1, 2, 4,  8, 16, 24,  and  32  indicate  the  number  of  bits  per 
pixel  for  color  images.  Values  of  34,  36,  and  40  indicate  2-bit,  4-bit,  and  8-bit 
grayscale,  respectively,  for  grayscale  images.  Your  program  can  determine 
which  depths  are  supported  by  a  given  compressor  by  examining  the 
compressor  capability  structure  returned  by  the  GetCodecInfo  (1-385)  function, 
ctabl e 

A  handle  to  a  custom  color  lookup  table.  Your  program  may  use  this 
parameter  to  indicate  a  custom  color  lookup  table  to  be  used  with  this  image.  If 
the  value  of  the  col  orDepth  parameter  is  less  than  or  equal  to  8  and  the  custom 
color  lookup  table  is  different  from  that  of  the  source  pixel  map  (that  is,  the 
ctSeed  field  values  differ  in  the  two  pixel  maps),  the  compressor  remaps  the 
colors  of  the  image  to  the  custom  colors.  If  you  set  the  col  orDepth  parameter  to 
16, 24,  or  32,  the  compressor  stores  the  custom  color  table  with  the  compressed 
image.  The  compressor  may  use  the  table  to  specify  the  best  colors  to  use  when 
displaying  the  image  at  lower  bit  depths.  The  compressor  ignores  the  ctabl  e 


srcRefNum, 
dstRef Num , 
col orDepth , 
ctabl e , 
qual i ty , 
doDi ther , 
compressAgai n , 
progressProc , 
cType , 
codec  ) ; 
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parameter  when  colorDepth  is  set  to  33,  34, 36,  or  40.  If  you  set  this  parameter 
to  NIL,  the  compressor  uses  the  color  lookup  table  from  the  source  pixel  map. 

quality 

A  constant  (see  below)  that  defines  the  desired  compressed  image  quality. 
doDi ther 

Indicates  whether  to  dither  the  image.  Use  this  parameter  to  indicate  whether 
you  want  the  image  to  be  dithered  when  it  is  displayed  on  a  lower-resolution 
screen.  The  following  constants  are  available: 
compressAgai n 

Indicates  whether  to  recompress  compressed  image  data  in  the  picture.  Use  this 
parameter  to  control  whether  any  compressed  image  data  that  is  in  the  source 
picture  should  be  decompressed  and  then  recompressed  using  the  current 
parameters.  Set  the  value  of  this  parameter  to  TRU  E  to  recompress  such  data.  Set 
the  value  of  this  parameter  to  FALSE  to  leave  the  data  as  it  is.  Note  that 
recompressing  the  data  may  have  undesirable  side  effects,  including  image 
quality  degradation. 

progressProc 

Points  to  an  ICMProgressProc  (III— 2093)  callback.  During  the  compression 
operation,  the  compressor  may  occasionally  call  a  function  you  provide  in 
order  to  report  its  progress. 

cType 

A  compressor  type.  You  must  set  this  parameter  to  a  valid  compressor  type 
constant, 
codec 

A  compressor  identifier.  Specify  a  particular  compressor  by  setting  this 
parameter  to  its  compressor  identifier.  Alternatively,  you  may  use  a  special 
identifier  (see  below). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

quality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 
codecNormal Quality 

Image  reproduction  of  normal  quality. 
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codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 
codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field, 
codec LosslessQuality 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

doDither  Constants 

defaul tDi ther 

The  dithering  in  the  source  file  is  to  be  respected. 
forceDi ther 

The  specified  image  should  be  dithered  whether  the  source  uses  dithering  or 
not. 

suppressDi ther 

Dithering  should  not  be  used  in  any  case.  The  ability  to  suppress  dithering  can 
be  useful  if,  for  example,  you  have  a  32-bit,  color  JPEG  image  drawn  into  an 
8-bit  buffer  with  a  custom  color  table  from  the  image.  In  that  case,  dithering 
would  not  be  necessary  and  probably  not  desirable,  particularly  if  the  buffer 
were  to  be  compressed  with  the  graphics  compressor. 

codec  Constants 

anyCodec 

The  first  compressor  or  decompressor  of  the  specified  type. 
bestSpeedCodec 

The  fastest  compressor  or  decompressor  of  the  specified  type. 
bestFi del i tyCodec 

The  most  accurate  compressor  or  decompressor  of  the  specified  type, 
best Comp  res si  on Codec 

The  compressor  that  produces  the  smallest  resulting  data. 

Discussion 

This  function  compresses  only  image  data.  Any  other  types  of  data  in  the  file,  such 
as  text,  graphics  primitives,  and  previously  compressed  images,  are  not  modified  in 
any  way  and  are  passed  through  to  the  destination  picture  file.  This  function 
supports  parameters  governing  image  quality,  compressor  type,  image  depth, 
custom  color  tables,  and  dithering. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Pictures  and  PICT  Files"  (V-2790) 


FDecompressImage 


Decompresses  a  single-frame  image  into  a  pixel  map  structure,  with  added  control 
over  the  decompression  process. 


OSErr  FDecompressImage  ( 

Ptr 

ImageDescri pti on Hand! e 

Pi xMapHandl e 

const  Rect 

Matri xRecordPtr 

short 

RgnHandl e 

Pi xMapHandl e 

const  Rect 

CodecQ 

Decomp res sorComponent 
1  ong 

ICMDataProc Record Ptr 
ICMProgressProc Record Ptr 


data , 
desc , 
dst , 

*srcRect, 

matrix, 

mode , 

mask, 

matte , 

*matteRect , 

accuracy , 

codec , 

but ferSi ze , 

dataProc, 

progressProc  ); 


data 

Points  to  the  compressed  image  data.  If  the  entire  compressed  image  cannot  be 
stored  at  this  location,  your  application  may  provide  a  data-loading  function 
(see  the  discussion  of  the  dataProc  parameter  to  this  function).  This  pointer 
must  contain  a  32-bit  clean  address. 

desc 

A  handle  to  the  ImageDescri  pti  on  (IV-2285)  structure  that  describes  the 
compressed  image. 

dst 

A  handle  to  the  pixel  map  where  the  decompressed  image  is  to  be  displayed. 
Set  the  current  graphics  port  to  the  port  that  contains  this  pixel  map. 

srcRect 

A  pointer  to  a  rectangle  defining  the  portion  of  the  image  to  decompress.  This 
rectangle  must  lie  within  the  boundary  rectangle  of  the  compressed  image, 
which  is  defined  by  (00)  and  ( (**desc)  .width(**desc)  .height).  If  you  want  to 
decompress  the  entire  source  image,  set  this  parameter  to  N I L.  If  the  parameter 
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is  NIL,  the  rectangle  is  set  to  the  rectangle  structure  of  the  ImageDescription 
(IV-2285)  structure. 

matrix 

Points  to  a  matrix  structure  that  specifies  how  to  transform  the  image  during 
decompression.  You  can  use  the  matrix  structure  to  translate  or  scale  the  image 
during  decompression.  If  you  do  not  want  to  apply  such  effects,  set  the  matrix 
parameter  to  NIL. 

mode 

The  transfer  mode  for  the  operation;  see  "Graphics  Transfer  Modes"  (IV-2670). 

mask 

A  handle  to  a  clipping  region  in  the  destination  coordinate  system.  If  specified, 
the  decompressor  applies  this  mask  to  the  destination  image.  If  you  do  not 
want  to  mask  bits  in  the  destination,  set  this  parameter  to  NIL. 

matte 

A  handle  to  a  pixel  map  that  contains  a  blend  matte.  You  can  use  the  blend 
matte  to  cause  the  decompressed  image  to  be  blended  into  the  destination  pixel 
map.  The  matte  can  be  defined  at  any  supported  pixel  depth;  the  matte  depth 
need  not  correspond  to  the  source  or  destination  depths.  However,  the  matte 
must  be  in  the  coordinate  system  of  the  source  image.  If  you  do  not  want  to 
apply  a  blend  matte,  set  this  parameter  to  N I L. 

matteRect 

A  pointer  to  a  rectangle  defining  a  portion  of  the  blend  matte  to  apply.  If  you 
do  not  want  to  use  the  entire  matte  referred  to  by  the  matte  parameter,  use  this 
parameter  to  specify  a  rectangle  within  that  matte.  If  specified,  this  rectangle 
must  be  the  same  size  as  the  rectangle  specified  by  the  s  rcRect  parameter.  If 
you  want  to  use  the  entire  matte,  or  if  you  are  not  providing  a  blend  matte,  set 
this  parameter  to  NIL. 
accuracy 

A  constant  (see  below)  that  defines  the  desired  compression  accuracy.  For  a 
good  display  of  still  images,  you  should  specify  at  least  codecHi  ghQual  1  ty. 

codec 

A  decompressor  identifier.  Specify  a  particular  decompressor  by  setting  this 
parameter  to  its  identifier.  Alternatively,  you  may  use  a  special  identifier  (see 
below).  Specifying  a  component  instance  maybe  useful  if  you  have  previously 
set  some  parameter  on  a  specific  instance  of  a  codec  field  and  want  to  make  sure 
that  the  specified  instance  is  used  for  that  operation. 
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buf f erSi ze 

The  size  of  the  buffer  to  be  used  by  the  data-loading  function  specified  by  the 
dataProc  parameter.  If  you  have  not  specified  a  data-loading  function,  set  this 
parameter  to  0. 
dataProc 

Points  to  an  ICMDataProc  (III— 2090)  data-loading  callback.  If  there  is  not  enough 
memory  to  store  the  compressed  image,  the  compressor  calls  a  function  you 
provide  that  loads  more  compressed  data.  If  you  have  not  provided  a 
data-unloading  callback,  set  this  parameter  to  N I L.  In  this  case,  the  compressor 
expects  that  the  entire  compressed  image  is  in  the  memory  location  specified  by 
the  data  parameter. 

progressProc 

Points  to  an  ICMProgressProc  (III— 2093)  progress  callback.  During  the 
compression  operation,  the  compressor  may  occasionally  call  a  function  you 
provide  in  order  to  report  its  progress.  If  you  have  not  provided  a  progress 
callback,  set  this  parameter  to  NIL.  If  you  pass  a  value  of  -1,  QuickTime 
provides  a  standard  progress  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

accuracy  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 

codecNormal Quality 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 
codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field, 
codec Los  si essQual  i  ty 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

codec  Constants 

anyCodec 

The  first  compressor  or  decompressor  of  the  specified  type. 
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bestSpeedCodec 

The  fastest  compressor  or  decompressor  of  the  specified  type. 
bestFi del i tyCodec 

The  most  accurate  compressor  or  decompressor  of  the  specified  type. 

Discussion 

This  function  gives  your  application  greater  control  over  the  parameters  that  guide 
the  decompression  operation.  If  you  find  that  you  do  not  need  this  level  of  control, 
use  Decompress  Image  (1-235).  Note  that  this  function  is  invoked  through  the  StdPi  x 
(III— 1912)  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Pixel  Maps"  (V-2789) 

Related  Java  Methods 

qui ckti me . std . i mage . QT Image . f Decompress ( ) 


FindCodec 


Determines  which  of  the  installed  compressors  or  decompressors  has  been  chosen 
to  field  requests  made  by  using  one  of  the  special  compressor  identifiers. 

OSErr  FindCodec  ( 

CodecType 
CodecComponent 
CompressorComponent 
Decomp ressorComponent 

cType 

You  must  set  this  parameter  to  a  valid  compressor  type  constant;  see  "Codec 
Identifiers"  (IV-2655). 
specCodec 

A  special  codec  identifier  value  (see  below), 
compressor 

A  pointer  to  a  field  to  receive  the  identifier  for  the  compressor  component.  The 
Image  Compression  Manager  returns  the  identifier  of  the  compressor  that 
meets  the  special  characteristics  you  specify  in  the  specCodec  parameter.  Note 
that  this  identifier  may  differ  from  the  val  ue  of  the  field  referred  to  by  the 
decompressor  field.  The  Image  Compression  Manager  sets  this  field  to  0  if  it 


cType , 
specCodec , 
Compressor , 
*decompressor  ) ; 
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cannot  find  a  suitable  compressor  component.  Set  this  parameter  to  N I L  if  you 
do  not  want  this  information. 

decompressor 

A  pointer  to  a  field  to  receive  the  identifier  for  the  decompressor  component. 
The  Image  Compression  Manager  returns  the  identifier  of  the  decompressor 
that  meets  the  special  characteristics  you  specify  in  the  specCodec  parameter. 
Note  that  this  identifier  may  differ  from  the  val  ue  of  the  field  referred  to  by  the 
compressor  field.  The  Image  Compression  Manager  sets  this  field  to  0  if  it 
cannot  find  a  suitable  decompressor  component.  Set  this  parameter  to  N I L  if 
you  do  not  want  this  information. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

specCodec  Constants 

anyCodec 

The  first  compressor  or  decompressor  of  the  specified  type. 
bestSpeedCodec 

The  fastest  compressor  or  decompressor  of  the  specified  type. 
bestFi del i tyCodec 

The  most  accurate  compressor  or  decompressor  of  the  specified  type. 
bestCompressi onCodec 

The  compressor  that  produces  the  smallest  resulting  data. 

Discussion 

Some  Image  Compression  Manager  functions  allow  you  to  specify  a  particular 
compressor  component  by  its  identifier.  For  example,  you  may  use  the  codec 
parameter  to  CompressSequenceBegi  n  (1-119)  to  specify  a  particular  compressor  to  do 
the  compression.  The  Image  Compression  Manager  also  supports  several  special 
identifiers  (see  specCodec  Constants,  above)  that  allow  you  to  exert  some  control 
over  the  component  for  a  given  action  without  having  to  know  its  identifier. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Getting  Information  About  Compressor  Components" 
(V-2788) 

Related  Java  Methods 

qui ckti me . std . image . Decompressor . f i nd Codec! ) , 
qui ckti me . std . image . Compressor . f i nd Codec ( ) 
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See  Also 

See  GetCodecNameLi  st  (1-386)  for  information  on  retrieving  codec  identifiers. 


FindNextComponent 


Returns  the  component  identifier  for  the  next  registered  component  that  meets  the 
selection  criteria  specified  by  an  application. 

Component  FindNextComponent  ( 

Component  aComponent, 

ComponentDescri pti on  *looking  ); 


aComponent 

The  starting  point  for  the  search.  Set  this  field  to  0  to  to  start  the  search  at  the 
beginning  of  the  component  list.  If  you  are  continuing  a  search,  you  can  specify 
a  component  identifier  previously  returned  by  FindNextComponent.  The  function 
then  searches  the  remaining  components. 

1  ooki  ng 

A  ComponentDescri  pti  on  (IV-2212)  structure.  Your  application  specifies  the 
criteria  for  the  component  search  in  the  fields  of  this  structure.  The  Component 
Manager  ignores  fields  that  are  set  to  0.  For  example,  if  you  set  all  the  fields  to 
0,  all  components  meet  the  search  criteria.  In  this  case,  your  application  can 
retrieve  information  about  all  of  the  components  that  are  registered  in  the 
system  by  repeatedly  calling  FindNextComponent  and  GetComponentlnfo  (1-389) 
until  the  search  is  complete.  Similarly,  if  you  set  all  fields  to  0  except  for  the 
componentManuf  acturer  field,  the  Component  Manager  searches  all  registered 
components  for  a  component  supplied  by  the  manufacturer  you  specify.  Note 
that  the  Fi  ndNextComponent  function  does  not  modify  the  contents  of  the 
ComponentDescri  pti  on  structure  you  supply.  To  retrieve  detailed  information 
about  a  component,  you  need  to  use  the  GetComponentlnfo  function  to  get  the 
component  description  record  for  each  returned  component. 


Discussion 


function  result  The  component  identifier  of  a  component  that  meets  the  search 
criteria,  or  0  if  there  are  no  more  matching  components. 

This  function  returns  the  component  identifier  of  a  component  that  meets  the  search 
criteria.  It  returns  a  function  result  of  0  when  there  are  no  more  matching 
components.  The  following  code  sample  illustrates  its  use: 


//  FindNextComponent  coding  example 
//  See  “Discovering  QuickTime,”  page  281 
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FixExp2 


void  f i ndGraphi csExporterComponents ( ) 

{ 

ComponentDescri pti on  cd; 

Component  c  =  0; 

cd . componentType  =  GraphicsExporterComponentType; 
cd . componentSubType  =  0; 
cd . componentManuf acturer  =  0; 
cd . componentFl ags  =  0; 

cd . componentFl agsMask  =  graphicsExporterlsBaseExporter; 


} 


while((c  =  Fi ndNextComponent(&cd ,  c))  !=  0)  { 

...  //  add  component  c  to  the  list. 


} 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Component  Functions  Used  By  Applications"  (V-2781) 

Related  Java  Methods 

qui cktime . std . comp . Component  I  den ti f i er . f  i  nd( ) 


FixExp2 


Undocumented 

Fixed  FixExp2  ( 

Fixed  src  ); 


src 

A  fixed  integer. 
function  result  Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 
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FixLog2 


FixLog2 


Undocumented 

Fixed  FixLog2  ( 

Fixed  src  )  ; 


src 

A  fixed  integer. 
function  result  Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


FixMulDiv 


Undocumented 

Fixed  FixMulDiv  ( 

Fixed  src, 

Fi xed  mul  , 

Fi  xed  di  vi  sor  ) ; 

src 

Undocumented 


mul 

Undocumented 
di vi sor 

Undocumented 

function  result  Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 
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FixPow 


FixPow 


Undocumented 

Fixed  FixPow  ( 

Fixed  base. 

Fixed  exp  ); 


base 

Undocumented 

exp 

Undocumented 

function  result  Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


FlashMediaDoButtonActions 


Performs  actions  attached  to  a  specified  button. 

ComponentResul t  FlashMediaDoButtonActions  ( 
Medi a  H  a  n  d 1 er  mh, 
char  *path, 

long  buttonID, 

long  transition  ); 


mh 

The  Toolbox's  connection  to  your  derived  Flash  media  handler.  You  can  obtain 
this  reference  from  GetMediaHandler  (1-432). 

path 

Specifies  the  path  to  the  button  to  which  the  action  is  attached. 
buttonID 

The  ID  of  the  button, 
transi ti on 

Sends  a  mouse  transition  message  to  the  object  and  whatever  Flash  actions  are 
associated  with  that  transition  on  the  object  that  should  be  performed.  The 
values  are  specific  Flash  transition  constants. 
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FlashMediaFrameLabelToMovieTime 


function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Movi  es .  h 


FlashMediaFrameLabelT  oMovieT  ime 


Undocumented 

ComponentResul t  FlashMediaFrameLabelToMovieTime  ( 
MediaHandler  mh, 

Ptr  theLabel  , 

TimeValue  *movieTime  ); 


mh 

The  Toolbox's  connection  to  your  derived  Flash  media  handler.  You  can  obtain 
this  reference  from  GetMediaHandler  (1-432). 

theLabel 

Undocumented 

movieTime 

Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es .  h 


FlashMediaFrameNumberT  oMovieT  ime 

Undocumented 

ComponentResul t  FlashMediaFrameNumberToMovieTime  ( 
MediaHandler  mh, 
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FlashMediaGetDisplayedFrameNumber 


long  fl ashFrameNumber, 

TlmeValue  *movieTime  ); 


mh 

The  Toolbox's  connection  to  your  derived  Flash  media  handler.  You  can  obtain 
this  reference  from  GetMediaHandler  (1-432). 
fl ashFrameNumber 
Undocumented 
movi eT i me 

Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


FlashMediaGetDisplayedFrameNumber 


Undocumented 

ComponentResul t  Fl ashMedi aGetDi spl ayedFrameNumber  ( 
Medi a  H  a  n  d 1 er  mh, 

long  *fl ashFrameNumber  ); 


mh 

The  Toolbox's  connection  to  your  derived  Flash  media  handler.  You  can  obtain 
this  reference  from  GetMediaHandler  (1-432). 

fl ashFrameNumber 
Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4. 
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FlashMediaGetFlashVariable 


Programming  Info 

C  interface  file:  Movi  es .  h 


FlashMediaGetFlash  V  ariable 


Gets  the  value  of  a  specified  Flash  action  variable. 


ComponentResul 
Medi aHandl 
char 
char 
Handl e 


t  FlashMediaGetFlashVariable 
er  mh , 

*path , 

*name , 

*theVariableCStr ingOut 


( 


) : 


mh 

The  Toolbox's  connection  to  your  derived  Flash  media  handler.  You  can  obtain 
this  reference  from  GetMedi  aHandl  er  (1-432). 

path 

Specifies  the  path  to  the  Flash  button  to  which  the  variable  is  attached. 

name 

Specifies  the  name  of  the  Flash  variable. 
theVari abl eCStri ngOut 

A  handle  to  the  value  of  the  Flash  variable  as  a  C  string. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Movi  es .  h 


FlashMediaGetRefConBounds 


Undocumented 

ComponentResul t  FlashMediaGetRefConBounds  ( 
MediaHandler  mh, 

long  refCon, 

long  *left, 

long  *top, 
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FlashMediaGetRefConID 


long  *right, 

long  *bottom  ); 

mh 

The  Toolbox's  connection  to  your  derived  Flash  media  handler.  You  can  obtain 
this  reference  from  GetMediaHandler  (1-432). 
refCon 

Undocumented 

1  eft 

Undocumented 

top 

Undocumented 
ri  ght 

Undocumented 

bottom 

Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


FlashMediaGetRefConID 


Undocumented 

ComponentResul t  FlashMediaGetRefConID  ( 
MediaHandler  mh, 

long  refCon, 

long  *refConID  ); 


mh 

The  Toolbox's  connection  to  your  derived  Flash  media  handler.  You  can  obtain 
this  reference  from  GetMediaHandler  (1-432). 

refCon 

Undocumented 
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FlashMediaGetSupportedSwfVersion 


refConID 

Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es .  h 


FlashMediaGetSupportedSwfVersion 


Identifies  the  version  of  Flash  that  this  version  of  QuickTime  supports. 

ComponentResul t  FI ashMedi aGetSupportedSwfVersi on  ( 

MediaHandler  mh, 

unsigned  char  *swfVersion  ); 


mh 

The  Toolbox's  connection  to  your  derived  Flash  media  handler.  You  can  obtain 
this  reference  from  GetMediaHandler  (1-432). 
swfVersi on 

The  version  number  of  the  most  current  version  of  Flash  that  this  version  of 
QuickTime  supports. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Movi  es .  h 


FlashMedialDT  oRef  Con 

Undocumented 

ComponentResul t  FI ashMedi alDToRefCon  ( 
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FlashMediaSetFlashVariable 


MediaHandler  mh, 

long  refConID, 

long  *refCon  ); 


mh 

The  Toolbox's  connection  to  your  derived  Flash  media  handler.  You  can  obtain 
this  reference  from  GetMediaHandler  (1-432). 
refConID 

Undocumented 

refCon 

Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


FlashMediaSetFlash  V  ariable 


Sets  the  specified  Flash  action  variable  to  a  value. 


Component Res ul t  FI ashMedi a  Set  FI ashVariable 


Medi aHandl er 

char 

char 

char 

Bool ean 


mh , 

*path , 

*name , 

*val ue , 

updateFocus  ); 


( 


mh 

The  Toolbox's  connection  to  your  derived  Flash  media  handler.  You  can  obtain 
this  reference  from  GetMedi  aHandl  er  (1-432). 

path 

Specifies  the  path  to  the  Flash  button  to  which  the  variable  is  attached. 

name 

Specifies  the  name  of  the  Flash  variable, 
val  ue 

Specifies  the  new  value  of  the  Flash  variable. 
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FlashMediaSetPan 


updateFocus 

Pass  TRUE  if  the  focus  is  to  be  changed. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Movi  es .  h 


FlashMediaSetPan 


Undocumented 

ComponentResul t  FlashMediaSetPan  ( 
MediaHandler  mh, 

short  xPercent, 

short  yPercent  ) ; 


mh 

Undocumented 

xPercent 

Undocumented 

yPercent 

Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es .  h 


FlashMediaSetZoom 


Undocumented 
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ComponentResul t  FI ashMedi aSetZoom  ( 
MediaHandler  mh, 

short  factor  ); 


mh 

Undocumented 

factor 

Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


FlashMediaSetZoomRect 


Undocumented 

ComponentResul t  FI ashMedi aSetZoomRect 

Medi a  H  a  n  d 1 er 

mh , 

1  ong 

1  eft , 

1  ong 

top , 

1  ong 

ri ght , 

1  ong 

bottom  ) ; 

mh 

Undocumented 

1  eft 

Undocumented 

top 

Undocumented 

ri  ght 

Undocumented 

bottom 

Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
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FlattenMovie 


(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es .  h 


FlattenMovie 


Creates  a  new  movie  file  containing  a  specified  movie. 

void  FlattenMovie  ( 

Movi  e 
1  ong 

const  FSSpec 
OSType 
Seri ptCode 
1  ong 
short 

ConstStr255Param 
theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

movi  eFl  attenFl  ags 

Contains  flags  (see  below)  that  control  the  process  of  adding  movie  data  to  the 
new  movie  file.  Set  unused  flags  to  0. 

theFi  1  e 

A  pointer  to  the  file  system  specification  for  the  movie  file  to  be  created, 
creator 

The  creator  value  for  the  new  file, 
scri ptTag 

The  script  in  which  the  movie  file  should  be  created.  Set  this  parameter  to  the 
Script  Manager  constant  smSystemScri  pt  to  use  the  system  script;  set  it  to 
smCurrentScri  pt  to  use  the  current  script.  See  Inside  Macintosh:  Text  (listed  in  the 
bibliography)  for  more  information  about  scripts  and  script  tags. 

createMovi  eFi  1  eFl  ags 

Contains  flags  (see  below)  that  control  file  creation  options. 


theMovi e , 

movi  eFl  attenFl  ags  , 
*theFi  1  e , 
creator , 
scri ptTag , 

createMovi  eFi  1  eFl  ags  , 
*resld , 
resName  ) ; 
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res  Id 

A  pointer  to  a  field  that  contains  the  resource  ID  number  for  the  new  resource. 
If  the  field  referred  to  by  the  res  Id  parameter  is  set  to  0,  the  Movie  Toolbox 
assigns  a  unique  resource  ID  number  to  the  new  resource.  The  toolbox  then 
returns  the  movie's  resource  ID  number  in  the  field  referred  to  by  the  res  I  d 
parameter.  The  Movie  Toolbox  assigns  resource  ID  numbers  sequentially, 
starting  at  128.  If  the  res  I  d  parameter  is  set  to  NIL,  the  Movie  Toolbox  assigns  a 
unique  resource  ID  number  to  the  new  resource  and  does  not  return  that 
resource's  ID  value. 
resName 

Points  to  a  character  string  with  the  name  of  the  movie  resource.  If  you  set  the 
resName  parameter  to  NIL,  the  toolbox  creates  an  unnamed  resource. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

movieFlattenFlags  Constants 

fl attenAddMovi eToDataFork 

Causes  the  movie  to  be  placed  in  the  data  fork  of  the  new  movie  file,  as  well  as 
in  the  resource  fork.  You  may  use  this  flag  to  create  movie  files  that  are  more 
easily  moved  to  computer  systems  other  than  the  Macintosh, 
fl attenDontlnterl eaveFl atten 

Allows  you  to  disable  the  Movie  Toolbox's  data  storage  optimizations.  By 
default,  the  Movie  Toolbox  stores  movie  data  in  a  format  that  is  optimized  for 
playback.  Set  this  flag  to  1  to  disable  these  optimizations, 
fl attenActi veTracksOnly 

Causes  the  Movie  Toolbox  to  add  only  enabled  movie  tracks  to  the  new  movie 
file.  Use  SetT rackEnabl  ed  (III— 1658)  to  enable  and  disable  movie  tracks. 

f 1 attenCompressMovi e Resource 

Compresses  the  movie  resource  stored  in  the  file's  data  fork,  but  not  the  movie 
resource  stored  in  the  resource  fork  on  Mac  OS  systems, 
f 1 attenFSSpecPtrlsDataRef Record Ptr 

Set  this  flag  to  1  if  the  FSSpec  pointer  is  a  pointer  to  a  Data  Ref  erenceRecord 
(IV-2233)  structure.  This  capability  enables  you  to  flatten  movies  for  devices 
other  than  file  systems, 
f 1 attenForceMovi eResourceBef oreMovi  eData 

Set  this  flag  when  you  are  creating  a  fast  start  movie,  to  put  the  movie  resource 
at  the  front  of  the  resulting  movie  file. 
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createMovieFileFlags  Constants 

createMovieFileDeleteCurFile 

Indicates  whether  to  delete  an  existing  file.  If  you  set  this  flag  to  1,  the  Movie 
Toolbox  deletes  the  file  (if  it  exists)  before  creating  the  new  movie  file.  If  this 
flag  is  set  to  0  and  the  file  specified  by  the  f  i  1  eSpec  parameter  already  exists, 
the  Movie  Toolbox  uses  the  existing  file.  In  this  case,  the  toolbox  ensures  that 
the  file  has  both  a  data  and  a  resource  fork.  If  this  flag  is  not  set,  the  data  is 
appended  to  the  file. 

Discussion 

The  file  created  by  FI  attenMovi  e  also  contains  all  the  data  for  the  movie;  that  is,  the 
Movie  Toolbox  resolves  any  data  references  and  includes  the  corresponding  movie 
data  in  the  new  movie  file. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Saving  Movies"  (V-2715) 

Related  Java  Methods 

qui ckti me. std .movi es .Movi e. f 1 atten( ) 


See  Also 

To  create  multiplatform  QuickTime  movies,  use  FI  attenMovi  eData  (1-374)  instead  of 
FI  attenMovi  e. 


FlattenMovieData 


Creates  a  new  movie  and  a  file  that  contains  all  the  movie  data. 


Movie  FlattenMovie 
Movi  e 
1  ong 

const  FSSpec 
OSType 
Seri ptCode 
1  ong 


Data  ( 
theMovi e , 

movi  e FI  attenFl  ags  , 
*theFi  1  e , 
creator , 
scri ptTag , 
createMovi  eFi  1  e FI  a 


gs 


) : 


theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
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movi  eFl  attenFl  ags 

Contains  flags  (see  below)  that  control  the  process  of  adding  movie  data  to  the 
new  movie  file.  These  flags  affect  how  the  toolbox  adds  movies  to  the  new 
movie  file  later.  Set  unused  flags  to  0. 
theFi  1  e 

This  parameter  usually  contains  a  pointer  to  the  file  system  specification  for  the 
movie  file  to  be  created.  In  place  ofaFSSpec  pointer,  QuickTime  lets  you  pass  a 
pointer  to  a  data  reference  structure  to  receive  the  flattened  movie  data. 

creator 

The  creator  value  for  the  new  file, 
scri ptTag 

Contains  constants  (see  below)  that  specify  the  script  in  which  the  movie  file 
should  be  created.  See  Inside  Macintosh:  Text  (listed  in  the  bibliography)  for 
more  information  about  scripts  and  script  tags. 
createMovi eFi 1 eFl ags 

Contains  flags  (see  below)  that  control  file  creation  options. 

function  result  The  identifier  of  the  new  movie.  If  the  function  could  not  create  the 
movie,  it  sets  this  returned  identifier  to  NIL. 

movieFlattenFlags  Constants 

fl attenAddMovI eToDataFork 

Causes  the  movie  to  be  placed  in  the  data  fork  of  the  new  movie  file.  You  may 
use  this  flag  to  create  single-fork  movie  files,  which  can  be  more  easily  moved 
to  computer  systems  other  than  Macintosh, 
fl attenDontlnterl eaveFl atten 

Allows  you  to  disable  the  Movie  Toolbox's  data  storage  optimizations.  By 
default,  the  Movie  Toolbox  stores  movie  data  in  a  format  that  is  optimized  for 
the  storage  device.  Set  this  flag  to  1  to  disable  these  optimizations, 
fl attenActi veTracksOnly 

Causes  the  Movie  Toolbox  to  add  only  enabled  movie  tracks  to  the  new  movie 
file.  Use  SetT rackEnabl  ed  (III— 1658),  to  enable  and  disable  movie  tracks. 

f 1 attenCompressMovi e Resource 

Compresses  the  movie  resource  stored  in  the  file's  data  fork,  but  not  the  movie 
resource  stored  in  the  resource  fork  on  Mac  OS  systems, 
f 1 attenFSSpecPtrlsDataRef Record Ptr 

Set  this  flag  to  1  if  the  FSSpec  pointer  is  a  pointer  to  a  Data  Ref  erenceRecord 
(IV-2233)  structure.  This  capability  enables  you  to  flatten  movies  for  devices 
other  than  file  systems. 
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fl attenForceMo vie ResourceBeforeMo vie Data 

Set  this  flag  when  you  are  creating  a  fast  start  movie,  to  put  the  movie  resource 
at  the  front  of  the  resulting  movie  file. 

scriptTag  Constants 

smSystemScri pt 

Use  the  system  script. 
smCurrentScri pt 

Use  the  current  script. 

createMovieFileFlags  Constants 

createMovi eFi 1 eDel eteCurFi 1 e 

Indicates  whether  to  delete  an  existing  file.  If  you  set  this  flag  to  1,  the  Movie 
Toolbox  deletes  the  file  (if  it  exists)  before  creating  the  new  movie  file.  If  this 
flag  is  set  to  0  and  the  file  specified  by  the  f i 1 eSpec  parameter  already  exists, 
the  Movie  Toolbox  uses  the  existing  file.  In  this  case,  the  toolbox  ensures  that 
the  file  has  both  a  data  and  a  resource  fork.  If  this  flag  isn't  set,  the  data  is 
appended  to  the  file. 

Discussion 

This  function  will  take  any  movie  and  optionally  make  it  self-contained, 
interleaved,  and  Fast  Start.  Unlike  Fl  attenMovi  e  (1-372),  this  function  does  not  add 
the  new  movie  resource  to  the  new  movie  file;  instead,  FlattenMovieData  returns  the 
new  movie  to  your  application.  Your  application  must  dispose  of  the  returned 
movie.  You  can  use  this  function  to  create  a  single-fork  movie  file,  by  setting  the 
flattenAddMovi  eTo  Data  Fork  flag  in  the  movieFlatten  Flags  parameter  to  1.  The  Movie 
Toolbox  then  places  the  movie  into  the  data  fork  of  the  movie  file.  Instead  of 
flattening  to  a  file,  you  can  specify  a  data  reference  to  flatten  a  movie  to.  The 
following  two  code  samples  show  flattening  a  movie  to  a  data  location  and  to  a  file: 

//  FlattenMovieData  used  to  flatten  a  movie  to  a  data  location 
//  create  a  0-length  handle 

myHandle  =  NewHandleClear(mySize) ; 
if  (myHandle  ==  NIL) 
goto  bail; 

//  fill  in  the  data  reference  record 

myDataRef Rec . dataRefType  =  Handl eDataHandl erSubType ; 
myDataRef Rec . dataRef  =  NewHandle(sizeof(Handle) ) ; 
if  (myDataRefRec. dataRef  ==  NIL) 
goto  bail; 

*( (Handle  *)*(myDataRefRec. dataRef ) )  =  myHandle; 
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myFlags  =  fl attenFSSpecPtrlsDataRefRecordPtr; 
myFile  =  (FSSpec  *)&myDataRefRec; 

//  flatten  the  source  movie  into  the  handle 

myMemMovie  =  Fl attenMovi eData (mySrcMovi e ,  myFlags,  myFile,  OL, 

smSystemScri pt ,  OL); 


Movie  aMovie; 

aMovie  =  Fl attenMovi eData (theMovi e , 
fl attenAddMovieToDataFork  | 
fl attenForceMovi eResourceBef oreMovi eData , 

&theOutputFi 1 e ,  OSTypeConstl ' TVOD ' ) ,  smSystemScri pt , 
createMovi eFi 1 eDel eteCurFi 1 e  |  createMovi eFi 1 eDontC reate Res Fi 1 e) ; 

Di sposeMovi e( aMovi e) ; 

Movie  aMovie; 

aMovie  =  Fl attenMovi eData (theMovi e , 
fl attenAddMovi eToDataFork, 

&theOutputFi 1 e ,  OSTypeConst( ' TVOD ' ) ,  smSystemScri pt , 
createMovi eFi 1 eDel eteCurFi 1 e  |  createMovi eFi 1 eDontC reate ResFi 1 e) ; 

Di sposeMovi e( aMovi e) ; 

//  FlattenMovieData  used  to  flatten  a  movie  to  a  Fast  Start  file 
//  See  “Discovering  QuickTime,”  page  257 

myErr  =  OpenMovi eFi 1 e(&myTempSpec ,  &myTempResRefNum,  fsRdPerm); 
if  (myErr  !=  noErr) 

goto  bail  ; 

myErr  =  NewMovi eFromFi 1 e(&myTempMovi e ,  myTempResRefNum,  NIL,  0,  0,  0); 
if  (myErr  !=  noErr) 

goto  bail  ; 

SetMovieProgressProc(myTempMovie,  (Movi  eProgresslIPP)  - 1 ,  OL); 

//  flatten  the  temporary  file  into  a  new  movie  file;  put  the  movie 
//  resource  first  so  that  progressive  downloading  is  possible 
myPanoMovie  =  Fl attenMovi eData ( 

myTempMovi e , 

flattenDontlnterleaveFl atten 

|  fl attenAddMovieToDataFork 

|  fl attenForceMovi eResourceBef oreMovi eData , 
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&myDestSpec , 

F0UR_CHAR_C0DE( 'TVOD'  )  , 
smSystemScri  pt , 
createMovi eFi 1 eDel eteCurFi 1 e 
|  createMovieFileDontCreateResFile) ; 

Special  Considerations 

Through  the  SetT rackLoadSetti  ngs  (III— 1661)  function,  the  Movie  Toolbox  allows 
you  to  set  a  movie's  preloading  guidelines  when  you  create  the  movie.  The  preload 
information  is  preserved  when  you  save  or  flatten  the  movie  (using  either 
FI  attenMovi  e  or  FI  attenMovi  eData).  In  flattened  movies,  the  tracks  that  are  to  be 
preloaded  are  stored  at  the  start  of  the  movie,  rather  than  being  interleaved  with  the 
rest  of  the  movie  data.  This  greatly  improves  preload  performance  because  it  is  not 
necessary  for  the  device  storing  the  movie  data  to  seek  during  retrieval  of  the  data 
to  be  preloaded. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Saving  Movies"  (V-2715) 

Related  Java  Methods 

qu ickti me. std. mo vies. Mo vie. flatten  Da ta() 


See  Also 

See  FI  attenMovi  e  (1-372). 


FracSinCos 


Undocumented 

Fract  FracSinCos  ( 

Fixed  degree, 

Fract  *cosOut  ); 

degree 

Undocumented 

cosOut 

Undocumented 

function  result  Undocumented 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


FSSpecToNativePathName 

Extracts  the  native  pathname  from  an  FSSpec. 

OSErr  FSSpecToNativePathName  ( 
const  FSSpec  *inFile, 

char  *outName, 

unsigned  long  outLen, 

long  flags  ); 

i  n  F  i  1  e 

A  pointer  to  a  FSSpec. 
outName 

A  pointer  to  a  buffer  to  hold  a  C  string. 
outLen 

Specifies  the  maximum  size  of  the  buffer  in  bytes,  including  the  string 
terminator. 

fl  ags 

Contains  flags  (see  below)  that  control  the  conversion. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

k  Fu 1 1 Nati vePath 

The  full  pathname  should  be  returned. 
kFi 1 eNameOnly 

Only  the  part  of  the  pathname  corresponding  to  the  file  should  be  returned. 
This  might  be  useful  to  return  a  string  for  a  Windows  title. 

kDi rectoryPathOnly 

The  full  pathname  up  to  and  including  the  enclosing  directory  but  not  the 
filename  should  be  returned.  This  can  be  useful  to  get  a  path  for  the  enclosing 
directory  that  might  be  used  to  find  related  files  in  the  same  directory. 
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Discussion 

You  can  use  this  function  to  convert  an  FSSpec  returned  by  QuickTime  to  a  native 
pathname  to  be  passed  to  the  current  operating  system.  It  accepts  an  FSSpec  and 
puts  the  equivalent  pathname  string  into  a  buffer. 

Special  Considerations 

You  can  set  the  output  buffer  size  to  pathnameMaxBufferSize.  This  value  must  also 
include  the  string  terminator. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML.h 


GDGetScale 


Returns  the  current  scale  of  the  given  screen  graphics  device. 

OSErr  GDGetScale  ( 

GDHandle  gdh, 

Fixed  *scale, 

short  *f 1 ags  ) ; 


gdh 

A  handle  to  a  screen  graphics  device, 
seal  e 

Points  to  a  fixed-point  field  to  hold  the  scale  result, 
fl  ags 

Points  to  a  short  integer  that  returns  the  status  parameter  flags  for  the  video 
driver.  Currently,  0  is  always  returned  in  this  field. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Controlling  Hardware  Scaling"  (V-2718) 

See  Also 

For  the  corresponding  set  function,  see  GDSetScal  e  (1-382). 


GDHasScale 


Returns  the  closest  possible  scaling  that  a  particular  screen  device  can  be  set  to  in  a 
given  pixel  depth. 

OSErr  GDHasScale  ( 

GDHandle  gdh, 

short  depth. 

Fixed  *scale  ); 


gdh 

A  handle  to  a  screen  graphics  device, 
depth 

The  pixel  depth  of  the  screen  device, 
scale 

Points  to  a  fixed-point  scale  value.  On  input,  this  field  should  be  set  to  the 
desired  scale  value.  On  output,  this  field  will  contain  the  closest  scale  available 
for  the  given  depth.  A  scale  of  0x10000  indicates  normal  size,  0x20000  indicates 
double  size,  and  so  on. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns  scaling  information  for  a  particular  screen  device  for  a 
requested  depth.  This  function  allows  you  to  query  a  screen  device  without  actually 
changing  it.  For  example,  if  you  specify  0x20000  but  the  screen  device  does  not 
support  it,  GDHasScale  returns  noErr  and  a  scale  of  0x10000.  Because  this  function 
checks  for  a  supported  depth,  your  requested  depth  must  be  supported  by  the 
screen  device. 

Special  Considerations 

GDHasScale  references  the  video  driver  through  the  graphics  device  structure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Controlling  Hardware  Scaling"  (V-2718) 


GDSetScale 


Sets  a  screen  graphics  device  to  a  new  scale. 

OSErr  GDSetScale  ( 

GDHandle  gdh, 

Fixed  scale, 

short  f 1 ags  ) ; 


gdh 

A  handle  to  a  screen  graphics  device, 
seal  e 

A  fixed-point  scale  value, 
fl  ags 

Points  to  a  short  integer.  It  returns  the  status  parameter  flags  for  the  video 
driver.  Currently,  0  is  always  returned  in  this  field. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Controlling  Hardware  Scaling"  (V-2718) 

See  Also 

For  the  corresponding  get  function,  see  GDGetScal  e  (1-380). 


GetBestDeviceRect 


Selects  the  deepest  of  all  available  graphics  devices,  while  treating  16-bit  and  32-bit 
screens  as  having  equal  depth. 

OSErr  GetBestDeviceRect  ( 

GDHandle  *gdh, 

Rect  *rp  ) ; 
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gdh 

A  pointer  to  the  handle  of  the  rectangle  for  the  chosen  device.  If  you  do  not  need 
the  information  in  this  parameter  returned,  specify  N I L. 
rp 

A  pointer  to  the  rectangle  that  is  adjusted  for  the  height  of  the  menu  bar  if  the 
device  is  the  main  device.  If  you  do  not  need  the  information  in  this  parameter 
returned,  specify  N I L. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  does  not  center  a  rectangle  on  a  device.  Rather,  it  returns  the  rectangle 
for  the  best  device.  The  following  code  sample  illustrates  its  use: 

//  GetBestDeviceRect  coding  example 
//  See  “Discovering  QuickTime,”  page  265 

WindowPtr  MakeMyWindow  (void) 

{ 

WindowPtr  pMacWnd; 

Rect  rectWnd  =  {0,  0,  120,  160}; 

Rect  rectBest; 

//  figure  out  the  best  monitor  for  the  window 
Get Best Devi ceRect(NIL,  & rect Best) ; 

//  put  the  window  in  the  top  left  corner  of  that  monitor 
OffsetRect(&rectWnd ,  rectBest . 1  eft  +  10,  rectBest. top  +  50); 

//  create  the  window 

pMacWnd  =  NewCWi ndow( NI L,  &rectWnd,  "\pGrabber", 

TRUE,  noGrowDocProc ,  ( Wi ndowPtr ) - 1 ,  TRUE,  0); 

//  set  the  port  to  the  new  window 
SetPort( pMacWnd ) ; 

return  pMacWnd; 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Graphics  Devices  and  Graphics  Worlds" 
(V-2798) 

GetCallBackTimeBase 


Retrieves  the  time  base  of  a  callback  event. 

TimeBase  GetCallBackTimeBase  ( 

QTCal 1  Back  cb  ) ; 


cb 

The  callback  event  for  the  operation.  You  obtain  this  value  from  the 
NewCal  1  Back  (11-1053)  function. 

function  result  A  pointer  to  a  Ti  meBaseRecord  (IV-2481)  structure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Time  Base  Callback  Functions"  (V-2763) 

Related  Java  Methods 

qu i c kt i me. std. clocks. QTCal 1  Back. getTi me Basel), 
qui ckti me . std . cl ocks .TimeBase . f romQTCal 1  Back ( ) 


GetCallBackType 


Retrieves  a  callback  event's  type. 

short  GetCallBackType  ( 

QTCal 1  Back  cb  )  ; 


cb 

The  callback  event  for  the  operation.  You  obtain  this  value  from  NewCall  Back 
(11-1053). 

function  result  The  callback  type  constant  (see  below).  If  the  high-order  bit  (defined 
by  cal  1  BackAtlnterrupt)  of  the  returned  value  is  set  to  1,  the  event 
can  be  invoked  at  interrupt  time. 
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Function  Result  Constants 

cal  1 BackAtT i me 

Indicates  that  the  event  is  to  be  invoked  at  a  specified  time, 
cal  1 BackAtRate 

Indicates  that  the  event  is  to  be  invoked  when  the  rate  for  the  time  base  reaches 
a  specified  value, 
call BackAtT i me Jump 

Indicates  that  the  event  is  to  be  invoked  when  the  time  base's  time  value 
changes  by  an  amount  that  differs  from  its  rate, 
call  BackAt  I  interrupt 

Defines  the  bit  of  the  returned  value  which  indicates  that  the  event  can  be 
invoked  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Time  Base  Callback  Functions"  (V-2763) 

Related  Java  Methods 

qui cktime . std . cl ocks . QTCal 1  Back. getTypel ) 


GetCodecInfo 


Returns  information  about  a  single  compressor  component. 

OSErr  GetCodecInfo  ( 

Codeclnfo  *info, 

CodecType  cType, 

CodecComponent  codec  ); 


i  nf  o 

A  pointer  to  a  Codeclnfo  (IV-2202)  structure.  GetCodecInfo  returns  detailed 
information  about  the  appropriate  compressor  component  in  this  structure. 
cType 

Set  this  parameter  to  a  valid  compressor  type  constant;  see  "Codec  Identifiers" 
(IV-2655).  If  you  want  information  about  any  compressor  of  the  type  specified 
by  this  parameter,  set  the  codec  parameter  to  0.  The  Image  Compression 
Manager  then  returns  information  about  the  first  compressor  it  finds  of  the  type 
you  have  specified. 
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codec 

Set  this  parameter  to  the  component  identifier  of  the  specific  compressor  for  the 
request,  or  to  0  for  any  compressor.  Component  identifiers  are  available  in  the 
CodecNameSpecLi  st  (IV-2208)  structure  returned  by  GetCodecNameLi  st  (1-386). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Getting  Information  About  Compressor  Components" 
(V-2788) 

Related  Java  Methods 

qui cktime. std . image. Codec Info. Codeclnfot ) 


GetCodecN  ameList 


Retrieves  a  list  of  installed  compressor  components  or  types. 

OSErr  GetCodecNameList  ( 

CodecNameSpecLi stPtr  *list, 

short  showAl 1  ) ; 


list 

A  pointer  to  a  field  that  is  to  receive  a  pointer  to  a  CodecNameSpecLi  st  (IV-2208) 
structure.  The  Image  Compression  Manager  creates  the  appropriate  list  and 
returns  a  pointer  to  that  list  in  the  field  specified  by  this  parameter. 

showAl 1 

A  short  integer  that  controls  the  contents  of  the  list.  Set  this  parameter  to  1  to 
receive  a  list  of  the  names  of  all  installed  compressor  components;  the  returned 
list  contains  one  entry  for  each  installed  compressor.  Set  this  parameter  to  0  to 
receive  a  list  of  the  types  of  installed  compressor  components;  the  returned  list 
contains  one  entry  for  each  installed  compressor  type. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  CodecType  data  type  defines  a  field  in  the  CodecNameSpec  (IV-2208)  structure  that 
identifies  the  compression  method  employed  by  a  given  compressor  component. 
See  "Codec  Identifiers"  (IV-2655).  Apple  Computer's  Developer  Technical  Support 
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group  assigns  these  values  so  that  they  remain  unique.  These  values  correspond,  in 
turn,  to  text  strings  that  can  identify  the  compression  method  to  the  user. 

Special  Considerations 

GetCodecNameLi  st  creates  the  CodecNameSpecLi  st  structure  in  your  application's 
current  heap  zone. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Getting  Information  About  Compressor  Components" 
(V-2788) 

Related  Java  Methods 

qui ckti me . std . image . CodecNameLi st . CodecNameLi  st( ) 


See  Also 

See  CodecNameSpecLi  st  (IV-2208). 


GetComponentlconSuite 


Returns  a  handle  to  the  component's  icon  suite  (if  it  provides  one). 

OSErr  GetComponentlconSuite  ( 

Component  aComponent, 

Handle  *iconSuite  ); 

aComponent 

A  component  instance.  Your  application  obtains  the  component  instance  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

i conSui te 

A  handle  to  the  component's  icon  suite,  if  any.  If  the  component  has  not 
provided  an  icon  suite,  GetComponent  I  conSui  te  returns  NI L  in  this  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns  a  handle  to  the  component's  icon  suite.  A  component  provides 
to  the  Component  Manager  the  resource  ID  of  its  icon  family  in  the  optional 
extensions  to  the  component  resource.  Your  application  is  responsible  for  disposing 
of  the  returned  icon  suite  handle. 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Component  Functions  Used  By  Applications"  (V-2781) 

See  Also 

For  information  about  Macintosh  icon  suites  and  icon  families,  see  Chapter  5  of 
Inside  Macintosh:  More  Macintosh  Toolbox  (listed  in  the  bibliography). 

GetComponentlndString 

Gets  a  private  component  resource  string. 

OSErr  GetComponentlndString  ( 

Component  aComponent, 

Str255  theString, 

short  strListID, 

short  i ndex  ) ; 

aComponent 

A  component  instance.  Your  application  obtains  the  component  instance  from 
OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

theStri ng 

The  returned  string. 
strLi stID 

The  ID  of  the  Macintosh  '  STR# '  resource  that  contains  the  string, 
i  ndex 

The  index  number  of  the  string  in  the  Macintosh  '  STR#'  resource. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  can  use  this  function  to  get  a  single  string  from  a  Macintosh  ’  STR# '  resource 
belonging  to  a  component.  The  following  code  snippet  illustrates  its  use: 

Str255  str; 

err  =  GetComponentlndStri ng( (Component)store->self ,  str,  128,  1); 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Components .  h 


GetComponentlnfo 

Returns  all  of  the  registration  information  for  a  component. 

OSErr  GetComponentlnfo  ( 

Component 

ComponentDescri pti  on 
Handl e 
Hand! e 
Handl e 

aComponent 

A  component  identifier  that  specifies  the  component  for  the  operation.  Your 
application  obtains  a  component  identifier  from  FindNextComponent  (1-360). 
Alternatively,  you  can  supply  a  component  instance.  Your  application  obtains 
a  component  instance  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent 
(11-1131). 

cd 

A  pointer  to  a  ComponentDescri  pti  on  (IV-2212)  structure,  which  contains 
information  about  the  component's  type,  subtype,  and  manufacturer. 

componentName 

A  handle  to  the  component's  name.  You  must  allocate  this  handle  before  calling 
this  function.  Pass  N I L  if  you  don't  want  this  information. 

componentlnfo 

A  handle  to  the  component's  information  string.  You  must  allocate  this  handle 
before  calling  this  function.  Pass  N I L  if  you  don't  want  this  information, 
componentlcon 

A  handle  to  the  component's  black-and-white  icon.  You  must  allocate  this 
handle  before  calling  this  function.  Pass  N I L  if  you  don't  want  this  information. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components  .  h 

Programming  summary:  "Component  Functions  Used  By  Applications"  (V-2781) 


aComponent , 

*cd , 

componentName , 
componentlnfo, 
componentlcon  ); 
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GetComponentInstanceA5 


Related  Java  Methods 

qui ckti me . std . comp. Component  I  dent i fier.getInfo( ) 


GetComponentInstanceA5 

Obsolete. 

long  GetComponentInstanceA5  ( 

Componentlnstance  aComponentlnstance  ); 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier.  Macintosh  Note:  Not  supported  by 

CarbonLib. 

Programming  Info 

C  interface  file:  Components .  h 

See  Also 

For  the  corresponding  set  function,  see  SetComponentInstanceA5  (III— 1570). 


GetComponentlnstanceError 


Returns  the  last  error  generated  by  a  specific  connection  to  a  component. 

OSErr  GetComponentlnstanceError  ( 

Componentlnstance  aComponentlnstance  ); 

aComponentlnstance 

A  component  instance.  Your  application  obtains  the  component  instance  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Component  Functions  Used  By  Applications"  (V-2781) 

See  Also 

For  the  corresponding  set  function,  see  SetComponentlnstanceError  (III— 1571). 
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GetComponentlnstanceStorage 


Lets  your  component  retrieve  a  handle  to  the  memory  associated  with  a  component 
connection. 

Handle  GetComponentlnstanceStorage  ( 

Componentlnstance  aComponentlnstance  ); 

a Component  Instance 

A  component  instance.  Your  application  obtains  the  component  instance  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

function  result  A  handle  to  the  memory  associated  with  a  component  connection. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 

See  Also 

For  the  corresponding  set  function,  see  SetComponentlnstanceStorage  (III— 1572). 


GetComponentListModSeed 


Determines  if  the  list  of  registered  components  has  changed, 
long  GetComponentListModSeed  (  void  ); 
function  result  The  component  registry  seed  number. 

Discussion 

This  function  lets  you  determine  if  the  list  of  registered  QuickTime  components  has 
changed.  It  returns  the  value  of  the  component  registry  seed  number  for  the 
component  list.  By  comparing  this  value  to  values  previously  returned  by  this 
function,  you  can  determine  whether  the  component  registry  has  changed. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 
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GetComponentPublicResource 

Retrieves  a  component's  public  resource. 

OSErr  GetComponentPublicResource  ( 

Component  aComponent, 

OSType  resourceType , 

short  resourcelD, 

Handle  *theResource  ); 

aComponent 

A  component  instance.  Your  application  obtains  the  component  instance  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
resourceType 

The  resource's  type. 
resourcelD 

The  resource's  ID. 
theResource 

A  pointer  to  a  handle  to  the  resource.  A  component  ’  s  public  resources  can  be 
accessed  without  having  to  first  open  the  component. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Some  types  of  components  provide  information  about  themselves  through  public 
component  resources.  For  example.  Movie  Export  components  can  each  contain  a 
public  resource  which  indicates  the  kinds  of  QuickTime  media  types  that  may  be 
exported.  QuickTime  visual  effects  components  can  each  contain  a  public  resource 
that  describes  the  1  i  st  of  parameters  that  can  be  used  to  configure  the  effect. 

Special  Considerations 

The  resources  returned  by  this  function  are  cached.  This  means  that  successive  calls 
to  access  the  same  resource  are  typically  very  fast. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Components .  h 
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GetComponentPublicResourceList 


Obtains  a  single  public  resource  from  each  component  that  matches  a  component 
description. 

OSErr  GetComponentPubl i cResourceLi st 
OSType 
short 
1  ong 

ComponentDescri pti  on 
GetMi  ssi  ngComponent  Res  our  cell  PP 
void 
void 

resourceType 

Undocumented 
resourcelD 

Undocumented 
fl  ags 

Undocumented 
cd 

Undocumented 
mi  ssi ngProc 

A  GetMi  ssi  ngComponentResourceProc  (III— 2084)  callback. 
refCon 

A  reference  constant  to  be  passed  to  your  callback.  Use  this  parameter  to  point 
to  a  data  structure  containing  any  information  your  function  needs. 
atomContai nerPtr 
Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 
Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Components .  h 


( 

resourceType , 
resourcelD, 
fl ags , 

*cd , 

mi ssi ngProc , 

*refCon , 

*atomContai nerPtr  ); 
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GetComponentRefcon 


Retrieves  the  value  of  the  reference  constant  for  your  component. 

long  GetComponentRefcon  ( 

Component  aComponent  ) ; 

aComponent 

A  component  instance.  Your  application  obtains  the  component  instance  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

function  result  The  component's  reference  constant. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 

See  Also 

For  the  corresponding  set  function,  see  SetComponentRefcon  (III— 1573). 


GetComponentResource 


Undocumented 

OSErr  GetComponentResource  ( 

Component  aComponent, 

OSType  resType, 

short  resID, 

Handle  *theResource  ); 

aComponent 

A  component  instance.  Your  application  obtains  the  component  instance  from 
OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

resType 

Undocumented 

resID 

Undocumented 

theResource 

Undocumented 
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function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 


GetComponentTypeModSeed 


Determines  if  the  specified  type  of  registered  component  has  changed. 

long  GetComponentTypeModSeed  ( 

OSType  componentType  ) ; 


componentType 

A  four-character  code  that  identifies  the  type  of  component.  See  "Component 
Identifiers"  (IV-2657). 


Discussion 


function  result  The  component  registration  seed  number  for  the  specified 
component  type. 

This  function  is  similar  to  GetComponentLi  stModSeed  (1-391),  but  is  specific  to  a  single 
component  type.  This  allows  you  to  tell,  for  example,  whether  the  registration  of 
image  decompressor  ( '  i mdc ' )  components  has  changed  regardless  of  other 
component  changes.  This  function  returns  the  value  of  the  component  registry  seed 
number  for  the  specified  component  type.  By  comparing  this  value  to  values 
previously  returned  by  this  function,  you  can  determine  whether  the  component 
registry  for  the  specified  type  has  changed. 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 


GetComponentVersion 

Returns  a  component's  version  number. 

long  GetComponentVersion  ( 

Componentlnstance  ci  ); 
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ci 

A  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

function  result  The  version  number  of  the  component. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Component  Functions  Used  By  Applications"  (V-2781) 


GetCompressedlmageSize 


Determines  the  size,  in  bytes,  of  a  compressed  image. 


OSErr  GetCompressedlmageSize 
ImageDescriptionHandle 
Ptr 
1  ong 

ICMDataProcRecordPtr 
1  ong 


( 

desc , 
data , 

bufferSi ze , 
dataProc , 
*dataSize  ); 


desc 

A  handle  to  the  ImageDescri  pti  on  (IV-2285)  structure  that  defines  the 
compressed  image  for  the  operation. 

data 

Points  to  the  compressed  image  data.  This  pointer  must  contain  a  32-bit  clean 
address. 

bufferSi ze 

The  size  of  the  buffer  to  be  used  by  the  data-loading  function  specified  by  the 
dataProc  parameter.  If  you  have  not  specified  a  data-loading  function,  set  this 
parameter  to  0. 
dataProc 

Points  to  an  ICMDataProc  (III— 2090)  callback.  If  the  data  stream  is  not  all  in 
memory  when  your  program  calls  GetCompressedlmageSi  ze,  the  compressor 
calls  a  function  you  provide  that  loads  more  compressed  data.  If  you  have  not 
provided  a  data-loading  callback,  set  this  parameter  to  N I L.  In  this  case,  the 
entire  image  must  be  in  memory  at  the  location  specified  by  the  data  parameter. 

dataSi ze 

A  pointer  to  a  field  that  is  to  receive  the  size,  in  bytes,  of  the  compressed  image. 
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GetCompressedPixMapInfo 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Most  applications  do  not  need  to  use  this  function  because  compressed  images  have 
a  corresponding  ImageDescri  pti  on  (IV-2285)  structure  with  a  size  field.  You  only 
need  to  use  this  function  if  you  do  not  have  an  image  description  structure 
associated  with  your  data;  for  example,  when  you  are  taking  a  compressed  image 
out  of  a  movie  one  frame  at  a  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Getting  Information  About  Compressed  Data"  (V-2787) 

Related  Java  Methods 

qui cktime . std . image . QTImage . getCompressedSi ze( ) 


GetCompressedPixMapInfo 


Retrieves  information  about  a  compressed  image. 


OSErr  GetCompressedPixMapInfo 
Pi xMapPtr 

ImageDescri pti onHandl e 
Ptr 
1  ong 

ICMDataProcRecord 
ICMProgressProc Record 


( 

pix, 

*desc , 

*data , 

*buf ferSi ze , 

*dataProc, 

*progressProc 


pi  x 

Points  to  a  structure  that  holds  encoded  compressed  image  data. 

desc 

A  pointer  to  a  field  that  is  to  receive  a  handle  to  the  ImageDescri  pti  on  (IV-2285) 
structure  that  defines  the  compressed  image.  If  you  are  not  interested  in  this 
information,  specify  NI L  in  this  parameter. 

data 

A  pointer  to  a  field  that  is  to  receive  a  pointer  to  the  compressed  image  data.  If 
the  entire  compressed  image  cannot  be  stored  at  this  location,  you  can  define  a 
data-loading  function  for  this  operation.  If  you  are  not  interested  in  this 
information,  you  may  specify  N I L  in  this  parameter. 
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bufferSi ze 

A  pointer  to  a  field  that  is  to  receive  the  size  of  the  buffer  to  be  used  by  the 
data-loading  function  specified  by  the  dataProc  parameter.  If  there  is  no 
data-loading  function  defined  for  this  operation,  this  parameter  is  ignored.  If 
you  are  not  interested  in  this  information,  you  may  specify  N I L  in  this 
parameter. 
dataProc 

A  pointer  to  an  ICMDataProc  (III— 2090)  callback.  If  there  is  not  enough  memory 
to  store  the  compressed  image,  the  decompressor  calls  a  function  you  provide 
that  loads  more  compressed  data.  If  there  is  no  data-loading  function  for  this 
image,  the  function  sets  the  dataProc  field  in  the  function  structure  to  N I L.  If  you 
are  not  interested  in  this  information,  specify  N I L  in  this  parameter. 

progressProc 

A  pointer  to  an  ICMProgressProc  (III— 2093)  callback.  During  a  decompression 
operation,  the  decompressor  may  occasionally  call  a  function  you  provide  in 
order  to  report  its  progress.  If  there  is  no  progress  function  for  this  image,  the 
function  sets  the  progressProc  field  in  the  function  structure  to  NIL.  If  you  pass 
a  value  of  -1,  QuickTime  provides  a  standard  progress  function.  If  you  are  not 
interested  in  progress  information,  specify  N I L  in  this  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  the  StdPix  Function"  (V-2797) 

See  Also 

For  the  corresponding  set  function,  see  SetCompressedPixMapInfo  (III— 1573). 


GetCompressionlnfo 


Gets  information  about  sound  compression. 


OSErr  GetCompressionlnfo 
short 
OSType 
short 
short 

Comp  res si onlnfoPtr 


( 

compressionID, 
format , 
numChannel s , 
sampl eSi ze , 
cp  ) : 
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compressi onID 

The  compression  algorithm  used  on  a  data  sample  (see  below), 
format 

The  format  of  the  compressed  data  (see  below).  This  parameter  is  set  to  0  if  the 
comp  res  si  on  ID  parameter  contains  other  than  f  i  xedCompressi  on. 

numChannel s 

The  number  of  channels  for  compressed  sound, 
sampl eSi ze 

The  size  of  each  sample, 
cp 

A  pointer  to  a  Compressi  onlnfo  (IV-2222)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

compressionID  Constants 

notCompressed 

No  compression, 
f i xedCompressi on 

Fixed-size  compression, 
vari abl eCompressi on 

Variable-size  compression. 

format  Constants 

'NONE' 

Not  compressed. 

' MAC3 ' 

Compression  format  is  MACE  3:1. 

'  MAC6 ' 

Compression  format  is  MACE  6:1. 

'  ima4 ' 

Compression  format  is  IMA  4:1. 

Discussion 

The  AIFF-C  Extended  Common  Chunk  format  does  not  contain  a  compressi  onID 
field.  In  this  case  (and  when  using  '  snd  '  resources  where  the  OSType  describing  the 
compression  format  is  known)  you  should  always  pass  the  constant 
fi xedCompressi  on  in  this  parameter  and  the  OSType  value  in  the  format  parameter. 
The  format  field  will  then  contain  the  OSType  value  representing  the  compression 
format.  If  you  set  the  compressi  onID  field  in  a  compressed  sound  header  to  any 
value  other  than  f  i  xedCompressi  on,  then  the  format  field  is  set  to  zero.  If  you  pass 


Inside  QuickTime:  Functions  A-H 


1-399 


GetCompressionName 


f  i  xedCompressi  on  in  the  comp  res  si  on  ID  parameter  you  will  need  to  pass  a  valid 
compression  type  here. 

Special  Considerations 

There  are  some  'snd  '  resources  that  do  not  store  an  OSType  value  in  the  format  field 
of  the  compressed  sound  header  to  describe  the  compression  format.  You  can  still 
use  Get  Comp  res  si  on  Info  in  this  case  by  passing  in  the  comp  res  si  on  ID  and  passing  0 
in  the  format  parameter.  The  correct  OSType  will  be  returned  in  the  format  field  of  the 
Compressi onlnfo  structure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

Related  Java  Methods 

qui ckti me . sound . Compressi onlnfo. get( ) 


GetCompressionName 


Describes  a  given  compression  format  in  a  string  that  can  be  displayed  to  the  user. 

OSErr  GetCompressionName  ( 

OSType  compressi onType , 

Str255  compressi onName  ); 

compressi onType 

The  compression  format  (see  "Codec  Identifiers"  (IV-2655). 
compressi onName 

A  string  containing  the  compression  format's  name. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  string  returned  by  GetCompressi  onName  can  be  used  in  pop-up  menus  and  other 
user  interface  elements  to  allow  the  user  to  select  a  compression  format. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 
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GetCompressionT  ime 


Determines  the  estimated  amount  of  time  required  to  compress  a  given  image. 


OSErr  GetCompressionTime 
Pi xMapHandl e 
const  Rect 
short 
CodecType 

CompressorComponent 

CodecQ 

CodecQ 

unsigned  long 


src, 

*srcRect, 
col orDepth , 
cType , 
codec , 

*spati al Qual i ty , 
*temporal Qual i ty , 
*compressTime  ); 


src 

A  handle  to  the  source  image.  The  source  image  must  be  stored  in  a  pixel  map 
structure.  The  compressor  uses  only  the  bit  depth  of  this  image  to  determine  the 
compression  time.  You  may  set  this  parameter  to  N I L  if  you  are  interested  only 
in  information  about  quality  settings. 

srcRect 

A  pointer  to  a  rectangle  defining  the  portion  of  the  source  image  to  compress. 
You  may  set  this  parameter  to  N I L  if  you  are  interested  only  in  information 
about  quality  settings.  GetCompressionTime  then  uses  the  bounds  of  the  source 
pixel  map. 
col orDepth 

The  depth  at  which  the  image  is  to  be  compressed.  If  you  set  this  parameter  to 
0,  the  Image  Compression  Manager  determines  the  appropriate  value  for  the 
source  image.  Values  of  1,  2, 4, 8, 16, 24,  and  32  indicate  the  number  of  bits  per 
pixel  for  color  images.  Values  of  34,  36,  and  40  indicate  2-bit,  4-bit,  and  8-bit 
grayscale,  respectively,  for  grayscale  images.  Your  program  can  determine 
which  depths  are  supported  by  a  given  compressor  by  examining  the 
compressor  information  structure  returned  by  the  GetCodecInfo  (1-385) 
function 
cType 

You  must  set  this  parameter  to  a  valid  compressor  type  constant;  see  "Codec 
Identifiers"  (IV-2655). 

codec 

Specify  a  particular  compressor  by  setting  this  parameter  to  its  compressor 
identifier.  Alternatively,  you  may  use  a  special  identifier  (see  below).  You  can 
also  specify  a  component  instance.  This  may  be  useful  if  you  have  previously 
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set  some  parameter  on  a  specific  instance  of  a  codec  field  and  want  to  make  sure 
that  the  specified  instance  is  used  for  that  operation. 

spati al Qual i ty 

A  pointer  to  a  field  containing  a  constant  (see  below)  that  defines  the  desired 
compressed  image  quality.  The  Image  Compression  Manager  sets  this  field  to 
the  closest  actual  quality  that  the  compressor  can  achieve.  If  you  are  not 
interested  in  this  information,  pass  N I L  in  this  parameter. 

temporal Qual i ty 

A  pointer  to  a  field  containing  a  constant  (see  below)  that  defines  the  desired 
temporal  quality.  Use  this  value  only  with  images  that  are  part  of  image 
sequences.  The  Image  Compression  Manager  sets  this  field  to  the  closest  actual 
quality  that  the  compressor  can  achieve.  If  you  are  not  interested  in  this 
information,  pass  N I L  in  this  parameter, 
compress!"  i  me 

A  pointer  to  a  field  to  receive  the  compression  time  in  milliseconds.  If  the 
compressor  cannot  determine  the  amount  of  time  required  to  compress  the 
image  or  if  the  compressor  does  not  support  this  function,  this  field  is  set  to  0. 
If  you  are  not  interested  in  this  information,  pass  NI L  in  this  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

codec  Constants 

anyCodec 

The  first  compressor  or  decompressor  of  the  specified  type. 
bestSpeedCodec 

The  fastest  compressor  or  decompressor  of  the  specified  type. 
bestFi del i tyCodec 

The  most  accurate  compressor  or  decompressor  of  the  specified  type, 
best Comp  res si  on Codec 

The  compressor  that  produces  the  smallest  resulting  data. 

spatialQuality  and  temporalQuality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 
codecNormal Qual i ty 

Image  reproduction  of  normal  quality. 
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codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 
codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field, 
codec Los  si essQual i ty 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

Discussion 

This  function  allows  you  to  verify  that  the  quality  settings  you  desire  are  supported 
by  a  given  compressor  component.  You  specify  the  compression  characteristics, 
including  compression  type  and  quality,  along  with  the  image.  The  Image 
Compression  Manager  returns  the  maximum  compression  time  for  the  specified 
image  and  parameters.  Note  that  some  compressors  may  not  support  this  function. 
If  the  component  you  specify  does  not  support  this  function,  the  Image 
Compression  Manager  returns  a  time  value  of  0. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Getting  Information  About  Compressed  Data"  (V-2787) 

Related  Java  Methods 

qui cktime . std . image . QTImage . getCompressi onTime( ) 


GetCSequenceDataRateParams 


Obtains  the  data  rate  parameters  previously  set  with  SetCSequenceDataRateParams 
(III— 1574). 

OSErr  GetCSequenceDataRateParams  ( 

ImageSequence  seqlD, 

DataRateParamsPtr  params  ); 

seqlD 

Contains  the  unique  sequence  identifier  that  was  returned  by 
CompressSequenceBegi  n  (1-119). 
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GetCSequenceFrameNumber 


params 

Points  to  the  data  rate  parameters  structure  associated  with  the  sequence 
identifier  specified  in  the  seqlD  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Constraining  Compressed  Data"  (V-2795) 

Related  Java  Methods 

quicktime.std.image.CSequence.getDataRateParamsO 


See  Also 

For  the  corresponding  set  function,  see  SetCSequenceDataRateParams  (III— 1574). 


GetCSequenceFrameNumber 


Returns  the  current  frame  number  of  the  specified  sequence. 

OSErr  GetCSequenceFrameNumber  ( 

ImageSequence  seqlD, 

1 ong  *f rameNumber  ) ; 


seqlD 

Contains  the  unique  sequence  identifier  that  was  returned  by  the 
CompressSequenceBegi n  (1-119)  function. 

f rameNumber 

A  pointer  to  the  current  frame  number  of  the  sequence  identified  by  the  seql  D 
parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Related  Java  Methods 

quicktime.std.image.CSequence. getFrameNumber ( ) 
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See  Also 

For  the  corresponding  set  function,  see  SetCSequenceFrameNumber  (III— 1576). 


GetCSequenceKeyFrameRate 


Determines  the  current  key  frame  rate  of  a  sequence. 

OSErr  GetCSequenceKeyFrameRate  ( 

ImageSequence  seqlD, 

long  *keyFrameRate  ); 

seqlD 

Contains  the  unique  sequence  identifier  that  was  returned  by 
CompressSequenceBegi  n  (1-119). 
keyFrameRate 

A  pointer  to  a  long  integer  that  specifies  the  maximum  number  of  frames 
allowed  between  key  frames.  Key  frames  provide  points  from  which  a 
temporally  compressed  sequence  may  be  decompressed. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Related  Java  Methods 

qui ckti me . std . image . CSequence . get Key Frame Rate! ) 


See  Also 

For  the  corresponding  set  function,  see  SetCSequenceKeyFrameRate  (III— 1577). 


GetCSequenceMaxCompressionSize 


Determines  the  maximum  size  an  image  will  be  after  compression  for  a  given 
compression  sequence. 

OSErr  GetCSequenceMaxCompressionSize  ( 

ImageSequence  seqlD, 

PixMapHandle  src, 

long  *size  ); 
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seqlD 

Contains  the  unique  sequence  identifier  that  was  returned  by  the 
CompressSequenceBegi n  (1-119)  function. 

src 

A  handle  to  the  source  Pi  xMap  (IV-2332)  structure.  The  compressor  uses  only 
the  image's  size  and  pixel  depth  to  determine  the  maximum  size  of  the 
compressed  image. 

si  ze 

A  pointer  to  a  field  to  receive  the  maximum  size,  in  bytes,  of  the  compressed 
image. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  similar  to  GetMaxCompressi  onSi  ze  (1-420),  but  operates  on  a 
compression  sequence  instead  of  requiring  the  application  to  pass  individual 
parameters  about  the  source  image. 

Special  Considerations 

Before  calling  GetCSequenceMaxCompressi  onSi  ze  you  must  have  already  started  a 
compression  sequence  with  CompressSequenceBegi  n  (1-119) 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Changing  Sequence-Compression  Parameters"  (V-2794) 

Related  Java  Methods 

quicktime.std.image.CSequence. getMaxCompressi on Si  ze( ) 


See  Also 

See  GetMaxCompressi  onSi  ze  (1-420). 


GetCSequencePrevBuffer 


Determines  the  location  of  the  previous  image  buffer  allocated  by  the  compressor. 

OSErr  GetCSequencePrevBuffer  ( 

ImageSequence  seqlD, 

GWorldPtr  *gworld  ); 
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seqlD 

Contains  the  unique  sequence  identifier  that  was  returned  by  the 
CompressSequenceBegi  n  (1-119)  function, 
gworl  d 

A  pointer  to  a  field  to  receive  a  pointer  to  the  CGraf  Port  (IV-2168)  structure  that 
describes  the  graphics  world  for  the  image  buffer.  You  should  not  dispose  of 
this  graphics  world;  the  returned  pointer  refers  to  a  buffer  that  the  Image 
Compression  Manager  is  using.  If  the  compressor  has  not  allocated  a  buffer, 
GetCSequencePrevBuf fer  returns  an  error  result  code. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Note  that  this  function  only  returns  information  about  buffers  that  were  allocated 
by  the  compressor.  You  cannot  use  this  function  to  determine  the  location  of  a 
buffer  you  have  provided. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Changing  Sequence-Compression  Parameters"  (V-2794) 

Related  Java  Methods 

qui cktime . std . image . CSequence . prevBuffer( ) , 
qui cktime . qd . QDGraphi cs . f romCSequence( ) 


GetDataHandler 


Retrieves  the  best  data  handler  component  to  use  with  a  given  data  reference. 

Component  GetDataHandler  ( 

Handle  dataRef, 

OSType  dataHandl erSubType , 

long  flags  ); 

dataRef 

A  handle  to  the  data  reference.  The  type  of  information  stored  in  the  handle 
depends  upon  the  data  reference  type  specified  by  the  dataHandl  erSubType 
parameter. 
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GetDefaultOutputVolume 


dataHandlerSubType 

Identifies  both  the  type  of  data  reference  and,  by  implication,  the  component 
subtype  value  assigned  to  the  data  handler  components  that  operate  on  data 
references  of  that  type, 
fl  ags 

Contains  flags  (see  below)  that  indicate  the  way  in  which  you  intend  to  use  the 
data  handler  component.  Note  that  not  all  data  handlers  necessarily  support  all 
services;  for  example,  some  data  handler  components  may  not  support 
streaming  writes.  Set  the  appropriate  flags  to  1. 


function  result  The  best  data  handler  component  conforming  to  the  parameters 
passed  in. 


flags  Constants 

kDataHCanRead 

You  intend  to  use  the  data  handler  component  to  read  data. 


kDataHCanWri te 

You  intend  to  use  the  data  handler  component  to  write  data. 


kDataHCanStreamingWrite 

You  intend  to  do  streaming  writes  (as  part  of  a  movie-capture  operation,  for 
example). 


Discussion 

Once  you  have  used  this  function  to  get  information  about  the  best  data  handler 
component  for  your  data  reference,  you  can  open  and  use  the  component  using 
Component  Manager  functions.  If  the  function  returns  a  value  of  N I L,  the  toolbox 
was  unable  to  find  an  appropriate  data  handler  component.  For  more  information 
about  the  error  that  caused  a  return  of  NI L,  call  GetMovi  esError  (1-492). 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Selecting  Media  Handlers"  (V-2754) 

Related  Java  Methods 

quicktime.std.movies.media.DataHandler.DataHand'lerO 


GetDef  aultOutputV  olume 


Determines  the  default  volume  level  of  the  current  sound  output  device. 
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OSErr  GetDef aul tOutputVol ume  ( 
long  *level  ); 

1  evel 

On  exit,  the  default  volume  level  of  the  current  sound  output  device.  The  values 
returned  in  the  high  and  low  words  range  from  0x0000  (silence)  to  0x0100  (full 
volume). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

You  can  call  this  function  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier.  Replaces  the  earlier  function  GetSoundVol  ume. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

For  the  corresponding  set  function,  see  SetDef  aul  tOutputVol  ume  (III— 1582). 


GetDSequencelmageBuffer 

Determines  the  location  of  the  offscreen  image  buffer  allocated  by  a  decompressor. 

OSErr  GetDSequencelmageBuffer  ( 

ImageSequence  seqlD, 

GWorldPtr  *gworld  ); 

seqlD 

Contains  the  unique  sequence  identifier  that  was  returned  by  the 
DecompressSequenceBegi  n  (1-238)  function. 

gworl  d 

A  pointer  to  a  field  to  receive  a  pointer  to  the  CGraf  Port  (IV-2168)  structure 
describing  the  graphics  world  for  the  image  buffer.  You  should  not  dispose  of 
this  graphics  world;  the  returned  pointer  refers  to  a  buffer  that  the  Image 
Compression  Manager  is  using.  It  is  disposed  of  for  you  when  the 
CDSequenceEnd  (1-77)  function  is  called.  If  the  decompressor  has  not  allocated  a 
buffer,  GetDSequencelmageBuffer  returns  an  error  result  code. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Functions  A-H 


1-409 
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Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Changing  Sequence-Decompression  Parameters" 
(V-2795) 

Related  Java  Methods 

quicktime.std.image.DSequence. getlmageBuffer ( ) , 
quicktime.qd.QDGraphics.fromDSequencelmageO 


GetDSequenceMatrix 


Gets  the  matrix  that  was  specified  for  a  decompression  sequence  by  a  call  to 
SetDSequenceMatri x  (III— 1587),  or  that  was  set  at  DecompressSequenceBegi  n  (1-238). 

OSErr  GetDSequenceMatrix  ( 

ImageSequence  seqlD, 

Matri xRecordPtr  matrix  ); 

seqlD 

Contains  the  unique  sequence  identifier  that  was  returned  by 
DecompressSequenceBegi n  (1-238). 

matri x 

Points  to  a  matrix  structure  that  specifies  how  to  transform  the  image  during 
decompression 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

See  Also 

For  the  corresponding  set  function,  see  SetDSequenceMatri  x  (III— 1587). 


GetDSequenceScreenBuffer 


Determines  the  location  of  the  offscreen  screen  buffer  allocated  by  a  decompressor. 

OSErr  GetDSequenceScreenBuffer  ( 

ImageSequence  seqlD, 

GWorldPtr  *gworld  ); 
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seqlD 

The  unique  sequence  identifier  that  was  returned  by  the 
DecompressSequenceBegi  n  (1-238)  function, 
gworl  d 

A  pointer  to  a  field  to  receive  a  pointer  to  the  CGraf  Port  (IV-2168)  structure  that 
describes  the  graphics  world  for  the  screen  buffer.  You  should  not  dispose  of 
this  graphics  world;  the  returned  pointer  refers  to  a  buffer  that  the  Image 
Compression  Manager  is  using.  It  is  disposed  of  for  you  when  the 
CDSequenceEnd  (1-77)  function  is  called.  If  the  decompressor  has  not  allocated  a 
buffer,  GetDSequenceScreenBuffer  returns  an  error  result  code. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Changing  Sequence-Decompression  Parameters" 
(V-2795) 

Related  Java  Methods 

qui ckti me . std . image . DSequence . getScreenBuf fer( ) , 
qui  cktime .  qd  .  QDG rapin'  cs  .  f romDSequenceScreen( ) 


GetFirstCallBack 

Returns  the  first  callback  event  associated  with  a  specified  time  base. 

QTCallBack  GetFirstCallBack  ( 

TimeBase  tb  ); 


tb 

Specifies  the  time  base  for  the  operation.  Your  component  can  obtain  the  time 
base  reference  from  your  Cl  ockSetT i meBase  (1-98)  function  or  from  the  Movie 
Toolbox's  GetCal  1  BackTi meBase  (1-384)  function. 

function  result  Apointertoa  Cal  1  BackRecord  (IV-2165)  structure.  Your  software  can 
pass  this  structure  to  other  functions,  such  as  Cl  ockRateChanged 
(1-97). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Functions  A-H 


1-411 


GetGraphicsImporterForDataRef 


Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Movie  Toolbox  Clock  Support  Functions"  (V-2869) 


GetGraphicsImporterForDataRef 

Locates  and  opens  a  graphics  importer  component  that  can  be  used  to  draw  the 
image  from  specified  data  reference. 

OSErr  GetGraphicsImporterForDataRef  ( 

Handle  dataRef, 

OSType  dataRefType, 

Componentlnstance  *gi  ); 

dataRef 

The  data  reference  to  be  drawn  using  a  graphics  importer  component. 
dataRefType 

The  type  of  data  reference  pointed  to  by  the  dataRef  parameter;  see  "Data 
References"  (IV-2661).  For  alias-based  data  references,  the  dataRef  handle 
contains  an  A1  iasRecord  and  dataRefType  is  set  to  rAl  i  asType. 
gi 

On  return,  contains  a  pointer  to  the  Componentlnstanceof  the  graphics  importer . 
If  no  graphics  importer  can  be  found,  this  parameter  will  be  set  to  NIL.  If 
GetGraphi  cs  Importer  For  Data  Ref  is  able  to  locate  a  graphics  importer  for  the 
data  reference,  the  returned  graphics  importer  Componentlnstance  will  already 
be  set  up  to  draw  from  the  specified  data  reference  to  the  current  port. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  tries  to  locate  a  graphics  importer  component  for  the  specified  data 
reference  by  checking  the  file  extension  (such  as  .GIF  or  .JPG),  the  Macintosh  file 
type,  and  the  MIME  type  of  the  file.  The  file  extension  is  retrieved  from  the  data 
reference  by  using  DataHGetFi  1  eName  (1-193)  to  call  the  data  handler  associated  with 
the  data  reference.  If  a  graphics  importer  cannot  be  found  using  the  file's  type,  file 
extension,  or  MIME  type,  GetGraphicsImporterForDataRef  asks  each  graphics 
importer  to  validate  the  file,  until  it  either  finds  an  importer  that  can  handle  the  file 
or  exhausts  the  list  of  possible  importers.  This  validation  attempt  can  be  quite 
time-consuming;  to  bypass  it,  call  GetGraphi  csImporterForDataRefWi  t h FI  ags  (1-413) 
instead. 
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GetGraphicsImporterForDataRefWithFlags 


Special  Considerations 

The  caller  ofGetGraphicsImporterForDataRefis  responsible  for  closing  the  returned 
Componentlnstance  using  Cl  oseComponent  (1-100).  You  must  call  Cl  oseComponent 
when  you  are  finished  with  the  importer. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Obtaining  a  Graphics  Importer  Instance"  (V-2878) 

Related  Java  Methods 

qui ckti me . std . image . Gra phi cs Importer . Graph i cs Importer! ) 


See  Also 

See  GetGraphi csImporterForDataRefWithFlags  (1-413). 


GetGraphicsImporterForDataRefWithFlags 

Locates  and  opens  a  graphics  importer  component  for  a  data  reference  with  flags 
that  control  the  search  process. 

OSErr  GetGraphi cs ImporterForDataRefWi thFl  ags  ( 

Handle  dataRef, 

OSType  dataRefType, 

Componentlnstance  *gi , 
long  flags  ); 

dataRef 

The  data  reference  to  be  drawn  using  a  graphics  importer  component. 
dataRefType 

The  type  of  data  reference  pointed  to  by  the  dataRef  parameter;  see  "Data 
References"  (IV-2661).  For  alias-based  data  references,  the  dataRef  handle 
contains  an  A1  i  asRecord  and  dataRefType  is  set  to  rAl  i  asType. 
gi 

On  return,  contains  a  pointer  to  the  Componentlnstance  of  the  graphics  importer. 
If  no  graphics  importer  can  be  found,  this  parameter  will  be  set  to  NIL.  If 
GetGraphi  csImporterForDataRefWi  thFl  ags  is  able  to  locate  a  graphics  importer 
for  the  data  reference,  the  returned  graphics  importer  Componentlnstance  will 
already  be  set  up  to  draw  from  the  specified  data  reference  to  the  current  port. 

fl  ags 

Contains  flags  (see  below)  that  control  the  graphics  importer  search  process. 
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GetGraphicsImporterForFile 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

kDontUseValidateToFindGraphicsImporter 

If  a  graphics  importer  cannot  be  found  using  the  file's  type,  file  extension,  or 
MIME  type,  give  up  immediately  without  attempting  the  slower  process  of 
asking  each  graphics  importer  to  validate  the  file. 

Discussion 

This  function  tries  to  locate  a  graphics  importer  component  for  the  specified  data 
reference  by  checking  the  file  extension  (such  as  .GIF  or  .JPG),  the  Macintosh  file 
type,  and  the  MIME  type  of  the  file.  The  file  extension  is  retrieved  from  the  data 
reference  by  using  DataHGetFi  1  eName  (1-193)  to  call  the  data  handler  associated  with 
the  data  reference.  If  a  graphics  importer  cannot  be  found  using  the  file's  type,  file 
extension,  or  MIME  type,  this  function  asks  each  graphics  importer  to  validate  the 
file,  until  it  either  finds  an  importer  that  can  handle  the  file  or  exhausts  the  list  of 
possible  importers.  This  validation  attempt  can  be  quite  time-consuming;  to  bypass 
it,  pass  kDontUseVal  i  dateToFi  ndGraphi  cs  Importer  in  the  f  1  ags  parameter. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Obtaining  a  Graphics  Importer  Instance"  (V-2878) 

Related  Java  Methods 

quickti me. std. image. Graph icsImporter.GraphicsImporterO 


See  Also 

See  GetGraphi  cs  Importer  For  Data  Ref  (I — 412). 


GetGraphicsImporterForFile 


Locates  and  opens  a  graphics  importer  component  that  can  be  used  to  draw  a 
specified  file. 

OSErr  GetGraphicsImporterForFile  ( 
const  FSSpec  *theFile, 

Componentlnstance  *gi  ); 

t  h  e  F  i  1  e 

The  file  to  be  drawn  using  a  graphics  importer  component. 
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gi 

On  return,  contains  a  pointer  to  the  Component  Instance  of  the  graphics  importer. 
If  no  graphics  importer  can  be  found  for  the  specified  file,  the  g  i  will  be  set  to 
NIL.  If  GetGraphi  cs  Importer  For  Fi  1  e  is  able  to  locate  a  graphics  importer  for  the 
file,  the  returned  graphics  importer  Componentlnstance  will  already  be  set  up  to 
draw  the  specified  file  to  the  current  port. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  first  tries  to  locate  a  graphics  importer  component  for  the  specified  file 
based  on  its  file  type.  If  it  is  unable  to  locate  a  graphics  importer  component  based 
on  the  Macintosh  file  type,  or  the  call  is  made  on  a  non-Macintosh  file, 
GetGraphicsImporterForFile  will  try  to  locate  a  graphics  importer  component  based 
on  the  file  extension  (such  as  .  J  PG  or  .  GI  F).  If  a  graphics  importer  cannot  be  found 
using  the  file's  type  or  extension,  GetGraphi  csImporterForFile  asks  each  graphics 
importer  to  validate  the  file,  until  it  either  finds  an  importer  that  can  handle  the  file 
or  exhausts  the  list  of  possible  importers.  This  validation  attempt  can  be  quite 
time-consuming.  To  bypass  the  validation  attempt,  call 

GetGraphi  cs  Importer  For  Fi  1  eWi  thFl  ags  (1-416)  instead.  The  following  code  sample 
illustrates  the  use  of  GetGraphi  cs  ImporterForFi  1  e: 

//  Get  a  graphics  importer  for  the  image  file,  determine  the  natural  size 

//  of  the  image,  and  draw  the  image 

//  See  “Discovering  QuickTime,”  page  274 

void  drawFi 1 e( const  FSSpec  *fss,  const  Rect  *boundsRect) 

{ 

Graphi cs ImportComponent  gi ; 

GetGraphi cs ImporterForFi 1 e( f ss ,  &gi ) ; 

Graphi cs I mport Set Bounds Rect (gi ,  bounds Rect ) ; 

Gr aph i cs Import Dr aw ( gi ) ; 

Cl oseComponent(gi ) ; 

} 

Special  Considerations 

The  caller  of  GetGraphi csImporterForFi  1  e  is  responsible  for  closing  the  returned 
Componentlnstance  using  Cl  oseComponent  (1-100). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Obtaining  a  Graphics  Importer  Instance"  (V-2878) 
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Related  Java  Methods 

qu i ckti me. std. image. Graph icslmporter. Graph icsImporter() 


See  Also 

See  GetGraphl  cs  Importer  For  Fi  1  eWi  thFl  ags  (1-416). 


GetGraphicsImporterForFileWithFlags 

Locates  and  opens  a  graphics  importer  component  for  a  file  with  flags  that  control 
the  search  process. 

OSErr  GetGraphicsImporterForFi 1 eWi thFl  ags  ( 
const  FSSpec  *theFile, 

Componentlnstance  *gi , 

1 ong  f 1 ags  ) ; 

t  h  e  F 1 1  e 

The  file  to  be  drawn  using  a  graphics  importer  component, 
gi 

On  return,  contains  a  pointer  to  the  Componentlnstanceof  the  graphics  importer. 
If  no  graphics  importer  can  be  found  for  the  specified  file,  the  gi  will  be  set  to 
NIL.  If  GetGraphi  cs  Importer  For  Fi  1  eWi  thFl  ags  is  able  to  locate  a  graphics 
importer  for  the  file,  the  returned  graphics  importer  Componentlnstance  will 
already  be  set  up  to  draw  the  specified  file  to  the  current  port, 
fl  ags 

Contains  flags  (see  below)  that  control  the  graphics  importer  search  process. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

kDontUseValidateToFindGraphicsImporter 

If  a  graphics  importer  cannot  be  found  using  the  file's  type  or  file  extension, 
give  up  immediately  without  using  the  slower  process  of  asking  graphics 
importers  to  validate  the  file. 

Discussion 

This  function  first  tries  to  locate  a  graphics  importer  component  for  the  specified  file 
based  on  its  file  type.  If  it  is  unable  to  locate  a  graphics  importer  component  based 
on  the  Macintosh  file  type,  or  the  call  is  made  on  a  non-Macintosh  file, 
GetGraphicsImporterForFile  will  try  to  locate  a  graphics  importer  component  based 
on  the  file  extension  (such  as  .JPG  or  .GIF).  If  a  graphics  importer  cannot  be  found 
using  the  file's  type  or  extension,  GetGraphi  cs  ImporterForFi  1  e  asks  each  graphics 
importer  to  validate  the  file,  until  it  either  finds  an  importer  that  can  handle  the  file 
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or  exhausts  the  list  of  possible  importers.  This  validation  attempt  can  be  quite 
time-consuming.  To  bypass  the  validation  attempt,  pass 
kDontUseVal  i  dateToFi  ndGraphi  cs  Importer  in  the  flags  parameter. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

See  Also 

See  GetGraphi csImporterForFile  (1-414). 


GetlmageDescriptionCT  able 


Sets  the  custom  color  table  for  an  image. 

OSErr  GetlmageDescriptionCTable  ( 
ImageDescri pti onHandl e  desc, 

CTabHandle  *ctable  ); 


desc 

A  handle  to  the  appropriate  ImageDescri  pti  on  (IV-2285)  structure, 
ctabl e 

A  pointer  to  a  field  that  is  to  receive  a  color  table  handle. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns  the  color  table  for  the  image  described  by  the 
ImageDescri  pti  on  (IV-2285)  structure  that  is  referred  to  by  the  desc  parameter.  The 
function  correctly  sizes  the  handle  for  the  color  table  it  returns. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Pixel  Maps"  (V-2789) 

Related  Java  Methods 

qui cktime . qd . Col orTabl e . f romlmageDescri pti on( ) , 
qui ckti me . std . image . ImageDescri pti  on . getCTabl e( ) 


See  Also 

For  the  corresponding  set  function,  see  SetlmageDescri  pti  onCTabl  e  (ill-1593). 
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GetlmageDescriptionExtension 

Returns  a  new  handle  with  the  data  from  a  specified  image  description  extension. 

OSErr  GetlmageDescriptionExtension  ( 

ImageDescri pti onHandl e  desc, 

Handle  *extension, 

long  idType, 

1 ong  i ndex  ) ; 

desc 

A  handle  to  the  appropriate  ImageDescri  pti  on  (IV-2285)  structure, 
extensi on 

A  pointer  to  a  field  to  receive  a  handle  to  the  returned  data.  The 
GetlmageDescri  pti  onExtensi  on  function  returns  the  extended  data  for  the 
image  described  by  the  ImageDescri  pti  on  (IV-2285)  structure  referred  toby  the 
desc  parameter.  The  function  correctly  sizes  the  handle  for  the  data  it  returns. 

i dType 

Specifies  the  extension's  type  value.  Use  this  parameter  to  determine  the  data 
type  of  the  extension.  This  parameter  contains  a  four-character  code,  similar  to 
an  OSType  field  value, 
i  ndex 

Specifies  the  extension's  index  value. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  allows  the  application  to  get  a  copy  of  a  specified  image  description 
extension.  Note  that  each  compressor  type  may  have  its  own  format  for  the 
extended  data  that  is  stored  with  an  image.  The  extended  data  is  similar  in  concept 
to  the  user  data  that  applications  can  associate  with  QuickTime  movies.  Once  you 
have  added  extended  data  to  an  image,  you  cannot  delete  it. 

Special  Considerations 

The  Image  Compression  Manager  allocates  a  new  handle  and  passes  it  back  in  the 
extension  parameter.  Your  application  should  dispose  of  the  handle  when  it  is  no 
longer  needed. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Image  Descriptions"  (V-2790) 
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Related  Java  Methods 

qui cktime . std . Image . ImageDescri pti on . getExtensi on( ) 


GetMatrixType 

Obtains  information  about  a  matrix. 

short  GetMatrixType  ( 

const  MatrixRecord  *m  ); 


Points  to  the  MatrixRecord  (IV-2304)  structure  for  this  operation. 

function  result  A  constant  (see  below)  that  defines  the  type  of  the  matrix. 

Function  Result  Constants 

i denti tyMatri xType 

The  specified  matrix  is  an  identity  matrix, 
transl ateMatri xType 

The  specified  matrix  defines  a  translation  operation, 
seal eMatri xType 

The  specified  matrix  defines  a  scaling  operation. 
scaleTransl ateMatri xType 

The  specified  matrix  defines  both  a  translation  operation  and  a  scaling 
operation. 

1 i nearMatri xType 

The  specified  matrix  defines  a  rotation,  skew,  or  shear  operation. 

1 i nearTransl ateMatri xType 

The  specified  matrix  defines  both  a  translation  operation  and  a  rotation,  skew, 
or  shear  operation. 

perspecti veMatri xType 

The  specified  matrix  defines  a  perspective  (nonlinear)  operation. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Matrices"  (V-2764) 

Related  Java  Methods 

qui ckti me . std . image . Matrix. getType( ) 
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GetMaxCompressionSize 


Determines  the  maximum  size  an  image  will  be  after  compression. 


OSErr  GetMaxCompressionSize 
Pi xMapHandl e 
const  Rect 
short 
CodecQ 
CodecType 

CompressorComponent 
1  ong 


( 

src , 

*srcRect , 
col orDepth , 
qual i ty , 
cType , 
codec , 

*size  ); 


src 

A  handle  to  the  source  image.  The  source  image  must  be  stored  in  a  pixel  map 
structure.  The  compressor  uses  only  the  image's  size  and  pixel  depth  to 
determine  the  maximum  size  of  the  compressed  image. 
srcRect 

A  pointer  to  a  rectangle  defining  the  portion  of  the  source  image  that  is  to  be 
compressed.  You  may  set  this  parameter  to  N I L  if  you  are  interested  only  in 
information  about  quality  settings.  GetCompressi  onT i me  (1-401)  then  uses  the 
bounds  of  the  source  pixel  map. 

col orDepth 

The  depth  at  which  the  image  is  to  be  compressed.  If  you  set  this  parameter  to 
0,  the  Image  Compression  Manager  determines  the  appropriate  value  for  the 
source  image.  Values  of  1, 2, 4,  8, 16, 24,  and  32  indicate  the  number  of  bits  per 
pixel  for  color  images.  Values  of  34,  36,  and  40  indicate  2-bit,  4-bit,  and  8-bit 
grayscale,  respectively,  for  grayscale  images.  Your  program  can  determine 
which  depths  are  supported  by  a  given  compressor  by  examining  the 
compressor  information  structure  returned  by  GetCodecInfo  (1-385). 
qual i ty 

A  constant  (see  below)  that  defines  the  desired  compressed  image  quality. 
cType 

You  must  set  this  parameter  to  a  valid  compressor  type  constant;  see  "Codec 
Identifiers"  (IV-2655). 

codec 

A  compressor  identifier.  Specify  a  particular  compressor  by  setting  this 
parameter  to  its  compressor  identifier.  Alternatively,  you  may  use  a  special 
identifier  (see  below).  You  can  also  specify  a  component  instance.  This  may  be 
useful  if  you  have  previously  set  some  parameter  on  a  specific  instance  of  a 


1-420 


Inside  QuickTime:  Functions  A-H 


GetMaxCompressionSize 


codec  field  and  want  to  make  sure  that  the  specified  instance  is  used  for  that 
operation. 

si  ze 

A  pointer  to  a  field  to  receive  the  size,  in  bytes,  of  the  compressed  image. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

quality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 

codecNormal Quality 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 
codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field, 
codec Los  si essQual  i  ty 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

codec  Constants 

anyCodec 

The  first  compressor  or  decompressor  of  the  specified  type. 
bestSpeedCodec 

The  fastest  compressor  or  decompressor  of  the  specified  type. 
bestFi del i tyCodec 

The  most  accurate  compressor  or  decompressor  of  the  specified  type. 
bestCompressi onCodec 

The  compressor  that  produces  the  smallest  resulting  data. 

Discussion 

This  function  returns  the  maximum  resulting  size  for  the  specified  image  and 
parameters.  Your  application  may  then  use  this  information  to  allocate  memory  for 
the  compression  operation.  The  following  code  sample  illustrates  its  use: 

//  GetMaxCompressionSize  coding  example 
//  See  “Discovering  QuickTime,"  page  286 
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PicHandle  GetQTCompressedPi ct  ( PixMapHandl e  hpmlmage) 

{ 


1  ong 
Handl e 
Ptr 

ImageDescriptionHandle 

OSErr 

Pi cHandl e 

Rect 

CodecType 

CodecComponent 

CodecQ 

short 


1 MaxCompressedSi ze  =  0; 
hCompressedData  =  NIL; 
pCompressedData ; 
hlmageDesc  =  NIL; 
nErr ; 

hpicPicture  =  NIL; 

rectlmage  =  (**hpmlmage) .bounds  ; 

dwCodecType  =  kJPEGCodecType ; 

codec  =  (CodecComponent)anyCodec; 

dwSpati al Qual i ty  =  codecNormal Qual i ty ; 

nDepth  =  0;  //  let  ICM  choose  depth 


nErr  =  GetMaxCompressi onSi ze( hpmlmage ,  &rectlmage,  nDepth, 

dwSpati al Qual i ty , 
dwCodecType , 

( Comp  res so rComponen t ) codec , 
&1 MaxCompressedSi ze ) ; 


if  (nErr  !=  noErr) 
return  NIL; 


hlmageDesc  =  (ImageDescriptionHandle)NewHandle(4) ; 
hCompressedData  =  NewHandl e( 1 MaxCompressedSi ze) ; 
if  ((hCompressedData  !=  NIL)  &&  (hlmageDesc  !=  NIL))  { 
MoveHHi (hCompressedData) ; 

HLockt hCompressedData ) ; 

pCompressedData  =  StripAddress(*hCompressedData) ; 
nErr  =  CompressImage( hpmlmage , 

&rectlmage , 
dwSpati al Qual i ty , 
dwCodecType , 
hlmageDesc , 
pCompressedData ) ; 

if  (nErr  ==  noErr)  { 

ClipRectt&rectlmage) ; 

hpicPicture  =  OpenPicturet&rectlmage) ; 

nErr  =  DecompressImagetpCompressedData , 

hlmageDesc , 
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hpmlmage , 
&rectlmage , 
&rectlmage , 
srcCopy, 
NIL) ; 

Cl osePi cturel ) ; 

} 


if  (theErr  ||  (GetHandl  eSi ze( ( Hand! e)hpi cPi cture)  == 

si zeof ( Pi cture) ) )  { 

Ki  1 1  Pi cturel hpi cPi cture) ; 
h  pi  cPi  cture  =  NIL; 

} 

} 

if  (hlmageDesc  !=  NIL) 

DisposeHandle((HandIe)hImageDesc); 

if  ( hCompressedData  !=  NIL) 

DisposeHandl e( hCompressedData ) ; 

return  hpicPicture; 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Getting  Information  About  Compressed  Data"  (V-2787) 

Related  Java  Methods 

qui cktime . std . image . QTImage . getMaxCompressi on Si ze( ) 


GetMaxLoadedT  imelnMovie 


When  a  movie  is  being  progressively  downloaded,  returns  the  duration  of  the  part 
of  a  movie  that  has  already  been  downloaded. 

OSErr  GetMaxLoadedTimelnMovie  ( 

Movie  theMovie, 
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T i meVal ue  *ti me  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  identifier  from  such 
functions  as  NewMovie  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

time 

The  duration  of  the  part  of  a  movie  that  has  already  been  downloaded.  This 
time  value  is  expressed  in  the  movie's  time  coordinate  system.  If  all  of  a  movie 
has  been  downloaded,  this  parameter  returns  the  duration  of  the  entire  movie. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

The  Movie  Toolbox  creates  a  time  table  for  a  movie  when  either 
QTMovi  eNeedsTi  meTabl  e  (11-1202)  or  GetMaxLoadedTi  melnMovi  e  is  called  for  the  movie, 
but  the  time  table  is  used  only  by  the  toolbox  and  is  not  accessible  to  applications. 
The  toolbox  disposes  of  the  time  table  when  the  download  is  complete. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "High-Level  Download  Control"  (V-2772) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . max LoadedTi melnMovi e( ) 


GetMediaCreationT  ime 

Returns  the  creation  date  and  time  stored  in  a  media. 

long  GetMediaCreationTime  ( 

Medi a  theMedi a  ) ; 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetT rackMedi  a  (1-535). 

function  result  The  media's  creation  date  and  time. 


1-424 


Inside  QuickTime:  Functions  A-H 


G  etMediaDataHandler 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Determining  Movie  Creation  and  Modification  Time" 
(V-2741) 

Related  Java  Methods 

qui ckti me . std .movi es .medi a . Medi a . getCreati onTime( ) 


GetMediaDataHandler 


Determines  a  media's  data  handler. 

DataHandler  GetMediaDataHandler  ( 

Media  theMedia, 

short  index  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 

i  ndex 

Identifies  the  data  reference.  You  provide  the  index  value  that  corresponds  to 
the  data  reference  for  which  you  want  to  retrieve  the  data  handler.  You  must 
set  this  parameter  to  1. 

function  result  A  data  handler  component  instance. 

Special  Considerations 

QuickTime  normally  takes  care  of  selecting  data  handlers  for  media.  Your 
application  should  not  need  to  call  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Selecting  Media  Handlers"  (V-2754) 

Related  Java  Methods 

qui  ckti  me .  std  .movi  es  .medi  a  .  Medi  a.getDataHandlerO 


See  Also 

For  the  corresponding  set  function,  see  SetMedi  aDataHandl  er  (III— 1594). 
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GetMediaDataHandlerDescription 

Retrieves  information  about  a  media's  data  handler. 


void  GetMediaDataHandlerDescription  ( 
Media  theMedia, 

short  index, 

OSType  *dhType, 

Str255  creatorName, 

OSType  *creatorManufacturer  ); 


theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewTrackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 

i  ndex 

Identifies  the  data  reference.  You  provide  the  index  value  that  corresponds  to 
the  data  reference  for  which  you  want  to  retrieve  the  data  handler  description. 
You  must  set  this  parameter  to  1. 
dhType 

A  pointer  to  a  field  of  data  type  OSType.  The  Movie  Toolbox  returns  the  data 
handler  type  identifier.  This  value  indicates  the  type  of  data  reference 
supported  by  this  data  handler.  This  value  also  corresponds  to  the  component 
subtype  specified  for  the  data  handler  component.  All  QuickTime  data 
references  have  a  type  value  of  ’  a  1  i  s  ’ .  If  you  don't  want  to  receive  this 
information,  set  this  parameter  to  NIL. 
creatorName 

Points  to  a  string.  The  Movie  Toolbox  returns  the  name  of  the  data  handler's 
creator.  If  you  don't  want  to  receive  this  information,  set  this  parameter  to  NIL. 

creator Manufacturer 

A  pointer  to  a  long  integer.  The  Movie  Toolbox  returns  the  4-byte  value  that 
identifies  the  manufacturer  of  the  component.  If  you  don't  want  to  retrieve  this 
information,  set  this  parameter  to  NIL. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94). 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  Movi es .  h 

Programming  summary:  "Selecting  Media  Handlers"  (V-2754) 
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Related  Java  Methods 

qui cktime . std .movi es .medi a . Medi a . getDataHandl erDescri pti on( ) 


GetMediaDataRef 


Returns  a  copy  of  a  specified  data  reference. 
OSErr  GetMediaDataRef  ( 


Medi  a 

theMedi a , 

short 

i  ndex. 

Handl e 

*dataRef , 

OSType 

♦dataRefType, 

1  ong 

♦dataRefAttributes  ) 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 
i  ndex 

The  index  value  that  corresponds  to  the  data  reference.  It  must  be  less  than  or 
equal  to  the  value  that  is  returned  by  GetMedi  aDataRefCount  (1-428). 

dataRef 

A  pointer  to  a  field  that  is  to  receive  a  handle  to  the  data  reference.  The  media 
handler  returns  a  handle  to  information  that  identifies  the  file  that  contains  this 
media's  data.  The  type  of  information  stored  in  that  handle  depends  upon  the 
value  of  the  dataRefType  parameter.  If  the  function  cannot  locate  the  specified 
data  reference,  the  handler  sets  this  returned  value  to  NIL.  Set  the  dataRef 
parameter  to  N I L  if  you  are  not  interested  in  this  information. 

dataRefType 

A  pointer  to  a  field  that  is  to  receive  the  type  of  data  reference.  If  the  data 
reference  is  an  alias,  the  media  handler  sets  this  value  to  'alts'.  Set  the 
dataRefType  parameter  to  N I L  if  you  are  not  interested  in  this  information. 
dataRefAttri butes 

A  pointer  to  a  field  that  is  to  receive  the  reference's  attribute  flags  (see  below). 
Unused  flags  are  set  to  0. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 
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dataRefAttributes  Constants 

data RefSelf Reference 

Indicates  whether  the  data  reference  refers  to  the  movie  resource's  data  file.  If 
this  flag  is  set  to  1,  the  data  reference  identifies  media  data  that  is  stored  in  the 
same  file  as  the  movie  resource. 

data RefWasNot Resolved 

Indicates  whether  the  Movie  Toolbox  resolved  the  data  reference.  If  this  flag  is 
set  to  1,  the  Movie  Toolbox  could  not  resolve  the  data  reference.  For  example, 
the  toolbox  may  be  unable  to  resolve  data  references  because  the  required 
storage  device  is  unavailable  at  the  time  a  movie  is  loaded.  If  the  data  reference 
is  unresolved,  the  Movie  Toolbox  disables  the  corresponding  track. 

Discussion 

Use  this  function  to  retrieve  information  about  a  data  reference.  For  example,  you 
might  want  to  verify  the  condition  of  a  movie's  data  references  after  loading  the 
movie  from  its  movie  file.  You  could  use  this  function  to  check  each  data  reference. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Data  References"  (V-2740) 

Related  Java  Methods 

qui ckti me . std .movi es .medi a . Medi a . get Data  Ref ( ) , 
qui ckti me . std .movi es .medi a . Data  Ref . f romMedi a ( ) 


See  Also 

For  the  corresponding  set  function,  see  SetMedi  aDataRef  (III— 1595). 


GetMediaDataRefCount 


Determines  the  number  of  data  references  in  a  media. 

OSErr  GetMediaDataRefCount  ( 

Media  theMedia, 
short  *count  ) ; 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetT rackMedi  a  (1-535). 
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count 

A  pointer  to  a  field  that  is  to  receive  the  number  of  data  references  in  the  media. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Data  References"  (V-2740) 

Related  Java  Methods 

qui  cktime .  std  .movi  es  .medi  a  .  Medi  a.getDataRefCountO 


GetMediaDataSize 


Determines  the  size,  in  bytes,  of  the  sample  data  in  a  media  segment. 

long  GetMediaDataSize  ( 

Media  theMedia, 

TimeValue  startTime, 

TimeValue  duration  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 

startTime 

A  time  value  specifying  the  starting  point  of  the  segment, 
durati on 

A  time  value  that  specifies  the  duration  of  the  segment. 
function  result  The  size,  in  bytes,  of  the  sample  data  in  the  defined  media  segment. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Media  Samples"  (V-2742) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Medi a . get Data  Si ze( ) 
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GetMediaDataSize64 

Provides  a  64-bit  version  of  GetMedi  aDataSi  ze  (1-429). 

OSErr  GetMedi aDataSi ze64  ( 

Media  theMedia, 

TimeValue  startTi me , 

TimeValue  duration, 

wi de  *dataSi ze  ) ; 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetT rackMedi  a  (1-535). 
startTime 

A  time  value  specifying  the  starting  point  of  the  segment, 
durati on 

A  time  value  that  specifies  the  duration  of  the  segment. 
dataSi ze 

The  size,  in  bytes,  of  the  sample  data  in  the  defined  media  segment. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

The  only  difference  between  this  function  and  GetMedi  aDataSi  ze  (1-429)  is  that  the 
d  a  t  a  S  i  z  e  parameter  returns  a  64-bit  integer  instead  of  the  function  returning  a  32-bit 
integer. 

Special  Considerations 

New  applications  should  use  this  function  instead  of  the  32-bit  version. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es .  h 

GetMediaDuration 

Returns  the  duration  of  a  media. 

TimeValue  GetMediaDuration  ( 

Medi a  theMedi a  ) ; 
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theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 

function  result  The  media's  duration. 

Discussion 

The  following  code  sample  illustrates  the  use  of  GetMedi  aDurati  on: 

//  GetMediaDuration  coding  example 
//  See  “Discovering  QuickTime,”  page  89 
void  CreateMyVideoTrack  (Movie  movie) 

{ 

Track  track; 

Media  media; 

Rect  rect  =  {0,  0,  100,  320}; 

track  =  NewMovi eTrack(movi e , 

FixRati  o(  rect .  ri  ght ,  1), 

FixRati o( rect . bottom,  1), 
kNoVol ume) ; 

media  =  NewTrackMedia(track, 

Vi deoMedi aType , 

600,  //  video  time  scale 

NIL,  NIL); 

Begi nMedi a  Ed i ts (medi a ) ; 

MyAddVi deoSampl esToMedi a (medi a ,  &rect ) ; 

EndMedi a  Ed i ts (medi a ) ; 

InsertMediaIntoTrack(track, 

0, 

0, 

GetMedi aDurati on(medi a) , 
k  F  i  x  1 ) ; 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Media  Time"  (V-2735) 


//  assemble  data 

//  track  start  time 
//  media  start  time 

//  normal  speed 
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Related  Java  Methods 

qui ckti me . std .movi es .medi a . Medi a . get Du  rati  on ( ) 


GetMediaHandler 


Obtains  a  reference  to  a  media  handler  component. 

Medi aHandl er  GetMediaHandler  ( 

Medi a  theMedi a  ) ; 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetT rackMedi  a  (1-535). 

function  result  A  media  handler  component  instance. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Selecting  Media  Handlers"  (V-2754) 

Related  Java  Methods 

qui ckti me . std . qt components .Ti meCoder . f romMedi a ( ) , 
qu i ckti me. std. mo vies. media. Medi a. getHandlerO, 
qui ckti me. std. mo vies. media. Music Media. getMusicHandlerO, 
qui ckti me. std. mo vies. media. Video Media. getVideoHandlert ) , 
qui ckti me. std. mo vies. media. Sound Media. getSoundHandlert ) , 
qui ckti me. std. mo vies. media. Sprite Medi a. getSpriteHandlert ) , 
quicktime.std.movies.media.ThreeDMedia.getThreeDHandler( ) , 
quicktime.std.movies.media.TextMedia.getTextHandlert ) , 
quicktime.std.movies.media.TimeCodeMedia.getTimeCodeHandlerO 

See  Also 

See  Medi  aSetGraphi  csMode  (11-892).  For  the  set  function  corresponding  to 
GetMedi  aHandl  er,  see  SetMedi  aHandl  er  (III — 1598). 


GetMediaHandlerDescription 

Retrieves  information  about  a  media  handler, 
void  GetMediaHandlerDescription  ( 
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Media  theMedia, 

OSType  *mediaType, 

Str255  creatorName, 

OSType  *creatorManuf acturer  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 

medi aType 

A  pointer  to  a  field  in  which  the  Movie  Toolbox  returns  the  media  type 
identifier  (see  below).  This  value  indicates  the  type  of  media  supported  by  this 
media  handler.  This  value  also  corresponds  to  the  component  subtype 
specified  for  the  media  handler  component.  If  you  don't  want  to  receive  this 
information,  set  the  medi  aType  parameter  to  NIL. 
creatorName 

Points  to  a  string.  The  Movie  Toolbox  returns  the  name  of  the  media  handler's 
creator.  If  you  don't  want  to  receive  this  information,  set  this  parameter  to  NIL. 
creatorManufacturer 

A  pointer  to  a  long  integer.  The  Movie  Toolbox  returns  the  4-byte  value  that 
identifies  the  manufacturer  of  the  component.  If  you  don't  want  to  retrieve  this 
information,  set  this  parameter  to  NIL. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

mediaType  Constants 

Vi deoMedi aType 
Video  media. 

SoundMedi aType 
Sound  media. 

TextMedi aType 
Text  media. 

Discussion 

The  following  code  sample  illustrates  the  use  of  GetMedi  aHandl  erDescri  pti  on: 

//  GetMediaHandlerDescription  coding  example 
//  See  “Discovering  QuickTime,”  page  363 
Movie  moviel; 

TimeValue  1 01 dDurati on ; 

Movie  movie2; 

long  llndex,  1 Ori gTrackCount ,  1 Referencelndex; 
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Track  track,  trackSprite; 

//  get  the  first  track  in  original  movie  and  position  at  the  start 
trackSprite  =  GetMovi elndTracktmovi el ,  1); 

SetMovi eSel ecti on (movi el ,  0,  0); 

//  remove  all  tracks  except  video  in  modifier  movie 
for  (llndex  =  1;  llndex  <=  GetMovi eTrackCounttmovi e2) ;  1 Index++)  { 
Track  track  =  GetMovi elndTracktmovi e2 ,  llndex); 

OSType  dwType; 

GetMediaHandlerDescriptiontGetT  rackMedi a ( track) , 

&dwType ,  NIL,  NIL); 
if  (dwType  !=  Vi deoMedi aType )  { 

DisposeMovieTrackt track) ; 

1  Index- - ; 

} 

} 

//  add  the  modifier  track  to  original  movie 
lOldDuration  =  GetMovieDurationtmoviel) ; 

AddMovieSelectiontmoviel,  movie2) ; 

DisposeMovie(movie2) ; 

//  truncate  the  movie  to  the  length  of  the  original  track 
Del eteMovi eSegmenttmovi el,  lOldDuration, 

GetMovieDuration(moviel)  -  lOldDuration); 

//  associate  the  modifier  track  with  the  original  sprite  track 
track  =  GetMovi elndTracktmovi el ,  1 Ori gTrackCount  +  1); 
AddTrackReferencettrackSprite,  track,  kTrackModi f i erReference , 

&1 Referencelndex) ; 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Selecting  Media  Handlers"  (V-2754) 

Related  Java  Methods 

quicktime.std.movies.media.Media.getHandlerDescriptiont) 
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GetMedialnputMap 

Returns  a  copy  of  the  input  map  associated  with  a  specified  media. 

OSErr  GetMedialnputMap  ( 

Media  theMedia, 

QTAtomContai ner  *inputMap  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 

i nputMap 

The  media  input  map  for  this  operation.  You  must  dispose  of  the  map  referred 
to  by  this  parameter  when  you  are  done  with  it  using  QTDi  sposeAtomContai  ner 
(11-1164). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

Use  this  function  to  specify  the  media  you  want  to  get  so  you  can  modify  its  input 
map,  as  illustrated  below: 

//  GetMedialnputMap  coding  example 
//  See  “Discovering  QuickTime,”  page  365 
#define  klmagelndexToOverride  1 

Movie  moviel,  movie2; 

long  1 Referencelndex,  1 ImagelndexToOverride; 

Track  trackSprite; 

QTAtomContai ner  qtacInputMap; 

QTAtom  1 InputAtom; 

OSType  dwInputType; 

Media  mediaSprite; 

//  get  the  sprite  media’s  input  map 
mediaSprite  =  GetTrackMedi a (trackSpri te) ; 

Get  Med  i  a  InputMapImedi  aSprite,  &q  tad  nputMap); 

//  add  an  atom  for  a  modifier  track 

QTInsertChi IdlqtacInputMap,  kParentAtomlsContai ner ,  kTrackModi fi er Input , 

1 Referencelndex,  0,  0,  NIL,  &1 InputAtom) ; 
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//  add  a  child  atom  to  specify  the  input  type 
dwInputType  =  kTrackModi f i erTypelmage ; 

QTInsertChildtqtacInputMap,  1 InputAtom ,  kTrackModi fi erType ,  1,  0, 
si zeoft dwInputType ) ,  &dwInputType ,  NIL); 

//  add  a  second  child  atom  to  specify  index  of  image  to  override 
1 ImagelndexToOverri de  =  EndianS16_NtoB(kImageIndexTo0verride) ; 
QTInsertChildtqtacInputMap,  llnputAtom,  kSpri teProperty Imagelndex ,  1,  0, 
si zeoft 1 ImagelndexToOverri de) ,  &1 ImagelndexToOverri de ,  NIL); 

//  update  the  sprite  media's  input  map 
SetMedi alnputMaptmediaSprite,  qtacInputMap) ; 

QTDi sposeAtomContai nert qtacInputMap) ; 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Manipulating  Media  Input  Maps"  (V-2753) 

Related  Java  Methods 

quicktime.std.movies.media.Media.getlnputMapt), 
qui ckti me . std .movi es . AtomContai ner . f romMedi a  Inputt ) 

See  Also 

For  the  corresponding  set  function,  see  SetMedialnputMap  (III— 1599). 


GetMediaLanguage 


Returns  a  media's  localized  language  or  region  code. 

short  GetMediaLanguage  ( 

Medi a  theMedi a  ) ; 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetT rackMedi  a  (1-535). 

function  result  The  media's  language  or  region  code. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Alternate  Tracks"  (V-2738) 

Related  Java  Methods 

qui  cktime .  std  .movi  es  .medi  a  .  Medi  a. get  Language!) 


See  Also 

For  the  corresponding  set  function,  see  SetMedi  aLanguage  (III— 1600).  See  Inside 
Macintosh:  Text  (listed  in  the  bibliography)  for  more  information  about  language 
and  region  codes. 


GetMediaModif  icationT  ime 


Returns  a  media's  modification  date  and  time. 

long  GetMediaModificationTime  ( 

Media  theMedia  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 

function  result  The  media's  modification  date  and  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Determining  Movie  Creation  and  Modification  Time" 
(V-2741) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Medi a . get Modi f i cati onTimeC ) 


GetMediaNextlnterestingTime 


Searches  for  times  of  interest  in  a  media. 


void  GetMediaNextlnterestingTime  ( 
Media  theMedia, 

short  i nteresti ngTimeFl ags , 

TimeValue  time. 

Fixed  rate. 
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TimeValue  *i nteresti ngTi me , 

TimeValue  *i nteresti ngDurati on  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetT rackMedi  a  (1-535). 
i nteresti ngTi me FI  a gs 

Contains  flags  (see  below)  that  determine  the  search  criteria.  Note  that  you  may 
set  only  one  of  the  nextT i  meMedi  aSampl  e,  nextTi  meMedi  aEdi  t  or 
nextTi meSyncSampl  e  flags  to  1.  Set  unused  flags  to  0. 

time 

Specifies  a  time  value  that  establishes  the  starting  point  for  the  search.  This  time 
value  must  be  expressed  in  the  media's  time  scale. 

rate 

The  search  direction.  Negative  values  cause  the  Movie  Toolbox  to  search 
backward  from  the  starting  point  specified  in  the  time  parameter.  Other  values 
cause  a  forward  search, 
i nteresti ngT i me 

A  pointer  to  a  time  value.  The  Movie  Toolbox  returns  the  first  time  value  it  finds 
that  meets  the  search  criteria  specified  in  the  flags  parameter.  This  time  value 
is  in  the  media's  time  scale.  If  there  are  no  times  that  meet  the  search  criteria  you 
specify,  the  Movie  Toolbox  sets  this  value  to  -1.  Set  this  parameter  to  N I L  if  you 
are  not  interested  in  this  information. 

i nteresti ngDurati on 

A  pointer  to  a  time  value.  The  Movie  Toolbox  returns  the  duration  of  the 
interesting  time.  This  time  value  is  in  the  media's  time  coordinate  system.  Set 
this  parameter  to  N I L  if  you  don't  want  this  information;  this  lets  the  function 
works  faster. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94). 

interestingTimeFlags  Constants 

nextT i meMedi aSampl e 

Set  this  flag  to  1  to  search  for  the  next  sample. 
nextT i meMedi aEdi t 

Set  this  flag  to  1  to  search  for  the  next  group  of  samples. 
nextT i meSyncSampl e 

Set  this  flag  to  1  to  search  for  the  next  sync  sample. 
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nextTimeEdgeOK 

Set  this  flag  to  1  to  accept  information  about  elements  that  begin  or  end  at  the 
time  specified  by  the  ti  me  parameter.  When  this  flag  is  set  the  function  returns 
valid  information  about  the  beginning  and  end  of  a  media. 

Discussion 

Some  compression  algorithms  conserve  space  by  eliminating  duplication  between 
consecutive  frames  in  a  sample.  They  do  this  by  deriving  frames  from  sync  samples, 
which  don't  rely  on  preceding  frames  for  content. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Finding  Interesting  Times"  (V-2735) 

Related  Java  Methods 

qui  cktime .  std  .movi  es  .medi  a  .  Medi  a  .  get  Next  Interest!'  ngTimel ) 


GetMediaPlayHints 

Undocumented 

void  GetMediaPlayHints  ( 

Media  theMedia, 
long  *flags  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 
fl  ags 

A  pointer  to  flags  (see  below). 

function  result  Undocumented 

flags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 
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Related  Java  Methods 

qui ckti me . std .movi es .medi a . Medi a . get PI  ay Hi nts ( ) 


See  Also 

For  the  corresponding  set  function,  see  SetMedi aPl  ayHi  nts  (III— 1601). 


GetMediaPreferredChunkSize 


Retrieves  the  maximum  chunk  size  for  a  media. 

OSErr  GetMediaPreferredChunkSize  ( 

Media  theMedia, 

long  *maxChunkSi ze  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetT rackMedi  a  (1-535). 

maxChunkSi ze 

Specifies  a  field  to  receive  the  maximum  chunk  size,  in  bytes. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Adding  Samples  to  Media  Structures"  (V-2752) 

Related  Java  Methods 

qu i ckti me. std. mo vies. media. Medi a. getPreferredChunkSizet) 


See  Also 

For  the  corresponding  set  function,  see  SetMedi  aPreferredChunkSi  ze  (III— 1603). 


GetMediaPropertyAtom 


Retrieves  the  property  atom  container  of  a  media  handler. 

OSErr  GetMediaPropertyAtom  ( 

Media  theMedia, 

QTAtomContai ner  *propertyAtom  ); 
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theMedi a 

A  reference  to  the  media  handler  for  this  operation. 
propertyAtom 

A  pointer  to  a  QT  atom  container.  On  return,  the  atom  container  contains  the 
property  atoms  for  the  track  associated  with  the  media  handler. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

You  can  call  GetMedi  a  PropertyAtom  to  retrieve  the  properties  of  the  track  associated 
with  the  specified  media  handler.  The  contents  of  the  returned  QT  atom  container 
are  defined  by  the  media  handler. 

Special  Considerations 

The  caller  is  responsible  for  disposing  of  the  QT  atom  container. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Media  Handler  Properties"  (V-2755) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Medi a . getPropertyAtom( ) , 
qui cktime . std .movi es . AtomContai ner . f romMedi a  Property ( ) 


See  Also 

For  the  corresponding  set  function,  see  SetMedi  aPropertyAtom  (III— 1604). 


GetMediaQuality 


Returns  a  media's  quality  level  value. 

short  GetMediaQuality  ( 

Media  theMedi a  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 

function  result  A  short  integer  whose  bits  indicate  quality  constants  (see  below). 
More  than  one  of  these  bits  may  be  set  to  1. 
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Function  Result  Constants 

0x00000001 

A  pixel  depth  of  1  bit  per  pixel. 

0x00000010 

A  pixel  depth  of  2  bits  per  pixel. 

0x00000100 

A  pixel  depth  of  4  bits  per  pixel. 

0x00001000 

A  pixel  depth  of  8  bits  per  pixel. 

0x00010000 

A  pixel  depth  of  16  bits  per  pixel. 

0x00100000 

A  pixel  depth  of  32  bits  per  pixel, 
medi aQual i tyDraft 

The  lowest  quality  level  (Bits  6  and  7  =  0). 
medi aQual i tyNormal 

An  acceptable  quality  level  (Bits  6  and  7  =  1). 
medi aQual i tyBetter 

A  higher  quality  level  (Bits  6  and  7  =  2). 
medi aQual i tyBest 

The  highest  quality  level  (Bits  6  and  7  =  3). 

Discussion 

The  Movie  Toolbox  uses  this  quality  value  to  influence  which  track  of  a  movie  it 
selects  to  play  on  a  given  computer.  This  even  applies  to  sound  media.  The 
low-order  6  bits  specify  pixel  depths  and  the  upper  2  bits  specify  quality  levels.  If  a 
bit  is  set  to  1,  the  media  can  be  played  at  the  corresponding  depth  and  quality  level. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Alternate  Tracks"  (V-2738) 

Related  Java  Methods 

qui ckti me . std .movi es .medi a . Medi a . getQual i ty ( ) 

See  Also 

For  the  corresponding  set  function,  see  SetMedi  aQual  i  ty  (III— 1605). 
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GetMediaSample 


Returns  a  sample  from  a  movie  data  file. 

OSErr  GetMediaSample  ( 

Medi  a 
Hand! e 
1  ong 
1  ong 

T i meVal ue 
T i meVal ue 
T i meVal ue 

Samp! eDescri pti onHandl e 
1  ong 
1  ong 
1  ong 
short 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 
dataOut 

A  handle.  The  GetMedi  aSampl  e  function  returns  the  sample  data  into  this 
handle.  The  function  increases  the  size  of  this  handle,  if  necessary.  You  can 
specify  the  handle's  maximum  size  with  the  maxSi  zeToGrow  parameter. 
maxSi zeToGrow 

The  maximum  number  of  bytes  of  sample  data  to  be  returned.  The 
GetMedi  aSampl  e  function  does  not  increase  the  handle  specified  by  the  dataOut 
parameter  to  a  size  greater  than  you  specify  with  this  parameter.  Set  this  value 
to  0  to  enforce  no  limit  on  the  number  of  bytes  to  be  returned. 

si  ze 

A  pointer  to  a  long  integer.  The  GetMedi  aSampl  e  function  updates  the  field 
referred  to  by  the  size  parameter  with  the  number  of  bytes  of  sample  data 
returned  in  the  handle  specified  by  the  dataOut  parameter.  Set  this  parameter 
to  N I L  if  you  are  not  interested  in  this  information. 

ti  me 

The  starting  time  of  the  sample  to  be  retrieved.  You  must  specify  this  value  in 
the  media's  time  scale, 
sampl  eTime 

A  pointer  to  a  time  value.  The  GetMedi  aSampl  e  function  updates  this  time  value 
to  indicate  the  actual  time  of  the  returned  sample  data.  (The  returned  time  may 
differ  from  the  time  you  specified  with  the  time  parameter.  This  will  occur  if  the 


theMedi a , 
dataOut , 
maxSi zeToGrow, 

*si ze , 
ti  me , 

*sampl eT i me , 

*durati on  Per Sampl e , 
sampl eDescri pti onH , 
*sampl eDescri pti onlndex, 
maxNumberOf Sampl es , 
*number0f Sampl es , 
*sampleFlags  ); 
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time  you  specified  falls  in  the  middle  of  a  sample.)  If  you  are  not  interested  in 
this  information,  set  this  parameter  to  NIL. 

durati onPerSampl e 

A  pointer  to  a  time  value.  The  Movie  Toolbox  returns  the  duration  of  each 
sample  in  the  media.  This  time  value  is  expressed  in  the  media's  time  scale.  Set 
this  parameter  to  0  if  you  don't  want  this  information. 

sampleDescriptionH 

A  handle  to  a  Sampl  eDescri  pti  on  (IV-2414)  structure.  The  GetMedi  aSampl  e 
function  returns  the  sample  description  corresponding  to  the  returned  sample 
data.  The  function  resizes  this  handle  as  appropriate.  If  you  don't  want  a 
Sampl  eDescri  pti  on  structure,  set  this  parameter  to  NIL. 
sampl eDescri pti onlndex 

A  pointer  to  a  long  integer.  The  GetMediaSample  function  returns  an  index  value 
to  the  Sampl  eDescri  pti  on  (IV-2414)  structure  that  corresponds  to  the  returned 
sample  data.  You  can  retrieve  the  structure  by  calling 
GetMedi  aSampl  eDescri  pti  on  (IM45)  and  passing  this  index  in  the  descH 
parameter.  If  you  don't  want  this  information,  set  this  parameter  to  NIL. 

maxN umber Of Sampl es 

The  maximum  number  of  samples  to  be  returned.  The  Movie  Toolbox  does  not 
return  more  samples  than  you  specify  with  this  parameter.  If  you  set  this 
parameter  to  0,  the  Movie  Toolbox  uses  a  value  that  is  appropriate  for  the 
media,  and  returns  that  value  in  the  field  referenced  by  the  numberOfSamples 
parameter. 

numberOfSampl es 

A  pointer  to  a  long  integer.  The  GetMedi  aSampl  e  function  updates  the  field 
referred  to  by  this  parameter  with  the  number  of  samples  it  actually  returns.  If 
you  don't  want  this  information,  set  this  parameter  to  NIL. 
sampl eFl ags 

A  pointer  to  a  short  integer  in  which  GetMedi  aSampl  e  returns  flags  (see  below) 
that  describe  the  sample.  Unused  flags  are  set  to  0.  If  you  don't  want  this 
information,  set  this  parameter  to  NIL. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

sampleFlags  Constants 

medi aSampl eNot Sync 

This  flag  is  set  to  1  if  the  sample  is  not  a  sync  sample  and  to  0  if  the  sample  is  a 
sync  sample. 


1-444 


Inside  QuickTime:  Functions  A-H 


GetMediaSampleCount 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Adding  Samples  to  Media  Structures"  (V-2752) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Medi a . getSampI  e( ) 


See  Also 

You  can  add  samples  to  movie  data  files  with  AddMedi  aSampl  e  (1-27). 


GetMediaSampleCount 


Determines  the  number  of  samples  in  a  media. 

long  GetMediaSampleCount  ( 

Media  theMedia  ); 

theMedi a 

The  media  for  this  operation.  You  obtain  this  media  identifier  from  such 
functions  as  NewTrackMedia  (11-1120)  and  GetTrackMedi  a  (1-535). 

function  result  The  number  of  samples  in  the  media. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Media  Samples"  (V-2742) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Medi a . getSampI eCount( ) 


GetMediaSampleDescription 


Retrieves  a  Sampl  eDescri  pti  on  (IV-2414)  structure  from  a  media. 

void  GetMediaSampleDescription  ( 

Media  theMedia, 

long  index, 

Sampl eDescri pti onHandl e  descH  ); 
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theMedi a 

The  media  for  this  operation.  You  obtain  this  media  identifier  from  such 
functions  as  NewT rackMedi  a  (11-1120)  and  GetT rackMedi  a  (1-535). 
i  ndex 

The  index  of  the  Sampl  eDescri  pti  on  (IV-2414)  structure  to  retrieve.  This  index 
corresponds  to  the  structure  itself,  not  to  the  samples  in  the  media. 

descH 

Specifies  a  handle  that  is  to  receive  the  Sampl  eDescri  pti  on  (IV-2414)  structure. 
The  Movie  Toolbox  correctly  resizes  this  handle  for  the  returned  structure.  If 
there  is  no  description  for  the  specified  index,  the  function  returns  this  handle 
unchanged.  Your  application  must  allocate  and  dispose  of  this  handle. 

Discussion 

The  Movie  Toolbox  identifies  a  media's  sample  descriptions  with  an  index  value, 
ranging  from  1  to  the  number  of  sample  descriptions  in  the  media.  Sample 
description  indexes  provide  a  convenient  way  to  access  each  sample  description  in 
a  media.  You  can  access  error  returns  from  this  function  through  GetMovi esError 
(I — 492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error  Codes"  (IV-2663). 

Special  Considerations 

The  format  of  sample  descriptions  differs  by  media  type.  Sample  descriptions  for 
image  data  are  defined  by  ImageDescri  pti  on  (IV-2285)  structures.  Sample 
descriptions  for  sound  are  defined  by  SoundDescri  pti  on  (IV-2449)  structures. 
Sample  descriptions  for  text  are  defined  by  TextDescri  pti  on  (IV-2474)  structures. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Media  Samples"  (V-2742) 

Related  Java  Methods 

quicktime.std.movies.media.Media.getSampleDescriptionO, 
qu i c kt i me. std. mo vies. media. Music Media. getMusi eDescri pti on ( ) , 
qu ickti me. std. mo vies. media. Video Media. getlmageDescriptiont), 
qui ckti me. std. mo vies. media. Sound Media. getSoundDescriptiont), 
qu ickti me. std. mo vies. media. SpriteMed i a. getSoundDescriptiont), 
qui ckti me . std .movi es .medi a  .ThreeDMedi  a.getThreeDDescriptionO  , 
quicktime.std.movies.media.TextMedia.getTextDescriptiont ) , 
qui ckti me . std .movi es .medi a .Ti meCodeMedi a . getTimeCodeDescri pti on ( ) 

See  Also 

For  the  corresponding  set  function,  see  SetMedi  aSampl  eDescri  pti  on  (III— 1606). 
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GetMediaSampleDescriptionCount 

Returns  the  number  of  sample  descriptions  in  a  media. 

long  GetMediaSampleDescriptionCount  ( 

Media  theMedia  ); 

theMedi a 

The  media  for  this  operation.  You  obtain  this  media  identifier  from  such 
functions  as  NewTrackMedia  (11-1120)  and  GetTrackMedi  a  (1-535). 

function  result  The  number  of  sample  descriptions  in  the  media. 

Special  Considerations 

The  format  of  sample  descriptions  differs  by  media  type.  Sample  descriptions  for 
image  data  are  defined  by  ImageDescri  pti  on  (IV-2285)  structures.  Sample 
descriptions  for  sound  are  defined  by  SoundDescri  pti  on  (IV-2449)  structures. 
Sample  descriptions  for  text  are  defined  by  TextDescri  pti  on  (IV-2474)  structures. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Media  Samples"  (V-2742) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Medi a . get Samp! eDescri pti onCounti ) 


GetMediaSampleReference 


Obtains  reference  information  about  samples  that  are  stored  in  a  movie  data  file. 


Medi  a 
1  ong 
1  ong 

T  i  meVal ue 
T  i  meVal ue 
T  i  meVal ue 

Sampl  eDescri pti onHand 
1  ong 
1  ong 
1  ong 
short 


( 

theMedi a , 

*data0f f set , 

*si ze , 
time , 

*sampl eTime, 

*durati on  Per Sampl e , 
sampl eDescri pti onH  , 
*sampl eDescri pti on  Index, 
maxNumberOf Sampl es , 
*number0f Sampl es , 
*sampleFlags  ); 
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theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetT rackMedi  a  (1-535). 
dataOffset 

A  pointer  to  a  long  integer.  GetMedi  a  Sampl  e  Reference  updates  the  field  referred 
to  by  this  parameter  with  the  offset  to  the  sample  data.  This  parameter  is  used 
differently  by  each  media  handler.  For  example,  the  hierarchical  file  system 
(HFS)  media  handler  returns  an  offset  into  the  file  that  contains  the  media  data. 

si  ze 

A  pointer  to  a  long  integer.  GetMedi  a  Sampl  e  Reference  updates  the  field  referred 
to  by  the  size  parameter  with  the  number  of  bytes  of  sample  data  referred  to  by 
the  reference.  Set  this  parameter  to  N I L  if  you  are  not  interested  in  this 
information. 

time 

The  starting  time  of  the  sample  reference  to  be  retrieved.  You  must  specify  this 
value  in  the  media's  time  scale, 
sampl eT i me 

A  pointer  to  a  time  value.  GetMedi  aSampl  eReference  updates  this  time  value  to 
indicate  the  actual  time  of  the  returned  sample  data.  (The  returned  time  may 
differ  from  the  time  you  specified  with  the  time  parameter.  This  will  occur  if  the 
time  you  specified  falls  in  the  middle  of  a  sample.)  If  you  are  not  interested  in 
this  information,  set  this  parameter  to  NIL. 

durati onPerSampl e 

A  pointer  to  a  time  value.  The  Movie  Toolbox  returns  the  duration  of  each 
sample  in  the  media.  This  time  value  is  expressed  in  the  media's  time  scale.  Set 
this  parameter  to  0  if  you  don't  want  this  information, 
sampl eDescriptionH 

A  handle  to  a  Sampl  eDescri  pti  on  (IV-2414)  structure.  GetMedi  aSampl  eReference 
returns  the  structure  corresponding  to  the  returned  sample  data.  The  function 
resizes  this  handle  as  appropriate.  If  you  don't  want  the  Sampl  eDescri  pti  on 
structure,  set  this  parameter  to  NIL. 

sampl eDescri pti on  Index 

A  pointer  to  a  long  integer.  GetMedi  aSampl  eReference  returns  an  index  value  to 
the  Sampl  eDescri  pti  on  (IV-2414)  structure  that  corresponds  to  the  returned 
sample  data.  To  retrieve  the  media  sample  description,  pass  this  index  in  the 
descH  parameter  of  GetMedi  aSampl  eDescri  pti  on  (1-445).  If  you  don't  want  this 
information,  set  this  parameter  to  NIL. 
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maxNumberOf Sampl es 

The  maximum  number  of  samples  to  be  returned.  The  Movie  Toolbox  does  not 
return  a  reference  that  refers  to  more  samples  than  you  specify  with  this 
parameter.  If  you  set  this  parameter  to  0,  the  Movie  Toolbox  uses  a  value  that 
is  appropriate  for  the  media  and  returns  that  value  in  the  field  referenced  by  the 
numberOfSampl  es  parameter. 
numberOf Sampl es 

A  pointer  to  a  long  integer.  GetMedi  aSampl  eReference  updates  the  field  referred 
to  by  this  parameter  with  the  number  of  samples  referred  to  by  the  returned 
reference.  If  you  don't  want  this  information,  set  this  parameter  to  NIL. 

sampl  e FI  ags 

A  pointer  to  a  short  integer  in  which  GetMedi  aSampl  eReference  returns  flags  (see 
below)  that  describe  the  samples  referred  to  by  the  returned  reference.  Unused 
flags  are  set  to  0.  If  you  don't  want  this  information,  set  this  parameter  to  NIL. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

sampleFlags  Constants 

medi aSampl eNotSync 

This  flag  is  set  to  1  if  the  sample  is  not  a  sync  sample  or  to  0  if  the  sample  is  a 
sync  sample. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Adding  Samples  to  Media  Structures"  (V-2752) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Medi a . get Sampl eReference! ) 


See  Also 

See  GetMedi  aSampl  eReferences  (1-449). 


GetMediaSampleReferences 


Obtains  reference  information  about  groups  of  samples  that  are  stored  in  a  movie. 

OSErr  GetMediaSampleReferences  ( 

Media  theMedia, 

TimeValue  time. 
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TimeVal ue 

SampleDescriptionHandle 
1  ong 
1  ong 
1  ong 

SampleReferencePtr 


*sampleTime, 
sampl eDescri pti onH , 

*s amp leDescripti on  Index, 
maxNumberOf Entri es , 
*actual Number of Entri es , 
sampl eRefs  ) ; 


theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetT rackMedi  a  (1-535). 

time 

The  starting  time  of  the  sample  references  to  be  retrieved.  You  must  specify  this 
value  in  the  media's  time  scale. 

sampl eT i me 

A  pointer  to  a  time  value.  Get  Med  i  a  Sampl  e  References  updates  this  time  value  to 
indicate  the  actual  time  of  the  first  returned  sample  data.  If  you  are  not 
interested  in  this  information,  set  this  parameter  to  NIL. 
sampl eDescri pti onH 

Ahandle  to  a  Sampl  eDescri  pti  on  (IV-2414)  structure.  GetMedi  aSampl  eReference 
(1-447)  returns  the  structure  corresponding  to  the  returned  sample  data.  The 
function  resizes  this  handle  as  appropriate.  GetMedi  aSampl  eReferences  only 
returns  a  single  sample  description.  If  the  sample  description  changes  within 
the  media,  GetMedi  aSampl  eReferences  returns  only  as  many  samples  as  use  a 
single  sample  description.  You  must  call  it  again  to  get  the  next  group  of 
samples  using  the  next  sample  description.  If  you  don't  want  the 
Sampl  eDescri  pti  on  structure,  set  this  parameter  to  NIL. 

sampl eDescri pti on  Index 

A  pointer  to  a  long  integer.  GetMediaSampleReferences  returns  an  index  value  to 
the  Sampl  eDescri  pti  on  (IV-2414)  structures  that  correspond  to  the  returned 
sample  data.  Use  this  index  to  retrieve  the  media  sample  descriptions  with 
GetMedi  aSampl  eDescri  pti  on  (1-445).  If  you  don't  want  this  information,  set  this 
parameter  to  NIL. 

maxNumberOf Entri es 

The  maximum  number  of  entries  to  be  returned.  The  sample  references  pointer 
provided  by  the  sampl  eRefs  parameter  must  be  large  enough  to  receive  the 
number  of  entries  specified  by  this  parameter.  The  toolbox  does  not  return 
more  entries  than  you  specify  with  this  parameter.  It  may,  however,  return 
fewer. 
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actual N umber of Entri  es 

A  pointer  to  a  long  integer.  GetMedi  aSampl  eReferences  updates  the  field 
referred  to  by  this  parameter  with  the  number  of  entries  referred  to  by  the 
returned  reference, 
sampl eRef s 

A  pointer  to  the  number  of  Sampl  eReferenceRecord  (IV-2416)  structures 
specified  in  the  maxNumberOf  Entri  es  parameter.  On  return  from  this  call,  the 
number  of  sample  reference  records  indicated  by  the  value  returned  in 
actual  Numberof  Entri  es  will  be  filled  in. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

Using  this  function  instead  of  GetMedi  aSampl  eReference  (1-447)  can  greatly  increase 
the  performance  of  operations  that  need  access  to  information  about  each  sample  in 
a  movie.  No  information  is  returned  from  this  call  that  wasn't  previously  available 
from  GetMedi  aSampl  eReference. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Adding  Samples  to  Media  Structures"  (V-2752) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Medi a . get Sampl eReferences ( ) 


See  Also 

See  GetMedi  aSampl  eReference  (1-447)  and  GetMedi  aSampl  eReferences64  (1-451). 


GetMediaSampleReferences64 


Provides  a  64-bit  version  of  GetMedi  aSampl  eReferences  (1-449). 

OSErr  GetMedi aSampl eReferences64  ( 

Media  theMedia, 

TimeValue  time, 

TimeValue  *sampleTime, 

Sampl eDescri pti onHandl e  sampl eDescri pti onH  , 
long  *sampl eDescriptionlndex, 

long  maxNumberOf Entri es  , 

long  *actual Numberof Entri es , 
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Sampl eReference64Ptr  sampleRefs  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetT rackMedi  a  (1-535). 

time 

The  starting  time  of  the  sample  references  to  be  retrieved.  You  must  specify  this 
value  in  the  media's  time  scale, 
sampl eT i me 

A  pointer  to  a  time  value.  GetMedi  aSampl  eReferences64  updates  this  time  value 
to  indicate  the  actual  time  of  the  first  returned  sample  data.  If  you  are  not 
interested  in  this  information,  set  this  parameter  to  NIL. 
sampl eDescriptionH 

A  handle  to  a  Sampl  eDescri  pti  on  (IV-2414)  structure.  GetMedi  aSampl  eRef  erence 
(1-447)  returns  the  sample  description  corresponding  to  the  returned  sample 
data.  The  function  resizes  this  handle  as  appropriate. 

GetMedi  aSampl  eReferences  only  returns  a  single  structure.  If  the  sample 
description  changes  within  the  media,  GetMedi  aSampl  eReferences  returns  only 
as  many  samples  as  use  a  single  sample  description.  You  must  call  it  again  to 
get  the  next  group  of  samples  using  the  next  sample  description.  If  you  don't 
want  the  Sampl  eDescri  pti  on  structure,  set  this  parameter  to  NIL. 

sampl eDescri pti onlndex 

A  pointer  to  a  long  integer.  GetMedi  aSampl  eReferences  64  returns  an  index  value 
to  the  sample  descriptions  that  correspond  to  the  returned  sample  data.  Use 
this  index  to  retrieve  the  media  sample  descriptions  with 
GetMedi  aSampl  eDescri  pti  on  (1-445).  If  you  don't  want  this  information,  set  this 
parameter  to  NIL. 
maxN umber Of Entri es 

The  maximum  number  of  entries  to  be  returned.  The  sample  references  pointer 
provided  by  the  sampleRefs  parameter  must  be  large  enough  to  receive  the 
number  of  entries  specified  by  this  parameter.  The  toolbox  does  not  return 
more  entries  than  you  specify  with  this  parameter.  It  may,  however,  return 
fewer. 

actual  Number of Entri es 

A  pointer  to  a  long  integer.  GetMedi  aSampl  eReferences64  updates  the  field 
referred  to  by  this  parameter  with  the  number  of  entries  referred  to  by  the 
returned  reference. 
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sampl eRef s 

A  pointer  to  the  number  of  Sampl  eReference64Record  (IV-2415)  structures 
specified  in  the  maxNumberOf  Entri  es  parameter.  On  return  from  this  call,  the 
number  of  sample  reference  records  indicated  by  the  value  returned  in 
actual  Numberof  Entri  es  will  be  filled  in. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

The  only  difference  between  this  function  and  GetMedi  aSampl  eRef  erences  (1-449)  is 
that  the  sampl  eRef  s  parameter  points  to  Sampl  eRef erence64 Record  structures  instead 
of  Sampl  eRef  erenceRecord  structures. 

Special  Considerations 

New  applications  should  use  this  function  instead  of  the  32-bit  version. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


See  Also 

See  GetMedi  aSampl  eReferences  (1-449). 


GetMediaShadowSync 


Returns  the  sample  number  of  the  shadow  sync  sample  associated  with  a  given 
frame  difference  sample  number. 

OSErr  GetMediaShadowSync  ( 

Media  theMedia, 

long  f rameDi ffSampl eNum, 

long  *syncSampl eNum  ); 

theMedi a 

Indicates  the  media  in  which  the  shadow  sync  sample  has  been  established  and 
from  which  the  shadow  sync  number  is  to  be  obtained. 

f rameDi ffSampl eNum 

The  frame  difference  sample  number  associated  with  the  desired  shadow  sync 
sample  number. 
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syncSampl eNum 

A  pointer  to  the  sample  number  of  the  shadow  sync  sample.  If  the  media  does 
not  have  a  shadow  sync  sample,  0  is  returned  in  the  syncSampl  eNum  parameter. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Enhancing  Movie  Playback  Performance"  (V-2722) 

Related  Java  Methods 

qui ckti me . std .movi es .medi a . Medi a . getShadowSynct ) 


See  Also 

For  the  corresponding  set  function,  see  SetMedi  aShadowSync  (III— 1607). 


GetMediaSyncSampleCount 


Gets  the  number  of  sync  samples  in  a  media. 

long  GetMediaSyncSampleCount  ( 

Medi a  theMedi a  ) ; 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetT rackMedi  a  (1-535). 

function  result  The  number  of  sync  samples  in  the  media. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Related  Java  Methods 

qui  ckti  me.  std.  mo  vies,  media.  Media,  get  SyncSampleCountO 
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GetMediaTimeScale 


Determines  a  media's  time  scale. 

TimeScale  GetMediaTimeScale  ( 

Media  theMedia  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 

function  result  The  media's  time  scale. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Media  Time"  (V-2735) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Medi a . getTi meScal e( ) 


See  Also 

For  the  corresponding  set  function,  see  SetMedi  aTi meScal  e  (III— 1608). 


GetMediaTrack 


Determines  the  track  that  uses  a  specified  media. 

Track  GetMediaTrack  ( 

Media  theMedia  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT  rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 

function  result  The  track  identifier  of  the  track  that  uses  the  specified  media. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Locating  a  Movie's  Tracks  and  Media  Structures" 
(V-2736) 
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Related  Java  Methods 

qui ckti me. std. movies. Track. fromMedi a ( ) , 
qu ickti me. std. mo vies. media. Media. getTrackO 


GetMediaUserData 


Obtains  access  to  a  media's  user  data  list. 

UserData  GetMediaUserData  ( 

Medi a  theMedi a  ) ; 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetT rackMedi  a  (1-535). 

function  result  The  media's  user  data  list. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  User  Data"  (V-2743) 

Related  Java  Methods 

qui ckti me. std. mo vies. media. User Data .fromMedi a ( ) , 
qu i c kt i me. std. mo vies. media. Media. getUser Da tat) 


See  Also 

You  can  then  use  GetUserData  (1-547),  AddUserData  (1-44),  and  RemoveUserData 
(III— 1459)  to  manipulate  the  contents  of  the  user  data  list.  If  the  data  list  contains 
text  data,  you  can  use  GetUserDataText  (1-549),  AddUserDataText  (1-45),  and 
RemoveUserDataText  (III— 1460)  to  work  with  its  contents. 


GetMovieActive 


Determines  whether  a  movie  is  currently  active. 

Boolean  GetMovieActive  ( 

Movi e  theMovi e  ) ; 
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theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  TRUE  if  the  movie  is  currently  active,  FALSE  otherwise. 

Special  Considerations 

The  Movie  Toolbox  services  only  active  movies. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Disabling  Movies  and  Tracks"  (V-2724) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . get Act i ve( ) 

See  Also 

For  the  corresponding  set  function,  see  SetMovi  eActi  ve  (III— 1609). 


GetMovieActiveSegment 


Determines  what  portion  of  a  movie  is  currently  active  for  playing. 

void  GetMovieActiveSegment  ( 

Movie  theMovi e, 

TimeValue  *startTime, 

TimeValue  *duration  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

startTime 

A  pointer  to  a  time  value.  GetMovi  eActi  veSegment  places  the  starting  time  of  the 
active  segment  into  the  field  referred  to  by  this  parameter.  If  the  returned  time 
value  is  set  to  -1,  the  entire  movie  is  active.  In  this  case,  the  Movie  Toolbox  does 
not  return  any  duration  information. 

durati on 

A  pointer  to  a  time  value.  GetMovi  eActi  veSegment  places  the  duration  of  the 
active  movie  segment  into  the  field  referred  to  by  this  parameter.  If  the  entire 
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movie  is  active,  the  sta  rtT i  me  parameter  is  set  to  -1  and  this  parameter  does  not 
return  any  duration  information. 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (IM94). 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Enhancing  Movie  Playback  Performance"  (V-2722) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . getActi veSegment ( ) 


See  Also 

For  the  corresponding  set  function,  see  SetMovi  eActi  veSegment  (III— 1609). 


GetMovieAnchorDataRef 


Retrieves  a  movie's  anchor  data  reference  and  type. 

OSErr  GetMovieAnchorDataRef  ( 

Movie  theMovie, 

Handle  *dataRef, 

OSType  *dataRefType , 

1 ong  *outFl ags  ) ; 

theMovi e 

A  movie  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e 
(11-1084). 

dataRef 

A  handle  to  the  data  reference.  The  type  of  information  stored  in  the  handle 
depends  upon  the  data  reference  type  specified  by  data  Ref  Type. 
dataRefType 

The  type  of  data  reference;  see  "Data  References"  (IV-2661). 
outFl  ags 

If  there  is  no  anchor  data  reference  associated  with  the  movie,  then 
GetMovi  eAnchorDataRef  sets  this  parameter  to  kMovi  eAnchorDataRef IsDefaul  t 
(see  below)  and  returns  copies  of  the  default  data  reference  and  type. 
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function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

outFlags  Constants 

kMovi eAnchorDataRef IsDefaul t 

Data  returned  in  dataRef  and  dataRefType  are  the  movie's  default  values. 

Discussion 

If  there  is  neither  an  anchor  nor  a  default  data  reference,  N I L  will  be  returned  in 
dataRef  and  0  in  dataRefType. 

Special  Considerations 

The  caller  should  dispose  of  the  data  reference  returned. 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movl  es  .  h 

See  Also 

For  the  corresponding  set  function,  see  SetMovi  eAnchorDataRef  (III— 1610). 


GetMovieBoundsRgn 

Determines  a  movie's  boundary  region. 

RgnHandle  GetMovieBoundsRgn  ( 

Movie  theMovie  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  A  handle  to  a  MacRegi  on  (IV-2303)  structure  that  the  function 

allocates.  If  the  movie  does  not  have  a  spatial  representation  at  the 
current  time,  the  function  returns  an  empty  region.  If  the  function 
could  not  satisfy  the  request,  it  sets  the  returned  handle  to  NIL. 

Discussion 

The  Movie  Toolbox  derives  the  boundary  region  only  from  enabled  tracks,  and  only 
from  those  tracks  that  are  used  in  the  current  display  mode  (that  is,  movie  or 
preview).  The  boundary  region  is  valid  for  the  current  movie  time. 
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Special  Considerations 

Your  application  must  dispose  of  the  returned  region  when  it  is  done  with  it. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qui ckti me . qd . Regi on . f romMovi e Bounds ( ) , 
qui ckti me. std .movi es .Movi e. get Bounds Rgn( ) 


GetMovieBox 


Returns  a  movie's  boundary  rectangle,  which  is  a  rectangle  that  encompasses  all  of 
the  movie's  enabled  tracks. 

void  GetMovieBox  ( 

Movie  theMovie, 

Rect  *boxRect  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
boxRect 

A  pointer  to  a  rectangle.  GetMovi  eBox  returns  the  coordinates  of  the  movie's 
boundary  rectangle  into  the  structure  referred  to  by  this  parameter. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi esSti ckyError  (IM94). 

Discussion 

The  movie  box  is  in  the  coordinate  system  of  the  movie's  graphics  world  and 
defines  the  movie's  boundaries  over  the  entire  duration  of  the  movie.  The  movie's 
boundary  rectangle  defines  the  size  and  shape  of  the  movie  before  the  Movie 
Toolbox  applies  the  display  clipping  region.  The  following  code  sample  illustrates 
the  use  of  GetMovi  eBox: 

//  GetMovieBox  coding  example 

//  See  “Discovering  QuickTime,”  page  218 

void  main  (void) 
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Wi ndowPtr 

pMacWnd ; 

Rect 

rectWnd ; 

Rect 

rectMovi 

e ; 

Movi  e 

movi e ; 

Bool ean 

bDone  = 

FALSE; 

OSErr 

nErr ; 

EventRecord 

er ; 

Wi ndowPtr 

pWhi chWnd ; 

short 

nPart; 

InitGraf(&qd.thePort) ; 

InitFonts( ) ; 

Ini tWi ndows ( ) ; 

InitMenusI ) ; 

TEIni t ( ) ; 

Ini tDi al ogs(NIL)  ; 
nErr  =  EnterMovi es ( ) ; 
if  (nErr  !=  noErr) 
return ; 

SetRectl&rectWnd ,  100,  100,  200,  200); 

pMacWnd  =  NewCWindow(NIL,  &rectWnd,  "\pMovie",  FALSE, 

noGrowDocProc ,  ( Wi ndowPtr ) - 1 ,  TRUE,  0); 

SetPortI pMacWnd ) ; 
movi e  =  GetMovi e( ) ; 
i f  (movi e  ==  NIL) 
return ; 

GetMovi eBox(movi e ,  &rectMovie) ; 

OffsetRect(&rectMovie,  - rectMovi e . 1  eft ,  -rectMovie.top) ; 

SetMovi eBox(movi e ,  &rectMovie) ; 

Si zeWi ndow( pMacWnd ,  rectMovi e . ri ght ,  rectMovie. bottom,  TRUE); 
ShowWi ndow( pMacWnd ) ; 

SetMovieGWorld(movie,  (CGraf Ptr)pMacWnd  ,  NIL); 

StartMovi e(movi e) ; 
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DisposeMovie(movie) ; 

DisposeWindow(pMacWnd) ; 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

quicktime.std.movies.Movie.getBoundsO,  qui ckti me. std. movies. Movie. get Box ( ) 

See  Also 

For  the  corresponding  set  function,  see  SetMovi  eBox  (III— 1611). 


GetMovieClipRgn 

Determines  a  movie's  clipping  region. 

RgnHandle  GetMovieClipRgn  ( 

Movi e  theMovi e  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  A  handle  to  a  MacRegi  on  (IV-2303)  structure,  which  the  function 
allocates,  that  represents  the  clipping  region.  If  the  function  could 
not  satisfy  your  request  or  if  there  is  no  clipping  region  defined  for 
the  movie,  GetMovi  eCl  i  pRgn  sets  the  returned  handle  to  NIL. 

Discussion 

The  clipping  region  is  saved  with  the  movie  when  your  application  saves  the  movie. 

Special  Considerations 

Your  application  must  dispose  of  this  region  when  it  is  done  with  it. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qui cktime . qd . Regi on . f romMovi eCl i p( ) ,  qui cktime . std .movi es . Movi e . get Cl i pRgn( ) 


See  Also 

For  the  corresponding  set  function,  see  SetMovi  eCl  i  pRgn  (III— 1612). 


GetMo  vieColorT  able 


Retrieves  a  movie's  color  table. 

OSErr  GetMovieColorTable  ( 

Movie  theMovie, 

CTabHandle  *ctab  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  identifier  from  such 
functions  as  NewMovie  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

ctab 

A  pointer  to  a  field  that  is  to  receive  a  handle  to  the  movie's  color  table.  If  the 
movie  does  not  have  a  color  table,  the  toolbox  sets  the  field  to  NIL. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

The  toolbox  returns  a  copy  of  the  color  table,  so  it  is  your  responsibility  to  dispose 
of  the  color  table  when  you  are  done  with  it. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qui cktime . std .movi es . Movi e . getCol orTabl  e( ) , 
qui cktime . qd . Col orTabl e . f romMovi e( ) 
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See  Also 

For  the  corresponding  set  function,  see  SetMovi  eCol  orTabl  e  (III— 1613). 


GetMovieCoverProcs 


Retrieves  the  cover  functions  that  you  set  with  the  SetMovi  eCoverProcs  function. 

OSErr  GetMovieCoverProcs  ( 

Movie  theMovie, 

Movi eRgnCoverUPP  *uncoverProc , 

Movi eRgnCoverUPP  *coverProc, 

1 ong  *refcon  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  identifier  from  such 
functions  as  NewMovie  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

uncoverProc 

Where  to  return  the  current  uncover  procedure.  This  value  is  set  to  N I L  if  no 
uncover  procedure  was  specified. 
coverProc 

Where  to  return  the  current  cover  procedure.  This  value  is  set  to  N I L  if  no  cover 
procedure  was  specified. 

refcon 

A  reference  constant  to  be  passed  to  your  callback.  Use  this  parameter  to  point 
to  a  data  structure  containing  any  information  your  cover  functions  need. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

This  function  returns  the  uncover  and  cover  functions  for  the  movie  as  well  as  the 
reference  constant  for  the  cover  functions. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Progress  and  Cover  Functions"  (V-2726) 
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See  Also 

For  the  corresponding  set  function,  see  SetMovi  eCoverProcs  (III— 1614). 


GetMo  vieCreationT  ime 


Returns  the  movie's  creation  date  and  time  information. 

long  GetMovieCreationTime  ( 

Movie  theMovie  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  The  movie's  creation  date  and  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Determining  Movie  Creation  and  Modification  Time" 
(V-2741) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . getCreati onTime( ) 


GetMovieDataSize 


Determines  the  size  of  the  sample  data  in  a  segment  of  a  movie. 

long  GetMovieDataSize  ( 

Movie  theMovie, 

TimeValue  startTime, 

TimeValue  duration  ); 

theMovi e 

The  movie  for  this  operation.  You  obtain  this  movie  identifier  from  such 
functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

startTime 

A  time  value  specifying  the  starting  point  of  the  segment. 
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durati on 

A  time  value  that  specifies  the  duration  of  the  segment. 


function  result  The  size,  in  bytes,  of  the  sample  data  in  the  defined  segment  of  the 
designated  movie. 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Media  Samples"  (V-2742) 

Related  Java  Methods 

quicktime.std.movies.Movie.getDataSizeO 


See  Also 

See  GetMovi  eDataSi  ze64  (1-466). 


GetMovieDataSize64 


Provides  a  64-bit  version  of  GetMovi  eDataSi  ze  (1-465). 

OSErr  GetMovi eDataSi ze64  ( 

Movie  theMovie, 

TimeVal ue  startTi me , 

TimeValue  duration, 

wi de  *dataSi ze  ) ; 

theMovi e 

The  movie  for  this  operation.  You  obtain  this  movie  identifier  from  such 
functions  as  NewMovie  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

startTime 

A  time  value  specifying  the  starting  point  of  the  segment, 
durati on 

A  time  value  that  specifies  the  duration  of  the  segment, 
data  size 

The  size,  in  bytes,  of  the  sample  data  in  the  defined  segment  of  the  designated 
movie. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 
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Discussion 

The  only  difference  between  this  function  and  GetMovi eDataSi  ze  (1-465)  is  that  the 
dataSi  ze  parameter  is  a  64-bit  integer  instead  of  a  32-bit  integer. 

Special  Considerations 

New  applications  should  use  this  function  instead  of  the  32-bit  version. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


See  Also 

See  GetMovi  eDataSi  ze  (1-465). 


GetMovieDefaultDataRef 


Gets  a  movie's  default  data  reference. 

OSErr  GetMovieDefaultDataRef  ( 

Movie  theMovie, 

Handle  *dataRef, 

OSType  *dataRefType  ); 

theMovi e 

A  movie  identifier.  Your  application  obtains  this  movie  identifier  from  such 
functions  as  NewMovie  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

dataRef 

A  pointer  to  a  field  that  is  to  receive  a  handle  to  the  data  reference.  The  function 
returns  a  handle  to  information  that  identifies  the  file  that  contains  this  media's 
data.  The  type  of  information  stored  in  that  handle  depends  upon  the  value  of 
the  dataRefType  parameter.  If  the  function  cannot  locate  the  specified  data 
reference,  the  handler  sets  this  returned  value  to  N I L.  Set  the  dataRef  parameter 
to  N I L  if  you  are  not  interested  in  this  information. 
dataRefType 

A  pointer  to  a  field  that  is  to  receive  the  type  of  data  reference;  see  "Data 
References"  (IV-2661).  If  the  data  reference  is  an  alias,  the  function  sets  this 
value  to  'alls',  indicating  that  the  reference  is  an  alias.  Set  the  dataRefType 
parameter  to  N I L  if  you  are  not  interested  in  this  information. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
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(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . getDefaul t Data  Ref ( ) , 
qui ckti me . std .movi es .medi a . Data  Ref . f romMovi e( ) 


See  Also 

For  the  corresponding  set  function,  see  SetMovi  eDefaul  tDataRef  (ill-1616). 


GetMovieDisplayBoundsRgn 

Determines  a  movie's  display  boundary  region. 

RgnHandle  GetMovieDisplayBoundsRgn  ( 

Movi e  theMovi e  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  A  handle  to  a  MacRegi  on  (IV-2303)  structure  that  the  function 

allocates.  If  the  movie  does  not  have  a  spatial  representation  at  the 
current  time,  the  function  returns  an  empty  region.  If  the  function 
could  not  satisfy  the  request,  it  sets  the  returned  handle  to  N I L. 

Discussion 

The  display  boundary  region  encloses  all  of  a  movie's  enabled  tracks  after  the  track 
matrix,  track  clip,  movie  matrix,  and  movie  clip  have  been  applied  to  them.  This 
region  is  in  the  display  coordinate  system  of  the  movie's  graphics  world.  The  Movie 
Toolbox  derives  the  display  boundary  region  only  from  enabled  tracks,  and  only 
from  those  tracks  that  are  used  in  the  current  display  mode  (that  is,  movie,  poster, 
or  preview).  The  display  boundary  region  is  valid  for  the  current  movie  time. 

Special  Considerations 

Your  application  must  dispose  of  the  returned  handle  when  it  is  done  with  it. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qui  cktime .  qd  .  Regi  on  .  f  romMovi  eDisplayBoundsO, 
qui cktime . std .movi es . Movi e . getDi spl ay Bounds Rgn( ) 


GetMovieDisplayClipRgn 

Determines  a  movie's  current  display  clipping  region. 

RgnHandle  GetMovieDisplayClipRgn  ( 

Movie  theMovie  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  A  handle  to  a  MacRegi  on  (IV-2303)  structure  that  the  function 

allocates.  If  the  movie  does  not  have  a  spatial  representation  at  the 
current  time,  the  function  returns  an  empty  region.  If  the  function 
could  not  satisfy  the  request,  it  sets  the  returned  handle  to  NIL. 

Special  Considerations 

Your  application  must  dispose  of  the  returned  handle  when  it  is  done  with  it.  Note 
that  the  display  clipping  region  is  not  saved  with  the  movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qui ckti me . qd . Regi on . f romMovi eDi spl ayCl i p( ) , 
qui cktime . std .movi es . Movi e . getDi spl ay Cl i p  Rg  n ( ) 


See  Also 

For  the  corresponding  set  function,  see  SetMovi  eDi  spl  ayCl  i  pRgn  (III— 1616). 
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GetMovieDuration 

Returns  the  duration  of  a  movie. 

TimeValue  GetMovieDuration  ( 

Movi e  theMovi e  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  The  duration  of  the  designated  movie. 

Discussion 

This  function  returns  a  time  value,  expressed  in  the  movie's  time  scale,  that  is 
calculated  to  be  the  maximum  durations  of  all  the  tracks  in  the  movie.  The  following 
code  sample  illustrates  its  use: 

//  GetMovieDuration  coding  example 
//  See  “Discovering  QuickTime,”  page  363 
Movie  moviel; 

TimeValue  1 01 dDurati on ; 

Movie  movie2; 

long  llndex,  1 Ori gTrackCount ,  1 Referencelndex ; 

Track  track,  trackSprite; 

//  get  the  first  track  in  original  movie  and  position  at  the  start 
trackSprite  =  GetMovi elndTrackimovi el ,  1); 

SetMovi eSel ecti on (movi el ,  0,  0); 

//  remove  all  tracks  except  video  in  modifier  movie 

for  (llndex  =  1;  llndex  <=  GetMovi eTrackCounttmovi e2) ;  llndex++)  { 

Track  track  =  GetMovi elndTracktmovi e2 ,  llndex); 

OSType  dwType; 

GetMedi aHandlerDescriptiontGetT  rackMedi a ( track) , 

&dwType ,  NIL,  NIL); 
if  (dwType  !=  Vi deoMedi aType )  { 

DisposeMovieTrackt track) ; 

1  Index- - ; 

} 

} 
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//  add  the  modifier  track  to  original  movie 
lOldDuration  =  GetMovi eDurationlmoviel ) ; 

AddMovi eSel ecti onlmovi el ,  movi e2 ) ; 

Di sposeMovi e(movi e2) ; 

//  truncate  the  movie  to  the  length  of  the  original  track 
Del eteMovi eSegment(movi el,  lOldDuration, 

GetMovi eDuration(moviel)  -  lOldDuration); 

//  associate  the  modifier  track  with  the  original  sprite  track 
track  =  GetMovi elndTracklmovi el ,  1 Ori gTrackCount  +  1); 

AddT rackReferencel trackSpri te ,  track,  kTrackModi f i er Reference , 
&1 Referencelndex) ; 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  Time"  (V-2732) 

Related  Java  Methods 

qui cktime . std .movi es . Movi e . getDurati on( ) 

GetMovieGWorld 


Returns  a  movie's  graphics  world. 

void  GetMovieGWorld  ( 

Movie  theMovie, 

CGrafPtr  *port, 

GDHandle  *gdh  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

port 

Apointer  toafieldthat  is  to  receive  a  pointer  to  a  CGrafPort  (IV-2168)  structure. 
Set  this  parameter  to  N I L  if  you  don't  want  this  information. 
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gdh 

A  pointer  to  a  field  that  is  to  receive  a  handle  to  a  GDevi  ce  (IV-2264)  structure. 
Set  this  parameter  to  N I L  if  you  don't  want  this  information. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

quicktime.std.movies.Movie.getGWorldO,  quicktime.qd.QDGraphics.fromMoviet ) 

See  Also 

For  the  corresponding  set  function,  see  SetMovi  eGWorl  d  (III— 1619). 


GetMovielmporterForDataRef 

Gets  the  movie  importer  component  for  a  movie. 

OSErr  GetMovielmporterForDataRef  ( 

OSType  dataRefType, 

Handle  dataRef, 

long  flags, 

Component  *importer  ); 

dataRefType 

The  type  of  data  reference;  see  "Data  References"  (IV-2661). 
dataRef 

A  handle  to  the  data  reference.  The  type  of  information  stored  in  the  handle 
depends  upon  the  data  reference  type  specified  by  dataRefType. 

fl  ags 

Flags  (see  below)  that  modify  this  function's  behavior, 
i mporter 

A  pointer  to  an  importer  component  that  can  import  the  movie.  Returns  N I L  if 
no  importer  can  be  found. 

function  result  If  this  function  is  allowed  to  use  async  calls  (by  being  passed 

kGetMovi  elmporterUseAsyncCal  1  s  in  the  f  1  ags  parameter),  it  returns 
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notEnoughDataErrifit  would  block.  You  can  access  this  error  return 
through  GetMovi  esError  (1-492)  and  GetMovi esSti  ckyError  (1-494), as 
well  as  in  the  function  result.  For  other  errors,  see  "Error  Codes" 
(IV-2663). 

flags  Constants 

kGetMovi elmporterDontConsi derGraphi cs Importers 

Don't  consider  any  still  image  file  formats  that  could  be  opened  as  QuickTime 
movies. 

kGetMovi  elmporterllseAsyncCal  1  s 

Call  DataHGetMIMETypeAsync  (1-201)  if  instructed  to  do  so.  Without  this  flag,  the 
call  may  block. 

Discussion 

You  can  use  GetMovi  elmporterForDataRef  to  determine  if  a  file  can  be  opened  by 
QuickTime  as  a  movie  (for  example,  in  a  drag-and-drop  operation)  as  illustrated 
below: 

AliasHandle  alias; 

Movi elmportComponent  mi; 

NewAl i as Mi nimal (&amp ; reply . sf Fi 1 e ,  &amp ; al i as ) ; 

GetMovi elmporterForDataRef! rAl iasType,  (Handle)alias, 
kGetMovi elmporterDontConsi derGraphi cs Importers ,  &amp ;mi ) ; 
DisposeHandle((Handle)alias); 

if  (mi  !=  NIL)  { 

//  this  file  can  be  opened  as  a  movie 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Related  Java  Methods 

qui cktime . std . qt components .Movi e Importer . Movi e Importer! ) 


GetMo  vielndT  rack 


Determines  the  track  identifier  of  a  track,  given  the  track's  index  value. 
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Track  GetMovielndTrack  ( 

Movie  theMovie, 

1 ong  i ndex  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
i  ndex 

The  index  value  of  the  track  for  this  operation. 

function  result  A  track  identifier.  If  the  function  cannot  locate  the  track,  it  sets  this 
returned  value  to  NIL. 

Discussion 

This  function  returns  the  track  identifier  that  is  appropriate  to  the  specified  track. 
The  index  value  identifies  the  track  among  all  current  tracks  in  a  movie.  Index 
values  range  from  1  to  the  number  of  tracks  in  the  movie.  The  following  code 
sample  illustrates  its  use: 

//  GetMovielndTrack  coding  example 
//  See  “Discovering  QuickTime,”  page  363 
Movie  moviel; 

TimeValue  1 01 dDurati on ; 

Movie  movie2; 

long  llndex,  1 Ori gTrackCount ,  1 Referencelndex ; 

Track  track,  trackSprite; 

//  get  the  first  track  in  original  movie  and  position  at  the  start 
trackSprite  =  GetMovi elndTracktmovi el ,  1); 

SetMovi eSel ecti on (movi el ,  0,  0); 


//  remove  all  tracks  except  video  in  modifier  movie 
for  (llndex  =  1;  llndex  <=  GetMovieTrackCount(movie2) ;  llndex++)  { 
Track  track  =  GetMovi elndTracktmovi e2 ,  llndex); 

OSType  dwType; 


GetMediaHandlerDescription(GetT  rackMedi a ( track) , 

&dwType ,  NIL,  NIL); 
if  (dwType  !=  Vi deoMedi aType )  { 
DisposeMovieTrack(track) ; 

1  Index-  -  ; 
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} 

} 

//  add  the  modifier  track  to  original  movie 
lOldDuration  =  GetMovi eDurati on(moviel ) ; 

AddMovi eSel ecti on(movi el ,  movi e2 ) ; 

Di sposeMovi e(movi e2) ; 

//  truncate  the  movie  to  the  length  of  the  original  track 
Del eteMovi eSegment(movi el,  lOldDuration, 

GetMovi eDuration(moviel)  -  lOldDuration); 

//  associate  the  modifier  track  with  the  original  sprite  track 
track  =  GetMovi elndTrackimovi el ,  1 Ori gTrackCount  +  1); 

AddT rackReferencei trackSpri te ,  track,  kTrackModi f i er Reference , 

&1 Referencelndex) ; 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Locating  a  Movie's  Tracks  and  Media  Structures" 
(V-2736) 

Related  Java  Methods 

qui cktime . std .movi es . Movi e . getlndTracki ) 

GetMo  vielndT  rackT  ype 

Searches  for  all  of  a  movie's  tracks  that  share  a  given  media  type  or  media 
characteri  sti  c. 

Track  GetMovielndTrackType  ( 

Movie  theMovie, 

long  index, 

OSType  trackType, 
long  flags  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  identifier  from  such 
functions  as  NewMovie  (11-1069),  NewMovi eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
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i  ndex 

The  index  value  of  the  track  for  this  operation.  This  is  not  that  same  as  the 
track's  index  value  in  the  movie.  Rather,  this  parameter  is  an  index  into  the  set 
of  tracks  that  meet  your  other  selection  criteria. 
trackType 

Contains  either  a  media  type  or  a  media  characteristic  value.  The  toolbox 
applies  this  value  to  the  search,  and  returns  information  about  tracks  that  meet 
this  criterion.  You  indicate  whether  you  have  specified  a  media  type  or 
characteristic  value  by  setting  the  flags  parameter  appropriately. 

fl  ags 

Contains  flags  (see  below)  that  control  the  search  operation.  Note  that  you  may 
not  set  both  movi  eTrackMedi  aType  and  movi  eT rackCharacteri  sti  c  to  1. 

function  result  A  track  identifier. 

flags  Constants 

movi eT  rackMedi aType 

Indicates  that  the  trackType  parameter  contains  a  media  type  value.  Set  this  flag 
to  1  if  you  are  supplying  a  media  type  value  (such  as  Vi  deoMedi  aType). 
movi eT rackCharacteri Stic 

Indicates  that  the  trackType  parameter  contains  a  media  characteri  sti  c  value. 
Set  this  flag  to  1  if  you  are  supplying  a  media  characteristic  value  (such  as 
Visual  Medi  aCharacteri  stic). 

movieTrackEnabledOnly 

Specifies  that  the  toolbox  should  only  search  enabled  tracks.  Set  this  track  to  1 
to  limit  the  search  to  enabled  tracks. 

Discussion 

The  toolbox  returns  the  track  identifier  that  corresponds  to  the  track  that  meets  your 
selection  criteria.  If  the  toolbox  cannot  find  a  matching  track,  in  returns  a  value  of 
N I L.  Note  that  the  index  parameter  does  not  work  the  same  way  that  is  does  in 
GetMovi  elndT  rack  (1-473).  With  Get  Movi  elndT  rackType,  the  i  ndex  parameter  specifies 
an  index  into  the  set  of  tracks  that  meet  your  other  selection  criteria.  For  example, 
in  order  to  find  the  third  track  that  supports  the  sound  characteri  stic,  you  would 
call  the  function  in  the  following  manner: 

theTrack  =  GetMovielndTrackType  (theMovie,  3,  AudioMedi aCharacteri stic , 
mo vieT rackCharacteri stic) ; 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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GetMovieLoadState 


Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Locating  a  Movie's  Tracks  and  Media  Structures" 
(V-2736) 

Related  Java  Methods 

qui cktime . std .movi es . Movi e . getlndTrackTypeC ) 


See  Also 

See  GetMovielndTrack  (1-473). 


GetMovieLoadState 


Returns  a  value  that  indicates  the  state  of  a  movie's  loading  process. 

long  GetMovieLoadState  ( 

Movie  theMovie  ); 

theMovi e 

A  movie  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e 
(11-1084). 

function  result  A  constant  (see  below)  that  indicates  the  movie's  loading  status. 

Function  Result  Constants 

kMovi eLoadStateLoadi ng 

Searching  for  movie  resource. 
kMovi e Load St ate PI ayabl e 

Movie  fully  formed;  fast-start  would  work. 
kMovi e Load St ate PI aythroughOK 

Returned  after  the  movie  has  become  playable,  as  soon  as  QuickTime  calculates 
that  the  download  would  be  complete  before  the  playback  would  finish. 

kMovi eLoadStateCompl  ete 

All  media  data  is  available. 
kMovi e Load St ateError 

The  loading  of  the  movie  failed,  typically  meaning  that  a  URL  could  not  be 
found  or  loaded.  This  constant  has  a  negative  value. 
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Discussion 

This  function  lets  your  code  perform  relative  comparisons  against  movie  loading 
milestones  to  determine  if  certain  operations  make  sense.  Its  return  values  are 
ordered  so  that  they  conform  to  this  rule: 

kMovi eLoadStateError 

<  kMovi eLoadStateLoadi ng 

<  kMovi eLoadStatePl ayabl e 

<  kMovi eLoadStateCompl ete 

Special  Considerations 

Because  of  the  "voting  system"  involved,  an  application  checking  for  the  load  state 
should  throttle  its  calling  of  the  routine.  Not  calling  GetMovi  eLoadState  more  often 
than  every  quarter  of  a  second  is  a  good  place  to  start. 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es .  h 


GetMovieMatrix 


Retrieves  a  movie's  transformation  matrix. 

void  GetMovieMatrix  ( 

Movie  theMovie, 

MatrixRecord  *matrix  ); 


theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

matri x 

A  pointer  to  a  Matri  xRecord  (IV-2304)  structure,  where  GetMovi  eMatri  x  returns 
the  movie's  matrix. 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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GetMovieModificationTime 


Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . getMatrix( ) 


See  Also 

For  the  corresponding  set  function,  see  SetMovi  eMatri  x  (III— 1622).  You  can  set  a 
movie's  matrix  with  SetMovi  eMatr lx.  The  Movie  Toolbox  provides  a  number  of 
functions  that  allow  you  to  manipulate  movie  matrices.  See  Set  I  dent  i  tyMatri  x 
(III— 1593)  for  information  about  these  functions. 


GetMo  vieModif  icationT  ime 


Returns  a  movie's  modification  date  and  time. 

long  GetMovieModificationTime  ( 

Movie  theMovie  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi eFromHandl e  (11-1084). 

function  result  The  movie's  modification  date  and  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Determining  Movie  Creation  and  Modification  Time" 
(V-2741) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . getModi f i cati onTime( ) 


GetMovieNaturalBoundsRect 


Gets  a  movie's  natural  boundary  rectangle. 

void  GetMovieNaturalBoundsRect  ( 

Movie  theMovie, 
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Rect  *natural Bounds  ); 
theMovi  e 

A  movie  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e 
(11-1084). 

natural  Bounds 

A  pointer  to  a  Rect  (IV-2399)  structure  that  represents  the  movie's  bounding 
rectangle. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Related  Java  Methods 

quicktime.std.movies.Movie.getNaturalBoundsRectt) 


GetMovieNextlnterestingTime 

Searches  for  times  of  interest  in  a  movie's  enabled  tracks. 

void  GetMovieNextlnterestingTime  ( 

Movie  theMovie, 

short  i n teres ti ngTi me  Flags, 

short  numMedi aTypes , 

const  OSType  *whi chMedi aTypes , 

TimeValue  time, 

Fixed  rate, 

TimeValue  *i nteresti ngTi me , 

TimeValue  *i nteresti ngDurati on  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
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i nteresti ngTimeFl  ags 

Contains  flags  (see  below)  that  determine  the  search  criteria.  Note  that  you  may 
set  only  one  of  the  nextTi  meMedi  aSampl  e,  nextT i  meMedi  a  Ed i  t,  nextT i  meT rackEdi  t 
and  nextTi meSyncSampl  e  flags  to  1.  Set  unused  flags  to  0. 
numMedi aTypes 

The  number  of  media  types  in  the  table  referred  to  by  the  whichMediaType 
parameter.  Set  this  parameter  to  0  to  search  all  media  types. 

whi chMedi aTypes 

A  pointer  to  an  array  of  media  type  constants  (see  below).  You  can  use  this 
parameter  to  limit  the  search  to  a  specified  set  of  media  types.  Each  entry  in  the 
table  referred  to  by  this  parameter  identifies  a  media  type  to  be  included  in  the 
search.  You  use  the  numMedi  aTypes  parameter  to  indicate  the  number  of  entries 
in  the  table.  Set  this  parameter  to  N I L  to  search  all  media  types. 

ti  me 

Specifies  a  time  value  that  establishes  the  starting  point  for  the  search.  This  time 
value  must  be  expressed  in  the  movie's  time  scale. 

rate 

The  search  direction.  Negative  values  cause  the  Movie  Toolbox  to  search 
backward  from  the  starting  point  specified  in  the  ti  me  parameter.  Other  values 
cause  a  forward  search. 

interestingTime 

A  pointer  to  a  time  value.  The  Movie  Toolbox  returns  the  first  time  value  it  finds 
that  meets  the  search  criteria  specified  in  the  flags  parameter.  This  time  value 
is  in  the  movie's  time  scale.  If  there  are  no  times  that  meet  the  search  criteria  you 
specify,  the  Movie  Toolbox  sets  this  value  to  -1.  If  you  are  not  interested  in  this 
information,  set  this  parameter  to  NIL. 
i nteresti ngDurati  on 

A  pointer  to  a  time  value.  The  Movie  Toolbox  returns  the  duration  of  the 
interesting  time.  This  time  value  is  in  the  movie's  time  coordinate  system.  Set 
this  parameter  to  N I L  if  you  don't  want  this  information;  in  this  case,  the 
function  works  faster. 

nterestingTimeFlags  Constants 

nextTi  meMedi aSampl e 

Searches  for  the  next  sample  in  the  movie's  media.  Set  this  flag  to  1  to  search  for 
the  next  sample. 

nextTi meMedi a  Ed i t 

Searches  for  the  next  group  of  samples  in  the  movie's  media.  Set  this  flag  to  1 
to  search  for  the  next  group  of  samples. 
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nextT i meT  rackEdi t 

Searches  for  the  media  sample  that  corresponds  to  the  next  entry  in  a  track's 
media  edit  list.  The  end  of  the  track  is  considered  an  empty  edit.  Set  this  flag  to 
1  to  search  for  the  next  track  edit. 
nextT imeSyncSampl e 

Searches  for  the  next  sync  sample  in  the  movie's  media.  Set  this  flag  to  1  to 
search  for  the  next  sync  sample.  Sync  samples  don't  rely  on  preceding  frames 
for  content.  Some  compression  algorithms  conserve  space  by  eliminating 
duplication  between  consecutive  frames  in  a  sample. 

nextT i meEdgeOK 

Instructs  the  Movie  Toolbox  that  you  are  willing  to  receive  information  about 
elements  that  begin  or  end  at  the  time  specified  by  the  ti  me  parameter.  Set  this 
flag  to  1  to  accept  this  information.  When  this  flag  is  set,  the  function  returns 
valid  information  about  the  beginning  and  end  of  the  movie. 
nextT i melgnoreActi veSegment 

Instructs  the  Movie  Toolbox  to  look  outside  of  the  active  segment  for  samples 
that  meet  the  search  criteria.  Set  this  flag  to  1  to  search  outside  of  the  active 
segment. 

whichMediaTypes  Constants 

Vi sual Medi a Character! sti c 

Value  =  '  eyes ' .  Instructs  the  Movie  Toolbox  to  search  all  tracks  that  have 
spatial  bounds. 

Audi oMediaCharacteri Stic 

Value  =  'ears'.  Instructs  the  Movie  Toolbox  to  search  all  tracks  that  play  sound. 

Discussion 

The  following  code  sample  shows  the  use  of  GetMovi  eNext  Interest i  ngT i me  to 
return,  through  the  time  parameter,  the  starting  time  of  the  first  video  sample  of  the 
specified  QuickTime  movie.  The  trick  here  is  to  set  the  nextTi  meEdgeOK  flag,  to 
indicate  that  you  want  to  get  the  starting  time  of  the  beginning  of  the  movie.  If  this 
function  encounters  an  error,  it  returns  a  (bogus)  starting  time  of  -1,  as  shown 
below: 

static  OSErr  QTStep_GetStartTimeOfFi rstVi deoSampl e  (Movie  theMovie, 

TimeValue  *theTime) 

{ 

short  myFlags; 

OSType  myTypes[l] ; 

*theTime  =  kBogusStartingTime;  //  a  bogus  starting  time 
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i f  (theMovi e  ==  NIL) 

return (inval idMovie) ; 


myFlags  =  nextTimeMediaSampl e  +  nextTimeEdgeOK; 

//  we  want  the  first  sample  in  the  movie 
myTypes[0]  =  Vi sual Medi aCharacteri sti c ;  //  we  want  video  samples 


} 


GetMovieNextInterestingTime(theMovie,  myFlags,  1,  myTypes, 

(TimeVal ue)0,  fixedl,  theTime,  NIL); 


return (GetMovi es Error! ) ) ; 


Special  Considerations 

This  function  examines  only  the  movie's  enabled  tracks. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Finding  Interesting  Times"  (V-2735) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . get Next  In teres ti ngTimel ) 


GetMoviePict 


Creates  a  QuickDraw  picture  from  a  specified  movie  at  a  specified  time. 

PicHandle  GetMoviePict  ( 

Movie  theMovie, 

TimeVal ue  time  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

ti  me 

The  movie  time  from  which  the  image  is  to  be  taken. 

function  result  A  handle  to  a  Pi  cture  (IV-2331)  structure.  If  the  function  could  not 
create  the  picture,  the  returned  handle  is  set  to  NIL. 
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Discussion 

This  function  uses  only  those  movie  tracks  that  are  currently  enabled  and  would 
therefore  be  used  in  playback.  Your  application  may  call  this  function  even  if  the 
movie  is  inactive. 

Special  Considerations 

Your  application  must  dispose  of  this  picture  handle. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Generating  Pictures  From  Movies"  (V-2725) 

Related  Java  Methods 

quicktime.qd.Pict.fromMoviet ) ,  qui c kt 1  me. std. movies. Movie. get PI ct( ) 


See  Also 

See  GetTrackPi ct  (1-540). 


GetMoviePosterPict 


Creates  a  QuickDraw  picture  that  contains  a  movie's  poster. 

PicHandle  GetMoviePosterPict  ( 

Movi e  theMovi e  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  A  handle  to  a  Pi  cture  (IV-2331)  structure.  If  the  function  could  not 
create  the  picture,  the  returned  handle  is  set  to  NIL. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Generating  Pictures  From  Movies"  (V-2725) 

Related  Java  Methods 

quicktime.qd.Pict.fromMoviet ) ,  quicktime.std.movies.Movie.getPosterPictt ) 
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GetMo  viePosterT  ime 


Returns  the  poster's  time  in  a  movie. 

TimeValue  GetMoviePosterTime  ( 

Movie  theMovie  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  The  time  in  the  movie  from  which  its  poster  is  taken. 

Discussion 

Since  a  movie  poster  has  no  duration,  it  is  defined  by  a  point  in  time  within  the 
movie.  The  time  value  returned  by  GetMoviePosterTime  is  in  the  time  coordinate 
system  of  the  movie  and  represents  the  starting  time  for  the  movie  frame  that 
contains  the  poster  image. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Movie  Posters  and  Movie  Previews"  (V-2718) 

Related  Java  Methods 

qui cktime . std .movi es . Movi e . getPosterTimeC ) 


See  Also 

For  the  corresponding  set  function,  see  SetMovi  ePosterT i me  (III— 1625). 


GetMoviePreferredRate 


Returns  a  movie's  default  playback  rate. 

Fixed  GetMoviePreferredRate  ( 

Movie  theMovie  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
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function  result  The  movie's  default  playback  rate. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Preferred  Movie  Settings"  (V-2721) 

Related  Java  Methods 

quicktime.std.movies.Movie.getPreferredRateO 


See  Also 

For  the  corresponding  set  function,  see  SetMovi  ePreferredRate  (III— 1626). 


GetMoviePref  erred  V  olume 


Returns  a  movie's  preferred  volume  setting. 

short  GetMoviePreferredVolume  ( 

Movi e  theMovi e  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  The  movie's  preferred  volume  setting. 

Discussion 

A  movie's  tracks  have  their  own  volume  settings.  A  track's  volume  is  scaled  by  the 
movie's  volume  to  produce  the  track's  final  volume.  On  Macintosh  computers,  the 
movie's  volume  is  further  scaled  by  the  sound  volume  that  the  user  controls  from 
the  Sound  control  panel. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Preferred  Movie  Settings"  (V-2721) 

Related  Java  Methods 

quicktime.std.movies.Movie.getPreferredVol ume( ) 
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See  Also 

For  the  corresponding  set  function,  see  SetMovi  ePreferredVol  ume  (III— 1627).  Use  the 
SetT rackVol  ume  (III— 1669)  function  to  set  the  volume  of  an  individual  track. 


GetMoviePreviewMode 


Determines  whether  a  movie  is  in  preview  mode. 

Boolean  GetMoviePreviewMode  ( 

Movie  theMovie  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  T  RU  E  if  the  movie  is  in  preview  mode;  FA  LS  E  if  the  movie  is  in  normal 
playback  mode. 

Discussion 

If  a  movie  is  in  preview  mode,  only  the  movie's  preview  can  be  displayed. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Movie  Posters  and  Movie  Previews"  (V-2718) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . get Previ ewMode( ) 


See  Also 

For  the  corresponding  set  function,  see  SetMovi  ePrevi  ewMode  (III— 1628). 


GetMo  viePrevie  wT  ime 


Returns  the  starting  time  and  duration  of  the  movie's  preview. 

void  GetMovi ePrevi ewTime  ( 

Movie  theMovie, 

TimeValue  *previewTime, 

TimeValue  *previ ewDurati on  ); 
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theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
previ ewT i me 

A  pointer  to  a  time  value.  The  Movie  Toolbox  places  the  preview's  starting  time 
into  the  field  referred  to  by  this  parameter.  If  the  movie  does  not  have  a 
preview,  the  Movie  Toolbox  sets  this  returned  value  to  0. 

previ ewDurati on 

A  pointer  to  a  time  value.  The  Movie  Toolbox  places  the  preview's  duration 
into  the  field  referred  to  by  this  parameter.  If  the  movie  does  not  have  a 
preview,  the  Movie  Toolbox  sets  this  returned  value  to  0. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94). 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Movie  Posters  and  Movie  Previews"  (V-2718) 

Related  Java  Methods 

quicktime.std.movies.Movie.getPrevi ewT i met ) 


See  Also 

For  the  corresponding  set  function,  see  SetMovi  ePrevi  ewT i  me  (III— 1629). 


GetMovieProgressProc 


Gets  the  Movi eProgressProc  (III— 2105)  callback  attached  to  a  movie. 

void  GetMovieProgressProc  ( 

Movie  theMovie, 

Movi eProgressUPP  *p, 

1 ong  *refcon  ) ; 

theMovi e 

A  movie  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e 
(11-1084). 
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P 

On  return,  a  pointer  to  a  Movi eProgressProc  (III— 2105)  callback, 
ref con 

On  return,  a  reference  constant  passed  to  the  callback.  This  parameter  is  used 
to  point  to  a  data  structure  containing  any  information  the  function  needs. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  4. 


Programming  Info 

C  interface  file:  Movi  es  .  h 


See  Also 

For  the  corresponding  set  function,  see  SetMovi  eProgressProc  (III— 1630). 


GetMoviePropertyAtom 

Gets  a  movie's  property  atom. 

OSErr  GetMoviePropertyAtom  ( 

Movie  theMovie, 

QTAtomContai ner  *propertyAtom  ); 

theMovi e 

A  movie  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e 
(11-1084). 

propertyAtom 

A  pointer  to  a  property  atom. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

This  routine  is  used  to  author  event  handlers  for  the  kQTEventMovi  eLoaded 
QuickTime  event. 

Version  Notes 

Introduced  in  QuickTime  4.1. 
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Programming  Info 

C  interface  file:  Movi  es .  h 

See  Also 

For  the  corresponding  set  function,  see  SetMovi  ePropertyAtom  (III— 1631). 


GetMovieRate 


Returns  a  movie's  playback  rate. 

Fixed  GetMovieRate  ( 

Movi e  theMovi e  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  The  movie's  playback  rate. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  Time"  (V-2732) 

Related  Java  Methods 

qui ckti me. std .movi es .Movi e . get Rate ( ) 

See  Also 

For  the  corresponding  set  function,  see  SetMovi  eRate  (III— 1631). 


GetMovieSegmentDisplayBoundsRgn 


Determines  a  movie's  display  boundary  region  for  a  specified  segment. 


RgnHandle  GetMovi eSegmentDi spl ayBoundsRgn  ( 


Movi  e 
TimeVal ue 
TimeVal ue 


theMovi e , 
time , 

durati on  ) ; 
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theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi eFromHandl e  (11-1084). 

ti  me 

The  starting  time  of  the  movie  segment  to  consider.  This  time  value  must  be 
expressed  in  the  movie's  time  coordinate  system.  The  duration  parameter 
specifies  the  length  of  the  segment. 

durati on 

The  length  of  the  segment  to  consider.  Set  this  parameter  to  0  to  specify  an 
instant  in  time. 

function  result  A  handle  to  a  MacRegi  on  (IV-2303)  structure  that  the  function 

allocates.  This  region  is  defined  in  the  movie's  display  coordinate 
system.  If  the  movie  does  not  have  a  spatial  representation  at  the 
current  time,  the  function  returns  an  empty  region.  If  the  function 
could  not  satisfy  the  request,  it  sets  the  returned  handle  to  NIL. 

Discussion 

This  function  allocates  a  region  and  returns  a  handle  to  it.  The  Movie  Toolbox 
derives  the  display  boundary  region  only  from  enabled  tracks  and  only  from  those 
tracks  that  are  used  in  the  current  display  mode  (movie,  poster,  or  preview).  The 
display  boundary  region  encloses  all  of  a  movie's  enabled  tracks  after  the  track 
matrix,  track  clip,  movie  matrix,  and  movie  clip  have  been  applied  to  them. 

Special  Considerations 

Your  application  must  dispose  of  the  returned  region  when  it  is  done  with  it. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movl  es  .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qui ckti me . qd . Regi on . f romMovi eSegment( ) , 

qui cktime . std .movi es . Movi e . getSegmentDi spl ay Bounds Rgn() 


GetMovieSelection 


Returns  information  about  a  movie's  current  selection. 
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void  GetMovi eSel ecti on  ( 

Movie  theMovie, 

TimeValue  *sel ecti onTi me , 

TimeValue  *sel ecti onDurati on  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

sel ecti onT i me 

A  pointer  to  a  time  value.  The  GetMovi  eSel  ecti  on  function  places  the  starting 
time  of  the  current  selection  into  the  field  referred  to  by  this  parameter.  Set  this 
parameter  to  N I L  if  you  don't  want  this  information, 
sel ecti onDurati on 

A  pointer  to  a  time  value.  The  GetMovi  eSel  ecti  on  function  places  the  duration 
of  the  current  selection  into  the  field  referred  to  by  this  parameter.  Set  this 
parameter  to  N I L  if  you  don't  want  this  information. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "High-Level  Movie  Editing  Functions"  (V-2746) 

Related  Java  Methods 

quicktime.std.movies.Movie.getSelectiont) 


See  Also 

For  the  corresponding  set  function,  see  SetMovi  eSel  ecti  on  (III— 1632). 


GetMoviesError 

Returns  the  contents  of  the  current  error  value  and  resets  the  current  error  value  to 

0. 

OSErr  GetMoviesError  (  void  ); 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error  in  the 
current  error  value. 
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Discussion 

The  Movie  Toolbox  provides  two  error  values  to  your  application:  the  current  error 
and  the  sticky  error.  The  current  error  is  the  result  code  from  the  last  Movie  Toolbox 
function;  it  is  updated  each  time  your  application  calls  a  Movie  Toolbox  function. 
The  following  code  sample  shows  a  typical  use: 

//  GetMoviesError  coding  example 

//  See  “Discovering  QuickTime,”  page  256 

OSErr  QTUti 1 s_SaveMovi e  (Movie  theMovie) 

{ 

StandardFi 1 eReply  mySFReply; 

StringPtr  myPrompt  =  QTUti 1 s_ConvertCToPascal String( kSavePrompt) ; 

StringPtr  myFileName  = 

QTUti 1 s_ConvertCToPascal String ( kSaveMovieFi 1 eName) ; 

OSErr  myErr  =  noErr; 

i f  ( theMovi e  ==  NIL) 

return (inval idMovie) ; 

StandardPutFi 1 e(myPrompt ,  myFileName,  &mySFReply); 
if  (mySFReply. sfGood)  { 

FI attenMovi eData (  theMovie, 

fl attenAddMovi eToDataFork, 

&mySFReply .  sf  Fi  1  e , 

F0UR_CHAR_C0DE( 'TVOD' ) , 
smSystemScri pt , 

createMovi eFi 1 eDel eteCurFi 1 e) ; 
myErr  =  GetMoviesError! ) ; 

} 

f ree(myPrompt ) ; 
f ree(myFi 1 eName) ; 
return(myErr) ; 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Error  Functions"  (V-2712) 

See  Also 

See  GetMovi  esSti  ckyError  (1-494). 
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GetMoviesStickyError 


GetMoviesStickyError 

Returns  the  contents  of  the  sticky  error  value. 

OSErr  GetMoviesStickyError  (  void  ); 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error  in  the 

sticky  error  value. 

Discussion 

The  sticky  error  value  contains  the  first  nonzero  result  code  from  any  Movie 
Toolbox  function  that  you  called  after  having  cleared  the  sticky  error  with 
Cl  earMovi  esSti  ckyError  (1-90). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Error  Functions"  (V-2712) 

See  Also 

See  GetMovi esError  (1-492). 


GetMovieStatus 


Searches  for  errors  in  all  the  enabled  tracks  of  the  movie  and  returns  information 
about  errors  that  are  encountered  during  the  processing  associated  with  the 
Movi  esTask  function. 

ComponentResul t  GetMovieStatus  ( 

Movie  theMovie, 

Track  *f i rstProbl emTrack  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

f i rstProbl emT  rack 

A  pointer  to  a  track  identifier.  The  Movie  Toolbox  places  the  identifier  for  the 
first  track  that  is  found  to  contain  an  error  into  the  field  referred  to  by  this 
parameter.  If  you  don't  want  to  receive  the  track  identifier,  set  this  parameter 
to  NIL. 
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function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error  in  the 
movie  status  value. 

Discussion 

This  function  returns  information  about  errors  that  are  encountered  during 
MoviesTask  (11-973)  execution.  These  errors  typically  reflect  playback  problems, 
such  as  low-memory  conditions.  GetMovi  eStatus  returns  the  error  associated  with 
the  first  problem  track. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Movies  and  Your  Event  Loop"  (V-2720) 

Related  Java  Methods 

qui cktime . std .movi es . Movi e . getStatusl ) 


GetMovieTime 


Returns  a  movie's  current  time  both  as  a  time  value  and  in  a  time  structure. 

TimeValue  GetMovieTime  ( 

Movie  theMovie, 

TimeRecord  *currentTime  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
currentT i me 

A  pointer  to  a  Ti  meRecord  (IV-2486)  structure.  The  function  updates  this  time 
structure  to  contain  the  movie's  current  time.  If  you  don't  want  this 
information,  set  this  parameter  to  NIL. 

function  result  The  time  value  of  the  current  time. 

Discussion 

This  function  returns  the  movie's  current  time  value  in  two  formats:  as  a  time  value 
and  in  a  time  structure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  Time"  (V-2732) 

Related  Java  Methods 

qui ckti me. std. movies. Movi e.getTi met ) ,  quicktime.std.movies.Movie.getTRTimet ) 


See  Also 

For  the  corresponding  set  function,  see  SetMovi  eT i me  (III— 1634). 


GetMovieTimeBase 


Returns  a  movie's  time  base. 

TimeBase  GetMovieTimeBase  ( 

Movi e  theMovi e  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  The  movie's  TimeBaseRecord  (IV-2481)  structure. 

Special  Considerations 

The  Movie  Toolbox  disposes  of  a  movie's  time  base  when  you  dispose  of  the  movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  Time"  (V-2732) 

Related  Java  Methods 

qui ckti me. std. movies. Movi e.getTi me Baset ) , 
qui ckti me . std . cl ocks .TimeBase . fromMovi e( ) 


GetMovieTimeScale 


Returns  the  time  scale  of  a  movie. 

TimeScale  GetMovieTimeScale  ( 
Movi e  theMovi e  ) ; 
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theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  A  long  integer  that  contains  the  movie's  time  scale. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  Time"  (V-2732) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . getTi meScal e( ) 

See  Also 

For  the  corresponding  set  function,  see  SetMovi  eTi meScal  e  (III— 1635). 


GetMo  vieT  rack 


Determines  the  track  identifier  of  a  track,  given  the  track's  ID  value. 

Track  GetMovieTrack  ( 

Movie  theMovie, 

long  trackID  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
trackID 

The  ID  value  of  the  track  for  this  operation. 
function  result  A  track  identifier. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Locating  a  Movie's  Tracks  and  Media  Structures" 
(Y-2736) 
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GetMovieTrackCount 


Related  Java  Methods 

qui cktime. std .movi es .Movi e . getTrack( ) 

GetMovieT  rackCount 

Returns  the  number  of  tracks  in  a  movie. 

long  GetMovieTrackCount  ( 

Movi e  theMovi e  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  The  number  of  tracks  in  the  movie. 

Discussion 

The  following  code  sample  illustrates  the  use  of  GetMovi  eT rackCount: 

//  GetMovieTrackCount  coding  example 
//  See  “Discovering  QuickTime,”  page  363 
Movie  moviel; 

TimeValue  1 01 dDurati on ; 

Movie  movie2; 

long  llndex,  1 Ori gTrackCount ,  1 Referencelndex ; 

Track  track,  trackSprite; 

//  get  the  first  track  in  original  movie  and  position  at  the  start 
trackSprite  =  GetMovi elndTracktmovi el ,  1); 

SetMovi eSel ecti on (movi el ,  0,  0); 

//  remove  all  tracks  except  video  in  modifier  movie 

for  (llndex  =  1;  llndex  <=  GetMovi eTrackCounttmovi e2) ;  llndex++)  { 

Track  track  =  GetMovi elndTracktmovi e2 ,  llndex); 

OSType  dwType; 

GetMedi aHandlerDescriptiontGetT  rackMedi a ( track) , 

&dwType ,  NIL,  NIL); 
if  (dwType  !=  Vi deoMedi aType )  { 

DisposeMovieTrackt track) ; 

1  Index- - ; 
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} 

} 

//  add  the  modifier  track  to  original  movie 
lOldDuration  =  GetMovi eDurati onlmoviel ) ; 

AddMovi eSel ecti onlmovi el ,  movi e2 ) ; 

Di sposeMovi e(movi e2) ; 

//  truncate  the  movie  to  the  length  of  the  original  track 
Del eteMovi eSegment(movi el,  lOldDuration, 

GetMovi eDuration(moviel)  -  lOldDuration); 

//  associate  the  modifier  track  with  the  original  sprite  track 
track  =  GetMovi elndTracklmovi el ,  1 Ori gTrackCount  +  1); 

AddT rackReferencel trackSpri te ,  track,  kTrackModi f i er Reference , 

&1 Referencelndex) ; 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Locating  a  Movie's  Tracks  and  Media  Structures" 
(V-2736) 

Related  Java  Methods 

qui  ckti me .  std  .movi  es  .  Movi  e .  getT rackCountO 


GetMovieUserData 


Obtains  access  to  a  movie's  user  data  list. 

UserData  GetMovieUserData  ( 

Movie  theMovie  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  The  UserDataRecord  (IV-2496)  structure  for  the  movie.  If  the  function 
could  not  locate  the  movie's  user  data,  it  sets  this  return  value  to  N I L. 
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GetMovie  Volume 


Discussion 

This  function  returns  a  reference  to  the  movie's  user  data  list,  which  is  valid  until 
you  dispose  of  the  movie.  When  you  save  the  movie,  the  Movie  Toolbox  saves  the 
user  data  as  well. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  User  Data"  (V-2743) 

Related  Java  Methods 

qu i c kti me. std. mo vies. media. User Data .  f romMovi e( ) , 
qui ckti me. std .movi es .Movi e. getUserData ( ) 


See  Also 

You  can  use  GetUserData  (1-547),  AddUserData  (1-44)  and  RemoveUserData  (III— 1459) 
to  manipulate  the  contents  of  the  user  data  list.  If  the  data  list  contains  text  data,  you 
can  use  GetUserDataText  (1-549),  AddUserDataText  (1-45),  and  RemoveUserDataText 
(III— 1460)  to  work  with  its  contents. 


GetMovie  V  olume 


Returns  a  movie's  current  volume  setting. 

short  GetMovi eVol ume  ( 

Movi e  theMovi e  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  The  current  volume  setting  for  the  movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Sound  Volume"  (V-2732) 

Related  Java  Methods 

qui ckti me. std. mo vies. Mo vie. getVol ume( ) 
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See  Also 

For  the  corresponding  set  function,  see  SetMovi  eVol  ume  (III— 1637). 


GetNextCallBack 


Returns  the  next  callback  event  associated  with  a  specified  time  base. 

QTCallBack  GetNextCallBack  ( 

QTCallBack  cb  ); 


cb 

Specifies  the  starting  callback  event  for  the  operation.  Your  clock  component 
obtains  this  value  from  the  GetFi  rstCallBack  (1-411)  function  or  from  previous 
calls  to  the  GetNextCal  1  Back  function. 

function  result  A  pointer  to  a  Cal  1  BackRecord  (IV-2165)  structure.  Your  software  can 
pass  this  structure  to  other  functions,  such  as  Cl  ockRateChanged 
(1-97). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Movie  Toolbox  Clock  Support  Functions"  (V-2869) 


GetNextlmageDescriptionExtensionType 


Retrieves  an  image  description  structure  extension  type. 

OSErr  GetNextlmageDescri pti onExtensi onType  ( 
ImageDescri pti onHandl e  desc, 

long  *idType  ); 


desc 

A  handle  to  an  ImageDescri  pti  on  (IV-2285)  structure, 
i dType 

A  pointer  to  an  integer  that  indicates  the  type  of  the  extension  after  which  this 
function  is  to  return  the  next  extension  type.  Poi  nt  to  a  value  of  0  to  return  the 
first  type  found. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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GetNextTrackForCompositing 


Discussion 

This  function  allows  your  application  to  search  for  all  the  types  of  extensions  in  an 
ImageDescri  pti  on  (IV-2285)  structure.  The  i  dType  parameter  should  be  set  to  0  to 
start  the  search.  When  no  more  extension  types  can  be  found,  the  function  will  set 
this  field  to  0. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Image  Descriptions"  (V-2790) 


GetNextTrackForCompositing 


Determines  the  next  track  in  a  movie's  compositing  process. 

Track  GetNextTrackForCompositing  ( 

Movie  theMovie, 

T rack  theT rack  ) ; 

theMovi e 

A  movie  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e 
(11-1084). 

theT  rack 

The  identifier  of  the  track  from  which  to  start. 
function  result  The  returned  identifier  of  the  next  track  to  be  composited. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . getNextT  rackForComposi ti ng( ) 


See  Also 

See  GetPrevT rackForComposi  ti  ng  (1-506). 
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GetNextT  rackRef  erenceT  y  pe 

Determines  all  of  the  track  reference  types  that  are  defined  for  a  given  track. 

OSType  GetNextTrackReferenceType  ( 

Track  theTrack, 

OSType  refType  ) ; 

theT  rack 

Identifies  the  track  for  this  operation.  Your  application  obtains  this  track 
identifier  from  such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack 
(1-497). 

refType 

The  type  of  reference.  Set  this  parameter  to  0  to  retrieve  the  first  track  reference 
type.  On  subsequent  requests,  use  the  previous  value  returned  by  this  function. 

function  result  An  OSType  containing  the  next  track  reference  type  value  defined  for 
the  track;  see  "Data  References"  (IV-2661). 

Discussion 

There  is  no  implied  ordering  of  the  values  returned  by  this  function  .  When  you 
reach  the  end  of  the  track's  reference  types,  this  function  sets  the  returned  value  to  0. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Track  References"  (V-2737) 

Related  Java  Methods 

qui ckti me . std .movi  es . Track, get Next Ref erenceType( ) 


GetNextUserDataType 


Retrieves  the  next  user  data  type  in  a  specified  user  data  list. 

long  GetNextUserDataType  ( 

UserData  theUserData, 

OSType  udType  ) ; 
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theUserData 

The  user  data  list  for  this  operation.  You  obtain  this  list  reference  by  calling  the 
GetMovi  ellserData  (1-499),  GetTrackUserData  (1-546),  or  GetMedi  aUserData 
(1-456)  function. 
udType 

Specifies  a  user  data  field;  see  "User  Data  Identifiers"  (IV-2696).  Set  this 
parameter  to  0  to  retrieve  the  first  user  data  field  in  the  user  data  list.  On 
subsequent  requests,  use  the  previous  value  returned  by  this  function. 

function  result  The  next  user  data  type  in  the  list.  Returns  0  when  there  are  no  more 
user  data  types. 

Discussion 

Use  this  function  to  scan  all  the  user  data  types  in  a  user  data  list. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  User  Data"  (V-2743) 

Related  Java  Methods 

qu i c kti me. std. mo vies. media. User Data. getNextType( ) 


GetPictureFileHeader 


Extracts  the  picture  frame  and  file  header  from  a  specified  picture  file. 

OSErr  GetPictureFileHeader  ( 
short  refNum, 

Rect  *frame, 

OpenCPi cParams  *header  ); 

refNum 

A  file  reference  number  for  the  source  PICT  file, 
frame 

A  pointer  to  a  rectangle  that  is  to  receive  the  picture  frame  rectangle  of  the 
picture  file.  This  function  places  the  pi  cFrame  rectangle  from  the  picture 
structure  into  the  rectangle  referred  to  by  the  frame  parameter.  If  you  are  not 
interested  in  this  information,  pass  N I L  in  this  parameter. 
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header 

A  pointer  to  an  OpenCPi  cParams  (IV-2326)  structure.  The  GetPi  ctureFi  1  eHeader 
function  places  the  header  from  the  specified  picture  file  into  this  structure.  If 
you  are  not  interested  in  this  information,  pass  NI L  in  this  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  program  can  use  the  information  returned  in  the  header  parameter  to 
determine  how  to  draw  an  image  without  having  to  read  the  picture  file. 

Special  Considerations 

Note  that  this  function  always  returns  a  version  2  header.  If  the  source  file  is  a 
version  1  PICT  file,  the  GetPi  ctureFi  1  eHeader  function  converts  the  header  into 
version  2  format  before  returning  it  to  your  application.  See  Inside  Macintosh: 
Imaging  With  QuickDrazv  (listed  in  the  bibliography)  for  more  information  about 
picture  headers. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Pictures  and  PICT  Files"  (V-2790) 


GetPosterBox 


Obtains  a  poster's  boundary  rectangle. 

void  GetPosterBox  ( 

Movie  theMovie, 

Rect  *boxRect  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

boxRect 

A  pointer  to  a  rectangle.  The  Movie  Toolbox  returns  the  poster's  boundary 
rectangle  into  the  structure  referred  to  by  this  parameter. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Movie  Posters  and  Movie  Previews"  (V-2718) 

Related  Java  Methods 

quicktime.std.movies.Movie.getPosterBoxO 


See  Also 

For  the  corresponding  set  function,  see  SetPosterBox  (III— 1638). 


GetPre  vT  rackForCompositing 


Determines  the  previous  track  in  a  movie's  compositing  process. 

Track  GetPrevTrackForCompositing  ( 

Movie  theMovie, 

T rack  theT rack  ) ; 


theMovi e 

A  movie  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e 
(11-1084). 
theT  rack 

The  identifier  of  the  track  from  which  to  start. 


function  result  The  returned  identifier  of  the  previous  track  in  the  compositing 
process. 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  Movi  es .  h 


Related  Java  Methods 

quicktime.std.movies.Movie.getPrevT  rackForComposi ti ng( ) 


See  Also 

See  GetNextT rackForComposi  ti  ng  (1-502). 
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GetQuickT  imePref  erence 

Retrieves  a  particular  preference  from  the  QuickTime  preferences. 

OSErr  GetQuickTimePreference  ( 

OSType  preferenceType , 

QTAtomContai ner  *preferenceAtom  ); 

preferenceType 

A  preference  type  to  be  retrieved  (see  below);  see  "Atom  ID  Codes"  (IV-2649). 
preferenceAtom 

A  pointer  to  the  returned  preference  atom. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

preferenceType  Constants 

Connecti onSpeedPref sType 

The  connection  speed  currently  set  in  the  QuickTime  Preferences;  the  atom  type 
returned  in  preferenceAtom  is  '  cspd ' . 

Bandwi dthManagementPref sType 

The  user's  current  bandwidth  management  preference;  the  atom  type  returned 
in  preferenceAtom  is  ’bwmg'. 

Discussion 

The  following  sample  code  shows  how  to  retrieve  the  connection  speed  setting  from 
the  QuickTime  preferences: 

struct  ConnectionSpeedPrefsRecord  { 
long  connecti onSpeed ; 

}; 

typedef  struct  ConnectionSpeedPrefsRecord  ConnectionSpeedPrefsRecord; 


OSErr  err; 

QTAtomContai ner  prefs; 

QTAtom  prefsAtom; 

long  dataSize; 

Ptr  atomData; 

ConnectionSpeedPrefsRecord  prefrec; 

err  =  GetQuickTimePreferenceCConnectionSpeedPrefsType,  &amp;prefs); 
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if  (err  ==  noErr)  { 

prefsAtom  =  QTFi ndChi 1 dBy IDCprefs ,  kParentAtomlsContainer , 

Connecti onSpeedPrefsType ,  1,  nil); 

if  ( IprefsAtom)  { 

//  set  the  default  setting  to  28.8kpbs 

prefrec . connecti onSpeed  =  kDataRate288ModemRate ; 

}  else  { 

err  =  QTGetAtomDataPtrtprefs ,  prefsAtom,  &amp ; dataSi ze , 

&amp  ;  atomData ) ; 

if  (dataSize  !=  sizeof(ConnectionSpeedPrefsRecord) )  { 

//  the  prefs  record  wasn't  the  right  size, 

//  so  it  must  be  corrupt  --  set  to  the  default 
prefrec . connecti onSpeed  =  kDataRate288ModemRate ; 

}  else  { 

//  everything  was  fine  --  read  the  connection  speed 
prefrec  =  *( Connecti onSpeedPrefsRecord  *)atomData; 

} 

} 

QTDi sposeAtomContai ner ( prefs ) ; 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

See  Also 

For  the  corresponding  set  function,  see  SetQui  ckT i mePreference  (III— 1639). 


GetSimilarity 


Compares  a  compressed  image  to  a  picture  stored  in  a  pixel  map  and  returns  a  value 
indicating  the  relative  similarity  of  the  two  images. 


OSErr  GetSimilarity  ( 

Pi xMapHandl e 
const  Rect 

ImageDescriptionHandle 

Ptr 

Fi  xed 


src , 

*srcRect , 
desc , 
data , 

*si mi  1 ari ty  ) ; 
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src 

A  handle  to  the  noncompressed  image.  The  image  must  be  stored  in  a  pixel 
map  structure. 

srcRect 

A  pointer  to  a  rectangle  defining  the  portion  of  the  image  to  compare  to  the 
compressed  image.  This  rectangle  should  be  the  same  size  as  the  image 
described  by  the  ImageDescri  pti  on  (IV-2285)  structure  specified  by  the  desc 
parameter. 

desc 

A  handle  to  the  ImageDescri  pti  on  (IV-2285)  structure  that  defines  the 
compressed  image  for  the  operation. 

data 

Points  to  the  compressed  image  data.  This  pointer  must  contain  a  32-bit  clean 
address, 
si  mi  1 ari ty 

A  pointer  to  a  field  that  is  to  receive  the  similarity  value.  The  compressor  sets 
this  field  to  reflect  the  relative  similarity  of  the  two  images.  Valid  values  range 
from  0  (completely  different)  to  1.0  (identical). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Getting  Information  About  Compressed  Data"  (V-2787) 

Related  Java  Methods 

qui cktime . std . image . QTImage . getSimi 1 ari ty ( ) 


GetSoundDescriptionExtension 


Gets  the  current  extension  to  a  SoundDescri  pti  on  (IV-2449)  structure. 

OSErr  GetSoundDescriptionExtension  ( 

SoundDescri pti onHandl e  desc. 

Handle  *extension, 

OSType  idType  ); 


desc 

A  handle  to  a  SoundDescri  pti  on  (IV-2449)  structure. 
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extensi on 

A  pointer  to  a  handle  that,  on  return,  contains  the  extension, 
i dType 

A  four-byte  signature  that  identifies  the  type  of  data  in  the  extension. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Related  Java  Methods 

qui ckti me . uti 1 . QTHandl e .  f romSoundDescri pti on ( ) , 

quickti me. std. mo vies. media. Sound Description, get Extensi on ( ) 


GetSoundHeaderOffset 


Gets  the  offset  from  the  beginning  of  a  sound  resource  to  the  embedded  sound 
header. 

OSErr  GetSoundHeaderOffset  ( 

SndLi stHandl e  sndHandle, 

1 ong  *offset  ) ; 

sndHandl e 

A  handle  to  a  SndLi  stResource  (IV-2447)  structure, 
offset 

On  exit,  the  offset  in  bytes  from  the  beginning  of  the  sound  resource  specified 
by  the  s  n  d  H  d  1  parameter  to  the  beginning  of  the  sound  header  within  that  sound 
resource. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns  the  number  of  bytes  from  the  beginning  of  the  sound  resource 
to  the  sound  header  that  is  contained  within  that  resource.  You  might  need  this 
information  if  you  want  to  use  the  address  of  that  sound  header  in  a  sound 
command  (such  as  soundCmd  or  buf  f  erCmd).  The  handle  passed  to 
GetSoundHeaderOffset  does  not  have  to  be  locked. 
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Special  Considerations 

You  can  call  the  GetSoundHeaderOf  fset  function  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

Related  Java  Methods 

qui  ckti  me. sound. SndHandle. get  SoundHeaderOffsetO 


GetSoundOutputlnfo 


Gets  information  about  the  current  sound  environment. 

OSErr  GetSoundOutputlnfo  ( 

Component  outputDevi ce , 

OSType  selector, 

void  *infoPtr  ); 

outputDevi ce 

The  identifier  of  a  sound  output  component.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131).  To 
access  the  default  output  device,  pass  N I L. 

sel ector 

The  selector  for  the  information  you  want;  see  "Sound  Information  Selectors" 
(IV-2693). 

l nf oPtr 

A  pointer  to  the  returned  sound  device  information. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  routine  operates  directly  on  the  sound  output  device  and  can  be  used  to 
retrieve  information  about  the  hardware  settings. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

For  the  corresponding  set  function,  see  SetSoundOutputlnfo  (ill-1640). 
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GetSoundPreference 


Reads  a  block  of  preferences  data  from  a  sound  resource  file. 

OSErr  GetSoundPreference  ( 

OSType  theType, 

Str255  name, 

Handl e  setti ngs  ) ; 

theType 

The  resource  type  of  the  preferences  resource. 

name 

The  resource  name  of  the  preferences  resource, 
setti ngs 

A  handle  to  the  data  in  the  preferences  resource. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  retrieves  the  block  of  preferences  data  you  previously  stored  in  a 
resource  by  calling  SetSoundPreference  (III— 1641).  It  is  the  responsibility  of  your 
component  to  allocate  the  block  of  data  referenced  by  the  settings  parameter.  The 
Sound  Manager  resizes  the  handle  (if  necessary)  and  fills  it  with  data  from  the 
resource  with  the  specified  type  and  name.  Your  sound  component  should  dispose 
of  the  handle  once  it  has  finished  reading  the  data  from  it. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

For  the  corresponding  set  function,  see  SetSoundPreference  (III— 1641). 


GetSpriteProperty 


Retrieves  the  value  of  a  specified  sprite  property. 

OSErr  GetSpriteProperty  ( 

Sprite  theSprite, 

long  propertyType , 

void  *propertyVal ue  ); 
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theSpri te 

The  sprite  for  this  operation. 
propertyType 

The  property  whose  value  should  be  retrieved  (see  below). 
propertyVal ue 

A  pointer  to  a  variable  that  will  hold  the  selected  property  value  on  return. 
Depending  on  the  property  type,  this  parameter  is  either  a  pointer  to  the 
property  value  or  the  property  value  itself,  cast  as  a  voi  d  pointer. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

propertyType  Constants 

kSpri tePropertyMatri x 

The  propertyVal  ue  parameter  returns  the  sprite's  MatrixRecord  (IV-2304) 
structure. 

kSpri te Property ImageDescri  pti  on 

The  propertyVal  ue  parameter  returns  an  ImageDescri  pti  onHandl  e,  which  is  a 
handle  to  the  sprite's  ImageDescri  pti  on  (IV-2285)  structure. 

kSpri tePropertylmageDataPtr 

The  propertyVal  ue  parameter  returns  a  Ptr,  which  is  a  pointer  to  the  sprite's 
image  data. 

kSpri tePropertyVi si bl e 

The  propertyVal  ue  parameter  returns  a  Bool  ean  that  is  TRUE  if  the  sprite  is 
visible,  FALSE  otherwise. 
kSpri te Property Layer 

The  propertyVal  ue  parameter  returns  the  sprite's  layer  number. 
kSpri tePropertyGraphi csMode 

The  propertyVal  ue  parameter  returns  the  sprite's 
ModifierTrackGraphi  csMode  Record  (IV-2311). 

Discussion 

You  call  this  function  to  retrieve  the  value  of  a  sprite  property,  setting  the 
propertyType  parameter  to  the  type  of  the  property  you  want  to  retrieve. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Creating  and  Manipulating  Sprites"  (V-2901) 
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Related  Java  Methods 

qui ckti me . uti 1 . Raw Encoded  Image . f romSpri te( ) , 

qu i c kt i me. std. an im. Sprite. get Matrix! ) , 

qu  i  c  kt  i  me. std. anim. Sprite. getl  mageDescriptlonO, 

qu i c kti me. std. an im. Sprite. getl mage Da tat ) , 

qui ckti me. std. an im. Sprite. getVisiblet ) , 

qui ckti me. std. anim. Sprite. get  Layer ( ) , 

qu i c kti me. std. an im. Sprite. getGraphicsModet), 

qu i ckti me. std. anim. Sprite. getl mage Da taSizet ) , 

qui ckti me . std . i mage . ImageDescri pti on . f romSpri te( ) 

See  Also 

For  the  corresponding  set  function,  see  SetSpri  teProperty  (III— 1641). 


GetSysBeep  V  olume 


Determines  the  current  volume  of  the  system  alert  sound. 

OSErr  GetSysBeepVol ume  ( 

1 ong  *1 evel  ) ; 


1  evel 

On  exit,  a  pointer  to  the  current  volume  level  of  the  system  alert  sound.  The 
value  may  range  from  0x0000  (silence)  to  0x0100  (full  volume). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

For  the  corresponding  set  function,  see  SetSysBeepVol  ume  (III— 1647). 


GetTimeBaseEffectiveRate 


Returns  the  effective  rate  at  which  the  specified  time  base  is  moving  relative  to  its 
master  clock. 

Fixed  GetTimeBaseEffectiveRate  ( 

TimeBase  tb  ) ; 
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tb 

The  time  base  for  this  operation.  Your  application  obtains  this  time  base 
identifier  from  the  NewTimeBase  (11-1119)  function. 

function  result  The  effective  rate  at  which  the  time  base  specified  by  tb  is  moving 
relative  to  its  master  clock. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Time  Base  Values"  (V-2760) 

Related  Java  Methods 

qui ckti me . std . cl ocks .TimeBase . get Effect! veRate( ) 


GetTimeBaseFlags 

Obtains  the  control  flags  of  a  time  base. 

long  GetTimeBaseFlags  ( 

TimeBase  tb  ); 


tb 

The  time  base  for  this  operation.  Your  application  obtains  this  time  base 
identifier  from  NewTimeBase  (11-1119). 

function  result  Control  flags  (see  below).  Unused  flags  are  set  to  0. 

Function  Result  Constants 

1 oopTimeBase 

Indicates  whether  or  not  the  time  base  loops.  If  this  flag  is  set  to  1  and  the  rate 
is  positive,  the  time  base  loops  back  and  restarts  from  its  start  time  when  it 
reaches  its  stop  time.  If  this  flag  is  set  to  1  and  the  rate  is  negative,  the  time  base 
loops  to  its  stop  time.  If  the  flag  is  set  to  0,  the  movie  stops  when  it  reaches  the 
end. 

pal i ndromeLoopTi meBase 

If  this  flag  is  set  to  1,  it  indicates  that  the  time  base  loops  in  a  palindromic 
fashion.  Palindromic  looping  causes  a  time  base  to  move  alternately  forward 
and  backward. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Time  Base  Values"  (V-2760) 

Related  Java  Methods 

qu ickti me. std. clocks. Time Base. getFlagsO 


See  Also 

For  the  corresponding  set  function,  see  SetT i meBaseFl  ags  (III— 1648). 


GetTimeBaseMasterClock 

Determines  the  clock  component  that  is  assigned  to  a  time  base. 

Componentlnstance  GetTimeBaseMasterClock  ( 

T i meBase  tb  ) ; 


tb 

The  time  base  for  this  operation.  Your  application  obtains  this  time  base 
identifier  from  the  NewTimeBase  (11-1119)  function. 

function  result  A  reference  to  a  component  instance.  If  a  clock  component  is  not 

assigned  to  the  time  base,  the  returned  reference  is  N I L.  In  this  case, 
the  time  base  relies  on  another  time  base  for  its  time  source.  Use 
GetTimeBaseMasterTi  meBase  (1-517)  to  obtain  the  time  base  reference 
to  that  master  time  base. 

Discussion 

This  function  returns  a  reference  to  a  component  instance  of  the  clock  component 
that  provides  a  time  source  to  the  specified  time  base.  Every  time  base  derives  its 
time  from  either  a  clock  component  or  from  another  time  base.  If  a  time  base  derives 
its  time  from  a  clock  component,  use  this  function  to  obtain  the  component  instance 
of  the  clock  component. 

Special  Considerations 

The  Component  Manager  allows  a  single  component  to  serve  multiple  client 
applications  at  the  same  time.  Each  client  application  has  a  unique  connection  to  the 
component,  identified  by  a  component  instance.  Don't  close  this  connection;  the 
time  base  is  using  it  to  maintain  its  time  source. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Creating  and  Disposing  of  Time  Bases"  (V-2759) 

Related  Java  Methods 

qui cktime . std . cl ocks . TimeBase . getMasterCl ock( ) 


See  Also 

For  the  corresponding  set  function,  see  SetTi  meBaseMasterCl  ock  (III— 1649). 


GetTimeBaseMasterTimeBase 

Determines  the  master  time  base  that  is  assigned  to  a  time  base. 

TimeBase  GetTimeBaseMasterTimeBase  ( 

TimeBase  tb  ); 


tb 

The  time  base  for  this  operation.  Your  application  obtains  this  time  base 
identifier  from  NewTimeBase  (11-1119). 

function  result  A  time  base.  If  a  master  time  base  is  not  assigned  to  the  time  base,  this 
function  sets  the  returned  reference  to  N I L.  In  this  case,  the  time  base 
relies  on  a  clock  component  for  its  time  source.  Use 
GetTimeBaseMasterCl  ock  (1-516)  to  obtain  the  component  instance 
reference  to  that  clock  component. 

Discussion 

This  function  returns  a  reference  to  the  master  time  base  that  provides  a  time  source 
to  this  time  base.  A  time  base  derives  its  time  from  either  a  clock  component  or  from 
another  time  base.  If  a  time  base  derives  its  time  from  another  time  base,  use  this 
function  to  obtain  the  identifier  for  that  master  time  base. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Creating  and  Disposing  of  Time  Bases"  (V-2759) 

Related  Java  Methods 

qui cktime . std . cl ocks . TimeBase . getMasterT imeBaseC ) 


See  Also 

For  the  corresponding  set  function,  see  SetTi  meBaseMasterTimeBase  (III— 1650). 
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GetTimeBaseRate 


GetTimeBaseRate 

Retrieves  the  rate  of  a  time  base. 

Fixed  GetTimeBaseRate  ( 

T i meBase  tb  ) ; 


tb 

The  time  base  for  this  operation.  Your  application  obtains  this  time  base 
identifier  from  the  NewTimeBase  (11-1119)  function. 

function  result  The  time  base's  rate.  This  rate  value  may  be  nonzero  even  if  the  time 
base  has  stopped,  because  it  has  reached  its  stop  time.  Rates  may  be 
set  to  negative  values,  which  cause  time  to  move  backward  for  the 
time  base. 

Discussion 

This  function  returns  the  current  rate  of  the  time  base  as  a  fixed-point  number. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Time  Base  Values"  (V-2760) 

Related  Java  Methods 

qu i c kt i me. std. clocks. Time Base. get RateO 


See  Also 

For  the  corresponding  set  function,  see  SetT i meBaseRate  (III— 1651). 


GetTimeBaseStartTime 


Determines  the  start  time  of  a  time  base. 

TimeValue  GetTimeBaseStartTime  ( 
TimeBase  tb, 

TimeScale  s, 

TimeRecord  *tr  ) ; 


The  time  base  for  this  operation.  Your  application  obtains  this  time  base 
identifier  from  the  NewTimeBase  (11-1119)  function. 
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s 

The  time  scale  in  which  to  return  the  start  time, 
tr 

A  pointer  to  a  time  structure  that  is  to  receive  the  start  time.  This  is  an  optional 
parameter.  If  you  don't  want  the  time  value  represented  in  a  time  structure,  set 
this  parameter  to  NIL. 

function  result  The  time  base's  start  time. 

Discussion 

This  function  returns  a  time  value  that  contains  the  start  time  for  the  specified  time 
base  in  the  specified  time  scale.  The  function  returns  this  value  even  if  you  specify 
a  time  structure  with  the  tr  parameter. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Time  Base  Values"  (V-2760) 

Related  Java  Methods 

qui cktime . std . cl ocks . TimeBase . getStartTi me( ) , 
qui cktime . std . cl ocks . TimeBase . getTRStartTI me( ) 


See  Also 

For  the  corresponding  set  function,  see  SetTi  meBaseStartTi  me  (III— 1652). 


GetTimeBaseStatus 


Determines  when  the  current  time  of  a  time  base  would  fall  outside  of  the  range  of 
values  specified  by  the  time  base's  start  and  stop  times. 

long  GetTimeBaseStatus  ( 

TimeBase  tb, 

TimeRecord  *unpi nnedTime  ); 


tb 

The  time  base  for  this  operation.  Your  application  obtains  this  time  base 
identifier  from  the  NewTimeBase  (11-1119)  function. 

unpi nnedT i me 

A  pointer  to  a  time  structure  that  is  to  receive  the  current  time  of  the  time  base. 
Note  that  this  time  value  may  be  outside  the  range  of  values  specified  by  the 
start  and  stop  times  of  the  time  base. 
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GetTimeBaseStopTime 


function  result  Status  flags  (see  below). 

Function  Result  Constants 

timeBaseBeforeStartTime 

Indicates  that  the  time  value  represented  by  the  contents  of  the  time  structure 
referred  to  by  the  unpinnedTime  parameter  lies  before  the  start  time  of  the  time 
base.  The  Movie  Toolbox  sets  this  flag  to  1  if  the  current  time  is  before  the  start 
time  of  the  time  base, 
ti meBaseAfterStopT  i  me 

Indicates  that  the  time  value  represented  by  the  contents  of  the  time  structure 
referred  to  by  the  unpinnedTime  parameter  lies  after  the  stop  time  of  the  time 
base.  The  Movie  Toolbox  sets  this  flag  to  1  if  the  current  time  is  after  the  stop 
time  of  the  time  base. 

Discussion 

The  status  information  returned  by  this  function  allows  you  to  determine  when  the 
current  time  of  a  time  base  would  fall  outside  of  the  range  of  values  specified  by  the 
start  and  stop  times  of  the  time  base.  This  can  happen  when  a  time  base  relies  on  a 
master  time  base  or  when  its  time  has  reached  the  stop  time. 

Special  Considerations 

This  function  returns  no  error  codes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Time  Base  Values"  (V-2760) 

Related  Java  Methods 

qu i ckti me. std. clocks. Time Base. getStatusO 


See  Also 


See  GetTimeBaseFl  ags  (1-515). 


GetTimeBaseStopTime 


Determines  the  stop  time  of  a  time  base. 

TimeValue  GetTimeBaseStopTime  ( 
TimeBase  tb, 

TimeScale  s, 

TimeRecord  *tr  ) ; 
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tb 

The  time  base  for  this  operation.  Your  application  obtains  this  time  base 
identifier  from  the  NewTimeBase  (11-1119)  function. 

s 

The  time  scale  in  which  to  return  the  stop  time, 
tr 

A  pointer  to  a  time  structure  that  is  to  receive  the  stop  time.  This  is  an  optional 
parameter.  If  you  don't  want  the  time  value  represented  in  a  time  structure,  set 
this  parameter  to  NIL. 

function  result  The  time  base's  stop  time. 

Discussion 

This  function  returns  a  time  value  that  contains  the  stop  time  for  the  specified  time 
base  in  the  specified  time  scale.  The  function  returns  this  value  even  if  you  specify 
a  time  structure  with  the  tr  parameter. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Time  Base  Values"  (V-2760) 

Related  Java  Methods 

qui cktime . std . cl ocks .TimeBase . getStopTime( ) , 
qui cktime . std . cl ocks .TimeBase . getTRStopT ime( ) 


See  Also 

For  the  corresponding  set  function,  see  SetTi  meBaseStopTi  me  (III— 1652). 


GetTimeBaseTime 


Obtains  the  current  time  value  from  a  time  base. 

TimeValue  GetTimeBaseTime  ( 

TimeBase  tb, 

T i meScal e  s  , 

TimeRecord  *tr  ); 


The  time  base  for  this  operation.  Your  application  obtains  this  time  base 
identifier  from  the  NewTimeBase  (11-1119)  function. 
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G  etTrack  Alternate 


s 

The  time  scale  in  which  to  return  the  current  time  value.  Set  this  parameter  to  0 
to  retrieve  the  time  in  the  preferred  time  scale  of  the  time  base, 
tr 

A  pointer  to  a  time  structure  that  is  to  receive  the  current  time  value.  This  is  an 
optional  parameter.  If  you  don't  want  the  time  value  represented  in  a  time 
structure,  set  this  parameter  to  NIL. 

function  result  The  time  base's  current  time. 

Discussion 

This  function  returns  a  time  value  that  contains  the  current  time  from  the  specified 
time  base  in  the  specified  time  scale.  The  function  returns  this  value  even  if  you 
specify  a  time  structure  with  the  tr  parameter. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Time  Base  Values"  (V-2760) 

Related  Java  Methods 

qui cktime. std . cl ocks .TimeBase. getTimet ) , 
qui cktime. std . cl ocks .TimeBase. getTRTime( ) 


See  Also 

For  the  corresponding  set  function,  see  SetT i meBaseT i me  (III— 1653). 


GetT  rackAlternate 

Determines  all  the  tracks  in  an  alternate  group. 

Track  GetTrackAl ternate  ( 

T rack  theT rack  ) ; 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

function  result  The  track  identifier  of  the  next  track  in  the  group. 

Discussion 

This  function  returns  the  track  identifier  of  the  next  track  in  the  group.  Because  the 
alternate  group  list  is  circular,  you  must  specify  a  different  track  in  the  group  each 
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time  you  call  this  function.  You  have  retrieved  all  the  tracks  in  the  group  when  the 
function  returns  the  track  identifier  that  you  supplied  the  first  time  you  called 
GetTrackAlternate.  If  there  is  only  one  track  in  an  alternate  group,  or  if  the  track  you 
specify  does  not  belong  to  a  group,  this  function  returns  the  track  identifier  you 
supply. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Alternate  Tracks"  (V-2738) 

Related  Java  Methods 

qui cktime . std .movi es . T rack. getAl ternate( ) 


See  Also 

For  the  corresponding  set  function,  see  SetT rackAl  ternate  (III— 1656). 


GetTrackBoundsRgn 

Lets  the  media  limit  the  size  of  a  track  boundary  rectangle. 

RgnHandle  GetTrackBoundsRgn  ( 

Track  theTrack  ); 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

function  result  A  handle  to  the  region  limited  by  the  media. 

Discussion 

Because  the  media  limits  the  size  of  the  track  boundary  rectangle,  the  region 
returned  by  GetTrackBoundsRgn  may  not  be  rectangular  and  maybe  smaller  than  the 
track  boundary  region. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qui  cktime .  qd  .  Reg  i  on  .  f  romT  rackBoundsO, 
qui cktime . std .movi es .Track. get Bounds Rgn( ) 
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GetTrackClipRgn 


See  Also 

Movie  Toolbox  uses  the  Medi  aGetSrcRgn  (11-865)  function  to  determine  whether 
your  media  has  an  irregularly  shaped  display  area.  If  your  media  is  displayed  in  a 
nonrectangular  area,  or  if  your  media  uses  only  a  portion  of  the  track  rectangle,  you 
can  use  this  function  to  report  that  fact  to  the  toolbox. 


GetT  rackClipRgn 

Determines  the  clipping  region  of  a  track. 

RgnHandle  GetTrackClipRgn  ( 

T rack  theT rack  ) ; 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

function  result  A  handle  to  the  track's  clipping  region. 

Discussion 

This  function  allocates  the  region  and  returns  a  handle  to  the  region.  Your 
application  must  dispose  of  this  region  when  you  are  done  with  it.  If  the  function 
could  not  satisfy  your  request  or  if  there  is  no  clipping  region  defined  for  the  track, 
it  sets  the  returned  handle  to  NIL. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qui ckti me . qd . Regi on . f romT rackClipt),  quic kti me. std. mo vies. Track. getCl i pRgn ( ) 


See  Also 

For  the  corresponding  set  function,  see  SetT rackCl  i  pRgn  (III— 1656). 


GetT  rackCreationTime 


Returns  a  track's  creation  date  and  time. 

long  GetTrackCreati onTi me  ( 

T  rack  theT  rack  ) ; 
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theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

function  result  The  track's  creation  date  and  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Determining  Movie  Creation  and  Modification  Time" 
(V-2741) 

Related  Java  Methods 

qui ckti me . std .movi es . Track . getCreati onTime( ) 


GetT  rackDataSize 

Determines  the  size,  in  bytes,  of  the  sample  data  in  a  segment  of  a  track. 

long  GetTrackDataSize  ( 

Track  theTrack, 

TimeValue  startTime, 

TimeValue  duration  ); 

theT  rack 

The  track  for  this  operation.  You  obtain  this  track  identifier  from  such  functions 
as  NewMovi  eT  rack  (11-1092)  and  GetMovi  eT  rack  (1-497). 
startTime 

A  time  value  specifying  the  starting  point  of  the  segment, 
durati on 

A  time  value  that  specifies  the  duration  of  the  segment. 
function  result  The  size,  in  bytes,  of  the  sample  data  in  a  segment  of  a  track. 

Discussion 

This  function  counts  each  use  of  a  sample.  That  is,  if  a  track  uses  a  given  sample 
more  than  once,  the  size  of  that  sample  is  included  in  the  returned  size  value  one 
time  for  each  use.  Consequently,  the  returned  size  is  greater  than  or  equal  to  the 
actual  size  of  the  track's  sample  data. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Media  Samples"  (V-2742) 

Related  Java  Methods 

qui ckti me. std .movi es .Track. getDataSi ze( ) 

See  Also 

See  GetTrackDataSi ze64  (1-526). 

GetTrackDataSize64 

Provides  a  64-bit  version  of  GetT rackDataSi  ze  (1-525). 

OSErr  GetTrackDataSi ze64  ( 

Track  theTrack, 

TimeVal ue  startTi me , 

TimeValue  duration, 

wi de  *dataSi ze  ) ; 

theT  rack 

A  track  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

startTime 

A  time  value  specifying  the  starting  point  of  the  segment, 
durati on 

A  time  value  that  specifies  the  duration  of  the  segment. 
dataSi ze 

The  size,  in  bytes,  of  the  sample  data  in  a  segment  of  a  track.  This  function 
counts  each  use  of  a  sample.  That  is,  if  a  track  uses  a  given  sample  more  than 
once,  the  size  of  that  sample  is  included  in  the  returned  size  value  one  time  for 
each  use.  Consequently,  the  returned  size  is  greater  than  or  equal  to  the  actual 
size  of  the  track's  sample  data. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

The  only  difference  between  this  function  and  GetT  rackDataSi  ze  (1-525)  is  that  size 
of  the  sample  data  is  returned  as  a  64-bit  integer  in  the  dataSi  ze  parameter  instead 
of  as  a  32-bit  integer  returned  by  the  function. 
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Special  Considerations 

New  applications  should  use  this  function  instead  of  the  32-bit  version. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


See  Also 

See  GetTrackDataSi  ze  (1-525). 


GetT  rackDimensions 


Determines  a  track's  source  rectangle. 

void  GetTrackDimensions  ( 

Track  theTrack, 

Fixed  *width. 

Fixed  *height  ); 


theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovieTrack  and  GetMovi  eTrack  (1-497). 

wi  dth 

A  pointer  to  a  fixed-point  number.  The  Movie  Toolbox  returns  the  width,  in 
pixels,  of  the  track's  rectangle.  This  value  corresponds  to  the  x  coordinate  of  the 
lower-right  corner  of  the  track's  rectangle. 

hei ght 

A  pointer  to  a  fixed-point  number.  The  Movie  Toolbox  returns  the  height,  in 
pixels,  of  the  track's  rectangle.  This  value  corresponds  to  the  y  coordinate  of  the 
lower-right  corner  of  the  track's  rectangle. 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qui ckti me . std .movi es . Track. get Di men si ons( ) 
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GetTrackDisplayBoundsRgn 


See  Also 

For  the  corresponding  set  function,  see  SetT rackDi mensi  ons  (III— 1657). 


GetTrackDisplayBoundsRgn 


Determines  the  region  a  track  occupies  in  a  movie's  graphics  world. 

RgnHandle  GetTrackDisplayBoundsRgn  ( 

T rack  theT rack  ) ; 


theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 


Discussion 


function  result  A  handle  to  the  region  the  specified  track  occupies  in  a  movie's 
graphics  world. 

This  function  allocates  the  region  and  returns  a  handle  to  the  region.  If  the  track 
does  not  have  a  spatial  representation  at  the  current  movie  time,  the  function 
returns  an  empty  region.  If  the  function  could  not  satisfy  your  request,  it  sets  the 
returned  handle  to  NIL. 


Special  Considerations 

Your  application  must  dispose  of  the  returned  region  when  you  are  done  with  it. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

quicktime.qd.Region.fromTrackDisplayC ) , 

qu ickti me. std. mo vies. Track. getDi splay Bounds Rgn() 


GetTrackDisplayMatrix 

Returns  a  matrix  that  is  the  concatenation  of  all  matrices  currently  affecting  the 
track's  location,  scaling,  and  so  on,  including  the  movie's  matrix,  the  track's  matrix, 
and  the  modifier  matrix. 

OSErr  GetTrackDisplayMatrix  ( 
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Track  theTrack, 

MatrlxRecord  *matrix  ); 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 
matri x 

A  pointer  to  a  matrix  structure. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

Since  modifier  information  is  passed  between  tracks  atMoviesTask  (11-973)  time,  the 
information  returned  by  this  call  represents  the  matrix  in  effect  at  the  last 
Movi esTask  call. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Enhancing  Movie  Playback  Performance"  (V-2722) 

Related  Java  Methods 

qui ckti me . std .movi es . Track. getDi s pi ayMatrix( ) 


See  Also 

To  determine  the  entire  clip  of  a  track  at  the  current  time,  use 

GetTrackDi  spl  ayBoundsRgn  (1-528).  The  results  of  GetTrackDi  spl  ayBoundsRgn  take 

into  account  any  clip  regions  provided  by  modifier  tracks. 


GetT  rackDuration 

Returns  the  duration  of  a  track. 

TimeVaiue  GetTrackDuration  ( 

Track  theTrack  ); 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT  rack  (11-1092)  and  GetMovi  eT  rack  (1-497). 

function  result  The  duration  of  the  specified  track,  expressed  in  the  time  scale  of  the 
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GetTrackEditRate 


Discussion 


movie  that  contains  the  track. 

The  duration  corresponds  to  the  ending  time  of  the  track  in  the  movie's  time 
coordinate  system  (remember  that  all  tracks  start  at  movie  time  0). 


Version  Notes 


Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Track  Time"  (V-2733) 

Related  Java  Methods 

qu ickti me. std. mo vies. Track. getDuratlont) 


GetT  rackEditRate 


Returns  the  rate  of  the  track  edit  of  a  specified  track  at  an  indicated  time. 

Fixed  GetTrackEditRate  ( 

Track  theTrack, 

T i meVal ue  atT i me  ) ; 

theT  rack 

The  track  identifier  for  which  the  rate  of  a  track  edit  (at  the  time  given  in  the 
atT i me  parameter)  is  to  be  determined. 

atTime 

Indicates  a  time  value  at  which  the  rate  of  a  track  edit  (of  a  track  identified  in 
the  parameter  theT  rack)  is  to  be  determined. 

function  result  The  rate  of  the  track  edit  of  the  specified  track  at  the  specified  time. 

Discussion 

This  function  is  useful  if  you  are  stepping  through  track  edits  directly  in  your 
application  or  if  you  are  a  client  of  QuickTime's  base  media  handler. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Editing  Tracks"  (V-2750) 

Related  Java  Methods 

qu ickti me. std. mo vies. Track. getEditRatet) 


1-530 


Inside  QuickTime:  Functions  A-H 


GetTrackEnabled 


GetT  rackEnabled 


Determines  whether  a  track  is  currently  enabled. 

Boolean  GetTrackEnabled  ( 

Track  theTrack  ); 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovieTrack  and  GetMovi  eTrack  (1-497). 

function  result  TRUE  if  the  specified  track  is  currently  enabled,  FALSE  otherwise. 

Discussion 

The  Movie  Toolbox  services  only  enabled  tracks. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Disabling  Movies  and  Tracks"  (V-2724) 

Related  Java  Methods 

qui ckti me . std .movi es .Track. get Enabl ed( ) 


See  Also 

For  the  corresponding  set  function,  see  SetT rackEnabl  ed  (III— 1658). 


GetTrackID 

Determines  a  track's  unique  track  ID  value. 

long  GetTrackID  ( 

Track  theTrack  ); 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

function  result  The  specified  track's  unique  track  ID  value. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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GetTrackLayer 


Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Locating  a  Movie's  Tracks  and  Media  Structures" 
(V-2736) 

Related  Java  Methods 

qu ickti me. std. mo vies. Track. getIDO 


GetTrackLayer 

Retrieves  a  track's  layer. 

short  GetTrackLayer  ( 

T rack  theT rack  ) ; 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

function  result  The  specified  track's  layer  number. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qu ickti me. std. mo vies. Track. getLayert) 

See  Also 

For  the  corresponding  set  function,  see  SetTrackLayer  (III— 1660). 


GetT  rackLoadSettings 

Retrieves  a  track's  preload  information. 

void  GetTrackLoadSetti ngs  ( 

Track  theTrack, 

TimeValue  *prel oadTime , 

TimeValue  *prel oadDurati on , 

long  *prel oadFl ags , 

1 ong  *defaul tHi nts  ) ; 
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theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 
prel oadT i me 

Specifies  a  field  to  receive  the  starting  point  of  the  portion  of  the  track  to  be 
preloaded.  The  toolbox  returns  a  value  of  -1  if  the  entire  track  is  to  be 
preloaded. 

prel oadDurati on 

Specifies  a  field  to  receive  the  amount  of  the  track  to  be  preloaded,  starting  from 
the  time  specified  in  the  preloadTime  parameter.  If  the  entire  track  is  to  be 
preloaded,  this  value  is  ignored, 
prel  oadFl  ags 

Specifies  a  field  to  receive  the  flags  (see  below)  that  control  when  the  toolbox 
preloads  the  track, 
def aul t H 1 nts 

Specifies  a  field  to  receive  the  playback  hints  for  the  track. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

preloadFlags  Constants 

prel oadAl ways 

Specifies  that  the  toolbox  always  preloads  this  track. 
preloadOnlylfEnabled 

Specifies  that  the  toolbox  preloads  this  track  only  when  the  track  is  enabled. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Enhancing  Movie  Playback  Performance"  (V-2722) 

Related  Java  Methods 

qui ckti me . std .movi  es .Track, get  Load Sett i ngs ( ) 


See  Also 

For  the  corresponding  set  function,  see  SetT rackLoadSetti  ngs  (III— 1661). 


GetT  rackMatrix 


Retrieves  a  track's  transformation  matrix. 
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GetTrackMatte 


void  GetTrackMatrix  ( 

Track  theTrack, 

MatrixRecord  *matrix  ); 


theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  and  GetMovi  eT rack  (1-497). 
matri x 

A  pointer  to  a  MatrixRecord  (IV-2304)  structure.  The  GetTrackMatrix  function 
returns  the  track's  matrix  into  the  structure  referred  to  by  this  parameter. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94). 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qu ickti me. std. mo vies. Track. get MatrixO 


See  Also 

For  the  corresponding  set  function,  see  SetT rackMatri  x  (III— 1662).  The  Movie 
Toolbox  provides  a  number  of  functions  that  allow  you  to  manipulate  track 
matrices.  See  Setldenti  tyMatri  x  (III— 1593)  for  information  about  these  functions. 


GetTrackMatte 


Retrieves  a  copy  of  a  track's  matte. 

PixMapHandle  GetTrackMatte  ( 

T  rack  theT  rack  ) ; 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT  rack  (11-1092)  and  GetMovi  eT  rack  (I — 497). 

function  result  A  handle  to  a  PixMap  (IV-2332)  structure  that  represents  the  specified 
track's  matte.  If  the  function  could  not  satisfy  your  request,  it  sets  the 
returned  handle  to  NIL. 
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Discussion 

The  matte  defines  which  of  the  track's  pixels  are  displayed  in  a  movie,  and  it  is  valid 
for  the  entire  duration  of  the  movie. 

Special  Considerations 

You  should  use  DisposeMatte  (1-267)  to  dispose  of  the  matte  when  you  are  finished 
with  it. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

See  Also 

For  the  corresponding  set  function,  see  SetT rackMatte  (III— 1663). 


GetT  rackMedia 


Determines  the  media  that  contains  a  track's  sample  data. 

Media  GetTrackMedia  ( 

Track  theTrack  ); 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

function  result  The  media  identifier  for  the  media  that  contains  the  track's  sample 
data.  If  the  function  could  not  locate  the  media,  it  sets  this  returned 
value  to  NIL. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Locating  a  Movie's  Tracks  and  Media  Structures" 
(Y-2736) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Medi a . f romT  rack( ) , 
qui cktime . std .movi es .medi a . Medi a . getT  rackMedi a( ) 
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GetTrackModificationTime 


GetT  rackModif  icationT  ime 


Returns  a  track's  modification  date  and  time. 

long  GetTrackModificationTime  ( 

T rack  theT rack  ) ; 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

function  result  The  specified  track's  modification  date  and  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Determining  Movie  Creation  and  Modification  Time" 
(V-2741) 

Related  Java  Methods 

qui ckti me. std. movies. Track. getModi f i cati onTi me ( ) 


GetT  rackMovie 


Determines  the  movie  that  contains  a  specified  track. 

Movie  GetTrackMovi e  ( 

T  rack  theT  rack  ) ; 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT  rack  and  GetMovi  eT  rack  (1-497). 

function  result  The  identifier  of  the  movie  that  contains  the  track. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Locating  a  Movie's  Tracks  and  Media  Structures" 
(V-2736) 
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Related  Java  Methods 

qui cktime . std .movi es . T rack. getMovi e( ) 


GetT  rackMo  vieBoundsRgn 

Determines  the  region  the  track  occupies  in  a  movie's  boundary  region. 

RgnHandle  GetTrackMovieBoundsRgn  ( 

Track  theTrack  ); 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

function  result  A  handle  to  the  region  the  specified  track  occupies  in  its  movie's 

boundary  region.  If  the  track  does  not  have  a  spatial  representation 
at  the  current  movie  time,  the  function  returns  an  empty  region.  If 
the  function  could  not  satisfy  your  request,  it  sets  the  returned 
handle  to  NIL. 

Discussion 

This  function  determines  the  region  by  applying  the  track's  clipping  region  and 
matrix.  This  region  is  valid  only  for  the  current  movie  time.  The  function  allocates 
the  region  and  returns  a  handle  to  it. 

Special  Considerations 

Your  application  must  dispose  of  the  returned  region  when  you  are  done  with  it. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qui  cktime .  qd  .  Reg  i  on  .  f  romT  rackMovieBoundsO, 
qui  cktime .  std  .movi  es  .Track.  getMovi  eBoundsRgnO 


GetTrackNextlnterestingTime 

Searches  for  times  of  interest  in  a  track, 
void  GetTrackNextlnterestingTime  ( 
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GetTrackNextlnterestingTime 


T  rack 
short 
T i meVal ue 
Fi  xed 
T i meVal ue 
T i meVal ue 


theT  rack , 

i nteresti ngTi me  FI ags , 
time , 
rate , 

*interestingTime, 

*i nteresti ngDurati on  ); 


theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 
i nteresti ngTi me  FI ags 

Contains  flags  (see  below)  that  determine  the  search  criteria.  Note  that  you  may 
set  only  one  of  the  nextT  i  meMedi  a  Samp  1  e,  nextTimeMedi  a  Ed  i  t,  nextT  i  meT  rackEdi  t 
and  nextT i meSyncSampl  e  flags  to  1.  Set  unused  flags  to  0. 

time 

Specifies  a  time  value  that  establishes  the  starting  point  for  the  search.  This  time 
value  must  be  expressed  in  the  movie's  time  scale. 

rate 

The  search  direction.  Negative  values  cause  the  Movie  Toolbox  to  search 
backward  from  the  starting  point  specified  in  the  time  parameter.  Other  values 
cause  a  forward  search, 
i nteresti ngT i me 

A  pointer  to  a  time  value.  The  Movie  Toolbox  returns  the  first  time  value  it  finds 
that  meets  the  search  criteria  specified  in  the  flags  parameter.  This  time  value 
is  in  the  movie's  time  scale.  If  there  are  no  times  that  meet  the  search  criteria  you 
specify,  the  Movie  Toolbox  sets  this  value  to  -1.  Set  this  parameter  to  N I L  if  you 
are  not  interested  in  this  information. 

i nteresti ngDurati on 

A  pointer  to  a  time  value.  The  Movie  Toolbox  returns  the  duration  of  the 
interesting  time.  This  time  value  is  in  the  movie's  time  coordinate  system.  Set 
this  parameter  to  N I L  if  you  don't  want  this  information;  in  this  case,  the 
function  works  more  quickly. 

interestingTimeFlags  Constants 

nextT i meMedi a Samp 1 e 

Searches  for  the  next  sample  in  the  track's  media.  Set  this  flag  to  1  to  search  for 
the  next  sample. 

nextT i meMedi a  Ed i t 

Searches  for  the  next  group  of  samples  in  the  track's  media.  Set  this  flag  to  1  to 
search  for  the  next  group  of  samples. 
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nextTi meT  rackEdi t 

Searches  for  the  media  sample  that  corresponds  to  the  next  entry  in  a  track's 
media  edit  list.  The  end  of  the  track  is  considered  an  empty  edit.  Set  this  flag  to 
1  to  search  for  the  next  track  edit. 
nextTi meSyncSampi e 

Searches  for  the  next  sync  sample  in  the  track's  media.  Set  this  flag  to  1  to 
search  for  the  next  sync  sample. 

nextTimeEdgeOK 

Instructs  the  Movie  Toolbox  that  you  are  willing  to  receive  information  about 
elements  that  begin  or  end  at  the  time  specified  by  the  time  parameter.  Set  this 
flag  to  1  to  accept  this  information.  When  this  flag  is  set,  the  function  returns 
valid  information  about  the  beginning  and  end  of  the  track. 
nextTi melgnoreActi veSegment 

Instructs  the  Movie  Toolbox  to  look  outside  of  the  active  segment  for  samples 
that  meet  the  search  criteria.  Set  this  flag  to  1  to  search  outside  of  the  active 
segment. 

Discussion 

Some  compression  algorithms  conserve  space  by  eliminating  duplication  between 
consecutive  frames  in  a  sample.  In  this  case,  sync  samples  don't  rely  on  preceding 
frames  for  content.  You  can  access  error  returns  from  this  function  through 
GetMovi esError  (1-492)  and  GetMovi esSti  ckyError  (1-494).  See  "Error  Codes" 
(IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Finding  Interesting  Times"  (V-2735) 

Related  Java  Methods 

qui ckti me . std .movi  es . Track . get Next  In teres ti ngTime( ) 


GetTrackOffset 


Determines  the  time  difference  between  the  start  of  a  track  and  the  start  of  the  movie 
that  contains  the  track. 

TimeVaiue  GetTrackOffset  ( 

Track  theTrack  ); 
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GetTrackPict 


theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 


function  result  The  time  difference  between  the  start  of  the  specified  track  and  the 
start  of  the  movie  that  contains  the  track. 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Track  Time"  (V-2733) 

Related  Java  Methods 

qui ckti me . std .movi es .T  rack. get Of f set ( ) 


See  Also 

For  the  corresponding  set  function,  see  SetTrackOffset  (III— 1664). 


GetTrackPict 


Creates  a  QuickDraw  picture  from  a  specified  track  at  a  specified  time. 

PicHandle  GetTrackPict  ( 

Track  theTrack, 

T i meVal ue  time  ) ; 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT  rack  (11-1092)  and  GetMovi  eT  rack  (1-497). 

time 

The  time  at  which  the  image  is  taken. 

function  result  A  handle  to  the  specified  picture.  If  the  function  could  not  create  the 
picture,  the  returned  handle  is  set  to  NIL. 

Special  Considerations 

Your  application  must  dispose  of  the  returned  picture  handle. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Generating  Pictures  From  Movies"  (V-2725) 
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Related  Java  Methods 

qui cktime . qd . PI ct . f romT rack( ) ,  qui cktime . std .movi es .Track. get Pi ct( ) 

See  Also 

GetT rackPi  ct  is  similar  to  GetMovi  ePi  ct  (1-483),  except  that  GetT rackPi  ct  uses  only 
the  specified  track  to  create  the  picture. 

GetT  rackRef  erence 

Retrieves  the  track  identifier  contained  in  an  existing  track  reference. 

Track  GetTrackReference  ( 

Track  theTrack, 

OSType  refType, 

long  index  ); 

theT  rack 

Identifies  the  track  for  this  operation.  Your  application  obtains  this  track 
identifier  from  such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack 
(1-497). 

refType 

The  type  of  reference;  see  "Data  References"  (IV-2661). 
i  ndex 

The  index  value  of  the  reference  found.  You  obtain  this  index  value  when  you 
create  the  track  reference. 

function  result  The  track  identifier  for  the  specified  track.  If  the  toolbox  cannot 
locate  the  track  reference  corresponding  to  your  specifications,  it 
returns  a  value  of  N I L. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Track  References"  (V-2737) 

Related  Java  Methods 

qui cktime . std .movi es .Track. get Ref erence ( ) 

See  Also 

For  the  corresponding  set  function,  see  SetT rackReference  (III— 1665). 
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GetT  rackRef  erenceCount 


Determines  how  many  track  references  of  a  given  type  exist  for  a  track. 

long  GetTrackReferenceCount  ( 

Track  theTrack, 

OSType  refType  ) ; 

theT  rack 

Identifies  the  track  for  this  operation.  Your  application  obtains  this  track 
identifier  from  such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack 
(1-497). 

refType 

The  type  of  reference;  see  "Data  References"  (IV-2661).  The  toolbox  determines 
the  number  of  track  references  of  this  type. 

function  result  A  long  integer  that  specifies  the  number  of  track  references  of  the 
specified  type  in  the  track.  If  there  are  no  references  of  the  type  you 
have  specified,  the  function  returns  a  value  of  0. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Track  References"  (V-2737) 

Related  Java  Methods 

quickti  me.  std.  mo  vies.  Track,  get  ReferenceCountO 


GetT  rackSegmentDisplayBoundsRgn 


Determines  the  region  a  track  occupies  in  a  movie's  graphics  world  during  a 
specified  segment. 

RgnHandle  GetTrackSegmentDi spl ayBoundsRgn  ( 

Track  theTrack, 

T imeVal ue  time  , 

TimeValue  duration  ); 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT  rack  (11-1092)  and  GetMovi  eT  rack  (1-497). 
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ti  me 

The  starting  time  of  the  track  segment  to  consider.  This  time  value  must  be 
expressed  in  the  movie's  time  coordinate  system.  The  duration  parameter 
specifies  the  length  of  the  segment, 
duratl on 

The  length  of  the  segment  to  consider.  Set  this  parameter  to  0  to  consider  an 
instant  in  time. 

function  result  A  handle  to  the  region  the  specified  track  occupies  in  its  movie's 

graphics  world  during  a  specified  segment.  If  the  track  does  not  have 
a  spatial  representation  during  the  specified  segment,  the  function 
returns  an  empty  region.  If  the  function  could  not  satisfy  your 
request,  it  sets  the  returned  handle  to  NIL. 

Discussion 

This  function  allocates  the  region  and  returns  a  handle  to  it.  This  region  is  valid  for 
the  specified  segment. 

Special  Considerations 

Your  application  must  dispose  of  the  returned  region  when  you  are  done  with  it. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qui cktime . qd . Regi on . f romT rackSegmentl ) , 

qui ckti me . std .movi es .Track . getSegmentDi spl ay Bounds Rgn() 


GetTrackSoundLocalizationSettings 


Returns  a  handle  to  a  copy  of  the  current  3D  sound  settings  for  a  specified  track. 

OSErr  GetTrackSoundLocal i zati onSetti ngs  ( 

Track  theTrack, 

Handle  *settings  ); 

theT  rack 

Identifies  the  track  for  this  operation.  Your  application  obtains  this  track 
identifier  from  such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack 
(1-497). 
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GetTrackStatus 


setti ngs 

A  handle  to  a  copy  of  the  current  3D  sound  settings  for  a  specified  track,  in  the 
format  of  an  SSpLocal  i  zati  onData  (IV-2460)  record.  If  there  are  no  3D  sound 
settings,  the  returned  handle  is  set  to  NIL. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Special  Considerations 

The  caller  of  this  function  is  responsible  for  disposing  of  the  returned  handle. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Track  Sound"  (V-2740) 

Related  Java  Methods 

quickti me. std. mo vies. Track. getSound Local izationSettingst), 
qui ckti me . uti 1 . QTHandl e . f romT rack! ) 


See  Also 

For  the  corresponding  set  function,  see  SetT rackSoundLocal  i  zati  onSetti  ngs 
(III— 1666). 


GetTrackStatus 


Returns  the  value  of  the  last  error  the  media  encountered  while  playing  a  specified 
track. 

ComponentResul t  GetTrackStatus  ( 

T rack  theT rack  ) ; 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
GetMovi eStatus  (1-494). 

function  result  GetT rackStatus  returns  the  last  error  encountered  for  the  specified 
track;  see  "Error  Codes"  (IV-2663).  If  the  component  does  not  find 
any  errors,  the  result  is  set  to  no  Err. 
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GetTrackUsage 


Discussion 

This  function  returns  information  about  errors  that  are  encountered  during  the 
processing  associated  with  MoviesTask  (11-973).  These  errors  typically  reflect 
playback  problems,  such  as  low-memory  conditions.  This  function  returns  the  last 
error  encountered  for  the  specified  track.  The  media  clears  this  error  code  when  it 
detects  that  the  error  has  been  corrected. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Movies  and  Your  Event  Loop"  (V-2720) 

Related  Java  Methods 

qui ckti me . std .movi es . Track. get St at us ( ) 


See  Also 

See  Movi esTask  (11-973). 


GetTrackUsage 


Determines  whether  a  track  is  used  in  a  movie,  its  preview,  its  poster,  or  a 
combination  of  these. 

long  GetTrackUsage  ( 

Track  theTrack  ); 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

function  result  Track  usage  flags  (see  below).  These  flags  may  be  combined. 

Function  Result  Constants 

trackUsagelnMovi e 

If  this  flag  is  set  to  1,  the  track  is  used  in  its  movie. 
trackUs age  In  Preview 

If  this  flag  is  set  to  1,  the  track  is  used  in  the  preview. 
trackUsagelnPoster 

If  this  flag  is  set  to  1,  the  track  is  used  in  the  poster. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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GetTrackUserData 


Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Movie  Posters  and  Movie  Previews"  (V-2718) 

Related  Java  Methods 

quickti me. std. mo vies. Track. getUsageO 


See  Also 

Your  application  can  specify  how  a  track  is  used  by  calling  SetT rackUsage  (III— 1668). 


GetTrackUserData 


Obtains  access  to  a  track's  user  data  list. 

UserData  GetTrackUserData  ( 

T rack  theT rack  ) ; 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

function  result  A  reference  to  the  specified  track's  user  data.  If  the  function  could 
not  locate  the  track's  user  data,  it  sets  this  returned  value  to  NIL. 

Discussion 

This  function  returns  a  reference  to  the  track's  user  data  list,  which  is  valid  until  you 
dispose  of  the  track.  When  you  save  the  track,  the  Movie  Toolbox  saves  the  user 
data  as  well. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  User  Data"  (V-2743) 

Related  Java  Methods 

quickti me. std. mo vies. media. User Data . f romT  rack! ) , 
quickti me. std. mo vies. Track. getUser Da ta() 


See  Also 

You  can  use  GetUserData  (1-547),  AddUserData  (1—44),  and  RemoveUserData  (III— 1459) 
to  manipulate  the  contents  of  the  user  data  list.  If  the  data  list  contains  text  data,  you 
can  use  GetUserDataText  (1-549),  AddUserDataText  (1-45),  and  RemoveUserDataText 
(III— 1460)  to  work  with  its  contents. 


1-546 


Inside  QuickTime:  Functions  A-H 
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GetT  rackV  olume 


Returns  a  track's  current  volume  setting. 

short  GetTrackVol ume  ( 

Track  theTrack  ); 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

function  result  The  specified  track's  current  volume  setting.  The  values  returned  in 
the  high  and  low  words  range  from  0x0000  (silence)  to  0x0100  (full 
volume).  You  can  use  constants  (see  below)  to  test  for  full  volume 
and  no  volume. 

Function  Result  Constants 

k  Fu 1 1 Vol ume 

Full  volume  (constant  value  is  1.0). 
kNoVol ume 

No  volume  (constant  value  is  0.0). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Sound  Volume"  (V-2732) 

Related  Java  Methods 

qui ckti me . std .movi es .Track . get Vol ume( ) 


See  Also 

For  the  corresponding  set  function,  see  SetT rackVol  ume  (III— 1669). 


GetUserData 


Returns  a  specified  user  data  item. 


OSErr  GetUserData  ( 

UserData  theUserData, 

Handle  data, 

OSType  udType, 

long  index  ); 
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GetUserDataltem 


theUserData 

The  user  data  list  for  this  operation.  You  obtain  this  list  reference  by  calling  the 
GetMovi  ellserData  (1-499),  GetTrackUserData  (1-546),  or  GetMedi  aUserData 
(1-456)  function. 

data 

A  handle  that  is  to  receive  the  data  from  the  specified  item.  GetUserData  resizes 
this  handle  as  appropriate  to  accommodate  the  item.  Your  application  is 
responsible  for  releasing  this  handle  when  you  are  done  with  it.  Set  this 
parameter  to  N I L  if  you  don't  want  to  retrieve  the  user  data  item.  This  can  be 
useful  if  you  want  to  verify  that  a  user  data  item  exists,  but  you  don't  need  to 
work  with  the  item's  contents. 

udType 

The  item's  type  value;  see  "User  Data  Identifiers"  (IV-2696). 
i  ndex 

The  item's  index  value.  This  parameter  must  specify  an  item  in  the  user  data 
list  identified  by  the  parameter  theUserData. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  User  Data"  (V-2743) 

Related  Java  Methods 

qu i c kti me. std. mo vies. media. User Data. get Da tat) 


GetUserDataltem 


Returns  a  specified  user  data  item. 


OSErr  GetUserDataltem  ( 


UserData 
voi  d 
1  ong 
OSType 
1  ong 


theUserData , 
*data , 
size, 
udType , 
i ndex  ) ; 
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theUserData 

The  user  data  list  for  this  operation.  You  obtain  this  list  reference  by  calling  the 
GetMovi  ellserData  (1-499),  GetTrackUserData  (1-546),  or  GetMedi  aUserData 
(1-456). 

data 

A  pointer  that  is  to  receive  the  data  from  the  specified  item. 

si  ze 

The  size  of  the  item. 
udType 

The  item's  type  value;  see  "User  Data  Identifiers"  (IV-2696). 
i  ndex 

The  item's  index  value.  This  parameter  must  specify  an  item  in  the  user  data 
list  identified  by  the  parameter  theUserData. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  User  Data"  (V-2743) 

Related  Java  Methods 

qui cktime . std .movi es .medi a.UserData. get Data Item( ) 


See  Also 

For  the  corresponding  set  function,  see  SetUserData Item  (III— 1673). 


GetUserDataText 


Retrieves  language-tagged  text  from  an  item  in  a  user  data  list. 


OSErr  GetUserDataText  ( 


UserData 
Handl e 
OSType 
1  ong 
short 


theUserData , 
data , 
udType , 
i ndex, 

itlRegionTag  ); 
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GoToBeginningOfMovie 


theUserData 

The  user  data  list  for  this  operation.  You  obtain  this  list  reference  by  calling  the 
GetMovi  ellserData  (1-499),  GetTrackUserData  (1-546),  or  GetMedi  aUserData 
(1-456)  function. 

data 

A  handle  that  is  to  receive  the  data.  The  GetUserDataText  function  resizes  this 
handle  as  appropriate.  Your  application  must  dispose  of  the  handle  when  you 
are  done  with  it. 

udType 

The  item's  type  value;  see  "User  Data  Identifiers"  (IV-2696). 
i  ndex 

The  item's  index  value.  This  parameter  must  specify  an  item  in  the  user  data 
list  identified  by  the  parameter  theUserData. 
i tl Regi onTag 

The  language  code  of  the  text  to  be  retrieved.  See  "Localization  Codes" 
(IV-2673). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

You  specify  the  user  data  list  and  item,  and  the  item's  type  value  and  language 
code.  The  Movie  Toolbox  retrieves  the  specified  text  from  the  user  data  item. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  User  Data"  (V-2743) 

Related  Java  Methods 

qu i c kti me. std. mo vies. media. User Data. getText ( ) 


GoT  oBeginningOf  Movie 


Repositions  a  movie  to  play  from  its  start. 

void  GoToBeginningOfMovie  ( 

Movi e  theMovi e  ) ; 
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G  oToEndOf  Movie 


theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi eFromHandl e  (11-1084). 

Discussion 

If  the  movie  is  in  preview  mode,  the  function  goes  to  the  start  of  the  preview 
segment  of  the  movie.  In  all  other  cases,  this  function  goes  to  the  start  of  the  movie, 
where  the  movie  time  value  is  0.  You  can  access  error  returns  from  this  function 
through  GetMovi esError  (I — 492)  and  GetMovi esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Controlling  Movie  Playback"  (V-2717) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . goToBegi nni ng( ) 


GoT  oEndOf  Mo  vie 


Repositions  a  movie  to  play  from  its  end. 

void  GoToEndOfMovie  ( 

Movie  theMovi e  ); 


theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Controlling  Movie  Playback"  (V-2717) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . goToEndi ) 
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GraphicsExportCanTranscode 


GraphicsExportCanT  ranscode 


Asks  whether  the  current  graphics  export  operation  should  be  performed  by 
transcoding. 

ComponentResul t  GraphicsExportCanTranscode  ( 

Graphi csExportComponent  cl, 

Boolean  *canTranscode  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

canT  ranscode 

Points  toaBooleanto  receive  the  answer.  TRUE  means  that  the  current  export 
operation  should  be  performed  by  transcoding,  FALSE  that  it  should  not. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Graphics  exporters  maybe  able  to  transcode  from  some  inputs  and  not  from  others. 
For  instance,  the  JPEG  graphics  exporter  is  able  to  transcode  compressed  JPEG 
streams,  but  not  other  kinds  of  compressed  data.  The  base  graphics  exporter  makes 
this  call  to  the  format-specific  graphics  exporter  to  ask  whether  the  current  export 
operation  should  be  done  by  transcoding.  If  the  format-specific  exporter  replies  that 
it  should,  the  base  exporter  calls  Graphi  csExportDoT ranscode  (1-555)  to  do  so.  If  the 
answer  is  no,  then  the  format-specific  exporter  will  not  be  able  to  transcode. 

Special  Considerations 

This  function  is  used  for  internal  communication  between  the  base  and 
format-specific  graphics  exporter.  Applications  will  not  usually  need  to  call  it. 
Format-specific  exporters  may  delegate  this  call,  in  which  case  the  base  graphics 
exporter's  implementation  gives  a  reply  of  FALSE. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Internal  Graphics  Export  Routines"  (V-2883) 

See  Also 

Format-specific  exporters  implementing  GraphicsExportCanTranscode  should  call 
Graphi  cs  Expo  rtMay  Exporter  Read  Input  Data  (1-585). 
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GraphicsExportCanUseCompressor 


Asks  whether  to  use  a  compressor  in  a  graphics  export  operation. 

ComponentResul t  GraphicsExportCanUseCompressor  ( 

Graphi csExportComponent  ci  , 

Boolean  *canUseCompressor , 

void  *codecSetti ngsAtomContai nerPtr  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 
canUseCompressor 

A  Bool  ean  variable  to  receive  the  answer. 
codecSetti ngsAtomContai  nerPtr 

A  pointer  to  a  QTAtomContai  ner  variable.  If  the  canUseCompressor  parameter 
returns  T  RU  E,  the  format-specific  exporter  should  create  a  new  QuickTime  atom 
container  with  information  about  the  compression  operation  and  return  it  here. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  base  graphics  exporter  makes  this  call  of  the  format-specific  graphics  exporter 
to  ask  whether  the  current  export  operation  should  be  done  by  using  an  image 
compressor.  If  the  answer  is  TRUE,  the  format-specific  exporter  must  also  create  and 
return  an  atom  container.  This  atom  container  must  contain  a  big-endian  'vide' 
(IV-2610)  atom  with  at  least  a  child  atom  of  type  '  sptl  '  (IV-2586)  containing  a 
SCSpati  al  Setti  ngs  (IV-2423)  record  specifying  which  compressor  to  use,  the  depth, 
and  the  spatial  quality. 

Special  Considerations 

This  function  is  used  for  internal  communication  between  the  base  and 
format-specific  graphics  exporter.  Applications  will  not  usually  need  to  call  it. 
Format-specific  exporters  may  delegate  this  call,  in  which  case  the  base  graphics 
exporter's  implementation  gives  a  reply  of  FALSE. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Internal  Graphics  Export  Routines"  (V-2883) 
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GraphicsExportDoExport 


GraphicsExportDoExport 


Performs  a  graphics  export  operation. 

ComponentResul t  GraphicsExportDoExport  ( 

Graphi csExportComponent  ci  , 

unsigned  long  *actual Si zeWri tten  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

actual  Si zeWri tten 

Points  to  a  variable  to  receive  the  number  of  bytes  written.  If  you  are  not 
interested  in  this  information,  pass  N I L. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Before  calling  this  function ,  you  must  specify  an  input  image,  using  one  of  the 
Graphi  csExportSetlnput...  functions,  and  a  destination  for  the  output  image  file, 
using  one  of  the  Graphi  csExportSetOutput...  functions. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Setting  the  Input  and  Output  of  a  Graphics  Exporter 
Instance"  (V-2883) 


GraphicsExportDoStandaloneExport 

Performs  a  standalone  graphics  export  operation. 

ComponentResul t  Graphi csExportDoStandal oneExport  ( 
Graphi csExportComponent  ci  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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GraphicsExportDoTranscode 


Discussion 

If  both  Graph i  csExportCanT ranscode  (1-552)  and  Gr apin'  csExportCanllseCompressor 
(1-553)  reply  FALSE,  the  base  graphics  exporter  makes  this  call  of  the  format-specific 
exporter  to  perform  the  export. 

Special  Considerations 

This  function  is  used  for  internal  communication  between  the  base  and 
format-specific  graphics  exporter.  Applications  will  not  usually  need  to  call  it. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Internal  Graphics  Export  Routines"  (V-2883) 

See  Also 

The  format-specific  exporter  may  call  Graphi  csExportGetlnputlmageDescri pti on 
(1-570),  Graphi  csExportGetlnputlmageDimensi  ons  (1-571),  and 
Graphi  csExportGetlnputlmageDepth  (1-569)  to  find  out  about  the  input  image.  It 
should  allocate  a  PixMap  (IV-2332)  structure  and  call  Graphi  cs  Export  Dr  aw  In  put  Image 
(1-557)  to  draw  portions  of  the  input  image  into  it.  The  format-specific  exporter 
should  call  Graphi  csExportWri  teOutputData  (1-611)  to  write  the  image  data. 


GraphicsExportDoT  ranscode 

Performs  a  graphics  export  operation  by  transcoding. 

ComponentResul t  GraphicsExportDoTranscode  ( 

Graphi csExportComponent  ci  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  base  graphics  exporter  makes  this  call  of  the  format-specific  graphics  exporter 
to  perform  a  transcoding  export.  This  function  should  call 

Graphi  csExportGet  Input  Data  Si  ze  (1-564)  and  Graphi  cs  Export  Read  In  put  Data  (1-586) 
to  measure  and  read  the  input  image  data,  and  Graphi  csExportWri  teOutputData 
(1-611)  to  write  the  output  image  file. 
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Special  Considerations 

This  function  is  used  for  internal  communication  between  the  base  and 
format-specific  graphics  exporter.  Applications  will  not  usually  need  to  call  it. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Internal  Graphics  Export  Routines"  (V-2883) 


GraphicsExportDoUseCompressor 


Performs  a  graphics  export  operation  with  compression. 

ComponentResul t  GraphicsExportDoUseCompressor  ( 

Graphi csExportComponent  ci  , 

void  *codecSetti ngsAtomContai ner , 

ImageDescri pti onHandl e  *outDesc  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 
codecSetti ngsAtomContai ner 

An  atom  container  returned  by  Graphi  csExportCanUseCompressor  (1-553). 
outDesc 

Points  to  an  image  description  handle  to  receive  an  ImageDescri  pti  on  (IV-2285) 
structure  describing  the  compressed  image. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  base  graphics  exporter  makes  this  call  to  perform  a  compressing  export. 

Special  Considerations 

This  function  is  used  for  internal  communication  between  the  base  and 
format-specific  graphics  exporter.  Applications  will  not  usually  need  to  call  it. 
Format-specific  exporters  will  normally  delegate  this  call,  unless  they  implement 
export  to  a  container  format  like  PICT  or  QuickTime  Image.  In  that  case,  they  will 
wrap  the  base  exporter's  implementation  in  one  that  forms  the  container  about  the 
compressed  data. 

Version  Notes 

Introduced  in  QuickTime  4. 


1-556 


Inside  QuickTime:  Functions  A-H 


GraphicsExportDrawInputlmage 


Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Internal  Graphics  Export  Routines"  (V-2883) 


GraphicsExportDrawInputlmage 


Draws  a  rectangular  portion  of  the  input  image  in  a  graphics  export  operation. 
ComponentResul t  GraphicsExportDrawInputlmage  ( 


Graphi csExportComponent 

ci  , 

CGraf Ptr 

gw. 

GDHandl e 

gd. 

const  Rect 

*srcRect, 

const  Rect 

*dstRect  ) 

ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component, 
gw 

A  pointer  to  an  offscreen  graphics  world,  color  graphics  port,  or  basic  graphics 
port. 

gd 

A  handle  to  a  GDevi ce  (IV-2264)  record.  If  you  pass  a  pointer  to  an  offscreen 
graphics  world  in  the  gw  parameter,  set  this  parameter  to  N I L  because 
GraphicsExportDrawInputlmage  ignores  this  parameter  and  sets  the  current 
device  to  the  device  attached  to  the  offscreen  graphics  world. 

srcRect 

Specifies  a  portion  of  the  input  image. 
dstRect 

Specifies  where  in  the  drawing  environment  to  draw  that  portion  of  the  input 
image. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  gw  and  gd  parameters  specify  a  drawing  environment  such  as  you  might  pass  to 
Graphi  csExportSetlnputGWorl  d  (1-596).  The  srcRect  and  dstRect  boundaries  need 
not  be  the  same  width  and  height;  you  can  use  this  function  to  scale  the  srcRect 
image  portion.  This  would  be  useful,  for  example,  if  you  were  writing  a  graphics 
exporter  for  a  multiple-resolution  format. 
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Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  a  Graphics  Exporter's  Input  Image"  (V-2889) 

See  Also 

When  doing  a  standalone  export,  an  exporter  will  typically  call  either 
Graph i  csExportGetlnputlmageDescri  pti  on  (1-570),  or  both 
Graph  i  csExportGetlnputlmageDi  men  si  on  s  (1-571)  and 

Graphi csExportGetlnputlmageDepth  (1-569),  to  determine  the  image's  bounds  and 

depth,  and  then  allocate  an  offscreen  graphics  world  and  call 

Graphi  csExportDrawInputlmage  to  draw  portions  of  the  image  into  that  world. 


GraphicsExportGetColorSyncProfile 


Gets  the  current  value  of  the  ColorSync  profile  for  a  graphics  export  operation. 

ComponentResul t  Graphi csExportGetCol orSyncProfi 1 e  ( 

Graphi csExportComponent  ci  , 

Handle  *col orSyncProfi 1 e  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

col orSyncProfi 1 e 

Points  to  a  variable  to  receive  the  ColorSync  profile  as  a  newly  allocated  handle. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

The  caller  is  responsible  for  disposing  of  the  returned  handle. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  Graphics  Exporter  Settings"  (V-2885) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  csExportSetCol  orSyncProfi  1  e  (1-589). 
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GraphicsExportGetCompressionMethod 


Returns  the  compression  method  for  a  graphics  export  operation. 

ComponentResul t  Graphi csExportGetCompressi onMethod  ( 

Graphi csExportComponent  ci  , 

long  *compressi onMethod  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

compressi onMethod 

Points  to  a  value  to  receive  the  compression  method. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  Graphics  Exporter  Settings"  (V-2885) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  csExportSetCompressi  onMethod 
(1-589). 

GraphicsExportGetCompressionQuality 

Returns  the  compression  quality  value  for  a  graphics  export  operation. 

ComponentResul t  Graphi csExportGetCompresslonQual i ty  ( 

Graphi csExportComponent  ci , 

CodecQ  *spati al Qual i ty  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component, 
spati al Qual i ty 

Points  to  a  variable  to  receive  a  quality  constant  (see  below). 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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spatialQuality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics, 
codec Normal  Qua  1 i ty 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 

codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field. 
codecLosslessQuality 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  Graphics  Exporter  Settings"  (V-2885) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  csExportSetCompressi  onQual  i  ty 
(1-590). 

GraphicsExportGetDefaultFileNameExtension 

Returns  the  suggested  file  name  extension  for  a  graphics  export  operation. 

ComponentResul t  Graphi csExportGetDefaul t F i 1 eNameExtensi on  ( 

Graphi csExportComponent  ci , 

OSType  *fi 1 eNameExtensi on  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

f i 1 eNameExtensi on 

Points  to  a  location  to  receive  the  file  name  extension. 
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function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

File  name  extensions  are  returned  as  upper-case  big-endian  four-character  codes. 
For  example,  the  extension  .png  would  be  returned  as  '  PNG’  (0x504E4720). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Finding  Out  About  Graphics  Export  Image  Formats" 
(V-2884) 

GraphicsExportGetDefaultFileTypeAndCreator 

Returns  the  suggested  file  type  and  creator  for  a  graphics  export  operation. 

ComponentResul t  Graphi csExportGetDefaul tFi 1 eTypeAndCreator  ( 

Graphi csExportComponent  ci , 

OSType  *fileType, 

OSType  *fileCreator  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component, 
f i 1 eType 

Points  to  a  location  to  receive  the  suggested  file  type  for  the  image  file  format. 
If  you  don't  need  this  information,  pass  N I L. 

f i 1 eCreator 

Points  to  a  location  to  receive  the  suggested  file  creator  for  the  new  image  file 
format.  If  you  don't  need  this  information,  pass  N I L. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function,  along  with  Graphi  csExportGetDefaul  tFi  1  eNameExtensi  on  (1-560)  and 
Graphi  csExportGetMIMETypeLi  st  (1-577),  returns  information  about  the  image 
format  supported  by  a  graphics  exporter.  Format-specific  exporters  must 
implement  all  three  of  these  calls. 

Version  Notes 

Introduced  in  QuickTime  4. 
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Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Finding  Out  About  Graphics  Export  Image  Formats" 
(V-2884) 

See  Also 

See  Graphl csExportGetDefaul  t Fi  1  eNameExtensI on  (1-560)  and 
Graphi  csExportGetMIMETypeLi  st  (1-577). 


GraphicsExportGetDepth 


Returns  the  current  depth  setting  for  a  graphics  export  operation. 

ComponentResul t  GraphicsExportGetDepth  ( 

Graphi csExportComponent  ci  , 

long  *depth  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

depth 

Points  to  a  variable  to  receive  the  depth. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  Graphics  Exporter  Settings"  (V-2885) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  csExportSetDepth  (1-591). 


GraphicsExportGetDontRecompress 

Determines  whether  the  original  compressed  data  for  a  graphics  export  operation 
will  not  be  decompressed  and  recompressed,  but  be  copied  through  to  the  output 
file. 

ComponentResul t  Graphi csExportGetDontRecompress  ( 

GraphicsExportComponent  ci , 
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Bool ean 


*dontRecompress  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

dontRecompress 

Points  toaBooleanto  receive  the  recompression  setting. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Even  though  it  is  not  decompressed  and  recompressed,  graphics  data  may  be 
modified  when  it  is  copied  through. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  Graphics  Exporter  Settings"  (V-2885) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  csExportSetDontRecompress  (1-592). 
To  determine  whether  a  particular  export  setting  is  available,  use 
Cal  1  ComponentCanDo  (1-58). 


GraphicsExportGetlnputDataReference 


Returns  the  current  input  data  reference  for  a  graphics  export  operation. 

ComponentResul t  Graphi csExportGetlnputDataReference  ( 

Graphi csExportComponent  ci  , 

Handle  *dataRef, 

OSType  *dataRefType  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

dataRef 

Points  to  a  variable  to  receive  the  data  reference  handle. 
dataRefType 

Points  to  a  variable  to  receive  the  data  reference  type. 
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function  result  See  "Error  Codes"  (IV-2663).  If  the  current  source  is  not  a  data 

reference,  the  function  returns  paramErr.  The  function  returns  noErr 
if  there  is  no  error. 

Discussion 

You  can  use  this  function  to  get  the  source  of  a  graphics  export  operation.  The 
source  can  be  a  QuickTime  graphics  importer  component  instance,  a  QuickDraw 
Pi  cture,  a  graphics  world,  a  Pi  xMap  (IV-2332)  structure,  or  a  piece  of  compressed 
data  described  byanlmageDescription  (IV-2285)  structure.  Compressed  data  can  be 
in  a  file,  handle,  pointer,  or  other  data  reference.  The  application  must  make  sure 
that  the  source  is  not  disposed  of  before  the  graphics  exporter  instance  is  closed  or 
given  a  new  source.  All  of  the  get  and  set  functions  for  these  sources  are 
implemented  by  the  base  graphics  exporter;  format-specific  importers  should 
delegate  all  of  them. 

Special  Considerations 

The  caller  is  responsible  for  disposing  of  the  returned  data  reference  handle. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Sources  for  Graphics  Exporter  Input  Images" 
( V-  2887) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  csExportSetlnputDataReference 
(1-593).  The  following  other  set  functions  also  specify  the  sources  for  input  images: 
Graphi  csExportSetlnputFi  1  e  (1-594),  Graphi  csExportSetlnputHandl  e  (1-597), 

Graphi csExportSetlnputPtr  (1-602),  Graphi csExportSetlnputGraphi cs Importer 
(1-595),  Graphi  csExportSetlnputPi  cture  (1-599),  Graphi  csExportSetlnputGWorl  d 
(1-596),  and  Graphi  csExportSetlnputPi  xmap  (1-600). 


GraphicsExportGetlnputDataSize 


Returns  the  number  of  bytes  of  original  image  data  that  can  be  read  in  a  graphics 
export  operation. 

ComponentResul t  GraphicsExportGetlnputDataSize  ( 

Graphi csExportComponent  ci  , 

unsi gned  1 ong  *si  ze  ) ; 
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GraphicsExportGetlnputFile 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

si  ze 

Points  to  a  variable  to  receive  the  size  in  bytes. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  used  by  format-specific  graphics  exporters  when  transcoding. 
Applications  will  not  normally  need  to  call  this  function. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Reading  Graphics  Exporter  Input  Data"  (V-2889) 


GraphicsExportGetlnputFile 


Returns  the  current  input  file  for  a  graphics  export  operation. 

ComponentResul t  GraphicsExportGetlnputFile  ( 

Graphi csExportComponent  ci  , 

FSSpec  *theFile  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

theFi  1  e 

A  pointer  to  the  file  specification  of  the  file  containing  the  graphics  data. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error.  If  the 
current  source  is  not  a  file,  the  function  returns  paramErr. 

Discussion 

You  can  use  this  function  to  get  the  source  of  a  graphics  export  operation.  The 
source  can  be  a  QuickTime  graphics  importer  component  instance,  a  QuickDraw 
Pi  cture,  a  graphics  world,  a  Pi  xMap  (IV-2332)  structure,  or  a  piece  of  compressed 
data  described  byanlmageDescription  (IV-2285)  structure.  Compressed  data  can  be 
in  a  file,  handle,  pointer,  or  other  data  reference.  The  application  must  make  sure 
that  the  source  is  not  disposed  of  before  the  graphics  exporter  instance  is  closed  or 
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given  a  new  source.  All  of  the  get  and  set  functions  for  these  sources  are 
implemented  by  the  base  graphics  exporter;  format-specific  importers  should 
delegate  all  of  them. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Sources  for  Graphics  Exporter  Input  Images" 
(V-2887) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  csExportSetlnputFi  1  e  (1-594).  The 
following  other  set  functions  also  specify  the  sources  for  input  images: 

Graphi  cs  Expo  rtSet  Input  Data  Reference  (1-593),  Graphi  csExportSetlnputHandl  e 
(1-597),  Graphi  csExportSetlnputPtr  (1-602), 

Graphi  cs  Expo  rtSet  I  nputGraphi  cslmporter  (1-595),  Graphi  cs  Expo  rtSet  Input  Pi  cture 
(1-599),  Graphi  csExportSetlnputGWorl  d  (1-596),  and  Graphi  csExportSetlnputPi xmap 
(1-600). 


GraphicsExportGetlnputGraphicsImporter 


Returns  the  current  input  graphics  importer  instance  for  a  graphics  export 
operation. 

ComponentResul t  Graphi csExportGetlnputGraphi cslmporter  ( 

Graphi csExportComponent  ci  , 

Graphi csImportComponent  *grip  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

grip 

Points  to  a  variable  to  receive  the  source  graphics  importer. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  must  get  the  source  of  a  graphics  export  operation.  The  source  can  be  a 
QuickTime  graphics  importer  component  instance,  a  QuickDraw  Pi  cture,  a 
graphics  world,  a  Pi  xMap  (IV-2332)  structure,  or  a  piece  of  compressed  data 
described  by  an  ImageDescri  pti  on  (IV-2285)  structure.  Compressed  data  can  be  in  a 
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file,  handle,  pointer,  or  other  data  reference.  The  application  must  make  sure  that 
the  source  is  not  disposed  of  before  the  graphics  exporter  instance  is  closed  or  given 
a  new  source.  All  of  the  get  and  set  functions  for  these  sources  are  implemented  by 
the  base  graphics  exporter;  format-specific  importers  should  delegate  all  of  them. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Sources  for  Graphics  Exporter  Input  Images" 
(V-  2887) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  csExportSetlnputGraphi  cs  Importer 
(1-595).  The  following  other  set  functions  also  specify  the  sources  for  input  images: 
Graphi  cs  Export  Set  In  put  Data  Reference  (1-593),  Graphi  csExportSetlnputFi  1  e  (1-594), 
Graphi  csExportSetlnputHandl  e  (1-597),  Graphi  csExportSetlnputPtr  (1-602), 

Graphi  cs  Export  Set  Input  Pi  cture  (1-599),  Graphi  cs  Export  Set  In  put  GWorl  d  (1-596),  and 
Graphi  csExportSetlnputPixmap  (1-600). 


GraphicsExportGetlnputG  W  orld 


Returns  the  current  input  graphics  world  for  a  graphics  export  operation. 

ComponentResul t  Graphi csExportGetlnputGWorl d  ( 

Graphi csExportComponent  ci  , 

GWorldPtr  *gworld  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

gworl  d 

Points  to  a  variable  to  receive  the  source  graphics  world. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  can  use  this  function  to  get  the  source  of  a  graphics  export  operation.  The 
source  can  be  a  QuickTime  graphics  importer  component  instance,  a  QuickDraw 
Pi  cture,  a  graphics  world,  a  Pi  xMap  (IV-2332)  structure,  or  a  piece  of  compressed 
data  described  by  an  ImageDescription  (IV-2285)  structure.  Compressed  data  can  be 
in  a  file,  handle,  pointer,  or  other  data  reference.  The  application  must  make  sure 
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that  the  source  is  not  disposed  of  before  the  graphics  exporter  instance  is  closed  or 
given  a  new  source.  All  of  the  get  and  set  functions  for  these  sources  are 
implemented  by  the  base  graphics  exporter;  format-specific  importers  should 
delegate  all  of  them. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Sources  for  Graphics  Exporter  Input  Images" 
(V-2887) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  csExportSetlnputGWorl  d  (1-596).  The 
following  other  set  functions  also  specify  the  sources  for  input  images: 

Graphi  cs  Expo  rtSet  Input  Data  Reference  (1-593),  Graphi  csExportSetlnputFi  1  e  (1-594), 
Graphi  csExportSetlnputHandl  e  (1-597),  Graphi  csExportSetlnputPtr  (1-602), 

Graphi  cs  Expo  rtSet  I  nputGraphi  cslmporter  (1-595),  Graphi  cs  Expo  rtSet  Input  Pi  cture 
(1-599),  and  Graphi  cs  Expo  rtSet  Input  Pi  xmap  (1-600). 


GraphicsExportGetlnputHandle 


Returns  the  current  input  handle  for  a  graphics  export  operation. 

ComponentResul t  GraphicsExportGetlnputHandle  ( 

Graphi csExportComponent  ci  , 

Handle  *h  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

h 

A  pointer  to  receive  the  handle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error.  If  the 
current  source  is  not  a  handle,  the  function  returns  paramErr. 

Discussion 

You  can  use  this  function  to  get  the  source  of  a  graphics  export  operation.  The 
source  can  be  a  QuickTime  graphics  importer  component  instance,  a  QuickDraw 
Pi  cture,  a  graphics  world,  a  Pi  xMap  (IV-2332)  structure,  or  a  piece  of  compressed 
data  described  by  an  ImageDescription  (IV-2285)  structure.  Compressed  data  can  be 
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GraphicsExportGetlnputlmageDepth 


in  a  file,  handle,  pointer,  or  other  data  reference.  The  application  must  make  sure 
that  the  source  is  not  disposed  of  before  the  graphics  exporter  instance  is  closed  or 
given  a  new  source.  All  of  the  get  and  set  functions  for  these  sources  are 
implemented  by  the  base  graphics  exporter;  format-specific  importers  should 
delegate  all  of  them. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Sources  for  Graphics  Exporter  Input  Images" 
(V-  2887) 

See  Also 

For  the  corresponding  set  function,  see  Graphi csExportSetlnputHandl  e  (1-597).  The 
following  other  set  functions  also  specify  the  sources  for  input  images: 

Graphi  cs  Export  Set  In  put  Data  Reference  (1-593),  Graphi  csExportSetlnputFi  1  e  (1-594), 
Graphi csExportSetlnputPtr  (1-602),  Graphi csExportSetlnputGraphi cslmporter 
(1-595),  Graphi  csExportSetlnputPi  cture  (1-599),  Graphi  csExportSetlnputGWorl  d 
(1-596),  and  Graphi  csExportSetlnputPixmap  (1-600). 


GraphicsExportGetlnputlmageDepth 


Returns  the  depth  of  the  input  image  for  a  graphics  export  operation. 

ComponentResul t  Graphi csExportGetlnputlmageDepth  ( 

Graphi csExportComponent  ci  , 

long  *inputDepth  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

i nputDepth 

Points  to  a  variable  to  receive  the  input  image  depth. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  a  Graphics  Exporter's  Input  Image"  (V-2889) 
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See  Also 

When  doing  a  standalone  export,  an  exporter  will  typically  call  either 
Graph i  cs Expo rtGet Input ImageDescri  pti  on  (1-570),  or  both 
GraphicsExportGetlnputlmageDimensions  (1-571)  and 

Graphi csExportGetlnputlmageDepth,  to  determine  the  image's  bounds  and  depth, 
and  then  allocate  an  offscreen  graphics  world  and  call 

Graphi csExportDrawInputlmage  (1-557)  to  draw  portions  of  the  image  into  the 
graphics  world. 


GraphicsExportGetlnputlmageDescription 


Returns  an  image  description  describing  the  input  image  in  a  graphics  export 
operation. 

ComponentResul t  Graphi csExportGetlnputlmageDescripti on  ( 

Graphi csExportComponent  ci  , 

ImageDescri pti onHandl e  *desc  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

desc 

Points  to  a  variable  to  receive  a  handle  to  an  ImageDescri  pti  on  (IV-2285) 
structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns  an  ImageDescri  pti  on  (IV-2285)  structure  containing 
information  such  as  the  format  of  the  compressed  data,  its  bit  depth,  natural 
bounds,  and  resolution. 

Special  Considerations 

The  caller  is  responsible  for  disposing  of  the  returned  image  description  handle. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  a  Graphics  Exporter's  Input  Image"  (V-2889) 
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See  Also 

When  doing  a  standalone  export,  an  exporter  will  typically  call 
Graphi csExportGetlnputlmageDescri pti on,  or 
Graphi  csExportGetlnputlmageDimensi  ons  (1-571)  and 

Graphi  csExportGetlnputlmageDepth  (1-569),  to  determine  the  image's  bounds  and 
depth,  and  then  allocate  an  offscreen  graphics  world  and  call 
Graphi  csExportDrawInputlmage  (1-557)  to  draw  portions  of  the  image  into  the 
graphics  world. 


GraphicsExportGetlnputlmageDimensions 


Returns  the  dimensions  of  the  input  image  in  a  graphics  export  operation. 

ComponentResul t  GraphicsExportGetlnputlmageDimensions  ( 

Graphi csExportComponent  ci  , 

Rect  *dimensions  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component, 
di mensi ons 

Points  to  a  rectangle  to  receive  the  dimensions  of  the  input  image. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  a  Graphics  Exporter's  Input  Image"  (V-2889) 

See  Also 

When  doing  a  standalone  export,  an  exporter  will  typically  call 
Graphi  csExportGetlnputlmageDescri  pti  on  (1-570),  or 

Graphi  csExportGetlnputlmageDimensi ons  and  Graphi  csExportGetlnputlmageDepth 
(1-569),  to  determine  the  image's  bounds  and  depth,  and  then  allocate  an  offscreen 
graphics  world  and  call  Graphi  csExportDrawInputlmage  (1-557)  to  draw  portions  of 
the  image  into  the  graphics  world. 
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GraphicsExportGetlnputOffsetAndLimit 


Retrieves  the  current  input  offset  and  limit  in  a  graphics  export  operation. 

ComponentResul t  GraphicsExportGetlnputOffsetAndLimit  ( 

Graphi csExportComponent  ci  , 

unsigned  long  *offset, 

unsigned  long  *limit  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component, 
offset 

Points  to  a  variable  to  receive  the  offset.  If  you  don't  need  this  information,  pass 
NIL. 
limit 

Points  to  a  variable  to  receive  the  limit.  If  you  don't  need  this  information,  pass 
NIL. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  only  applicable  when  the  input  is  a  data  reference,  file,  handle  or 
pointer. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Restricting  the  Range  of  an  Input  Image's  Source" 
(V-2888) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  csExportSetlnputOffsetAndLi  mi  t 
(1-598). 

GraphicsExportGetlnputPicture 

Returns  the  current  input  picture  in  a  graphics  export  operation. 

ComponentResul t  GraphicsExportGetlnputPicture  ( 

Graphi csExportComponent  ci , 

PicHandle  *picture  ); 


1-572 


Inside  QuickTime:  Functions  A-H 


GraphicsExportGetlnputPixmap 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component, 
pi cture 

Points  to  a  variable  to  receive  the  source  picture. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  can  use  this  function  to  get  the  source  of  a  graphics  export  operation.  The 
source  can  be  a  QuickTime  graphics  importer  component  instance,  a  QuickDraw 
Pi  cture,  a  graphics  world,  a  Pi  xMap  (IV-2332)  structure,  or  a  piece  of  compressed 
data  described  byanlmageDescription  (IV-2285)  structure.  Compressed  data  can  be 
in  a  file,  handle,  pointer,  or  other  data  reference.  The  application  must  make  sure 
that  the  source  is  not  disposed  of  before  the  graphics  exporter  instance  is  closed  or 
given  a  new  source.  All  of  the  get  and  set  functions  for  these  sources  are 
implemented  by  the  base  graphics  exporter;  format-specific  importers  should 
delegate  all  of  them. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Sources  for  Graphics  Exporter  Input  Images" 
(V-  2887) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  cs  Export  Set  In  put  Pi  cture  (1-599).  The 
following  other  set  functions  also  specify  the  sources  for  input  images: 

Graphi  cs  Export  Set  In  put  Data  Reference  (1-593),  Graphi  csExportSetlnputFi  1  e  (1-594), 
Graphi  csExportSetlnputHandl  e  (1-597),  Graphi  csExportSetlnputPtr  (1-602), 

Graphi  csExportSetlnputGraphi  cs  Importer  (1-595),  Graphi  cs  Export  Set  InputGWorl  d 
(1-596),  and  Graphi  csExportSetlnputPixmap  (1-600). 


GraphicsExportGetlnputPixmap 


Returns  the  current  input  pi xmap  in  a  graphics  export  operation. 

ComponentResul t  GraphicsExportGetlnputPixmap  ( 

Graphi csExportComponent  ci  , 

PixMapHandle  *pixmap  ); 
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ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component, 
pi xmap 

Points  to  a  variable  to  receive  the  source  Pi  xMap  (IV-2332)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  can  use  this  function  to  get  the  source  of  a  graphics  export  operation.  The 
source  can  be  a  QuickTime  graphics  importer  component  instance,  a  QuickDraw 
Pi  cture,  a  graphics  world,  a  Pi  xMap  (IV-2332)  structure,  or  a  piece  of  compressed 
data  described  by  anlmageDescription  (IV-2285)  structure.  Compressed  data  can  be 
in  a  file,  handle,  pointer,  or  other  data  reference.  The  application  must  make  sure 
that  the  source  is  not  disposed  of  before  the  graphics  exporter  instance  is  closed  or 
given  a  new  source.  All  of  the  get  and  set  functions  for  these  sources  are 
implemented  by  the  base  graphics  exporter;  format-specific  importers  should 
delegate  all  of  them. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Sources  for  Graphics  Exporter  Input  Images" 
(Y-28S7) 

See  Also 

For  the  corresponding  set  function,  see  Graphl  csExportSetlnputPixmap  (1-600).  The 
following  other  set  functions  also  specify  the  sources  for  input  images: 

Graph  i  cs  Expo  rtSet  Input  Data  Reference  (1-593),  Graphl  csExportSetlnputFi  1  e  (1-594), 
Graphi  csExportSetlnputHandl  e  (1-597),  Graphi  csExportSetlnputPtr  (1-602), 

Graph  i  cs  Expo  rtSet  I  nputGraphi  cslmporter  (1-595),  Graphi  cs  Expo  rtSet  Input  Pi  cture 
(1-599),  and  Graphi  csExportSetlnputGWorl  d  (1-596). 


GraphicsExportGetlnputPtr 


Returns  the  current  input  pointer  in  a  graphics  export  operation. 

ComponentResul t  GraphicsExportGetlnputPtr  ( 

Graphi csExportComponent  ci  , 

Ptr  *p, 

unsi gned  1 ong  *si  ze  ) ; 
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ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

P 

A  pointer  to  receive  a  pointer  containing  the  graphics  data. 

si  ze 

A  pointer  to  a  value  describing  the  size  of  the  image  data  in  bytes. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  can  use  this  function  to  get  the  source  of  a  graphics  export  operation.  The 
source  can  be  a  QuickTime  graphics  importer  component  instance,  a  QuickDraw 
Pi  cture,  a  graphics  world,  a  Pi  xMap  (IV-2332)  structure,  or  a  piece  of  compressed 
data  described  byanlmageDescription  (IV-2285)  structure.  Compressed  data  can  be 
in  a  file,  handle,  pointer,  or  other  data  reference.  The  application  must  make  sure 
that  the  source  is  not  disposed  of  before  the  graphics  exporter  instance  is  closed  or 
given  a  new  source.  All  of  the  get  and  set  functions  for  these  sources  are 
implemented  by  the  base  graphics  exporter;  format-specific  importers  should 
delegate  all  of  them. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Sources  for  Graphics  Exporter  Input  Images" 
( V-  2887) 

See  Also 

For  the  corresponding  set  function,  see  Graph icsExportSetlnputPtr  (1-602) .  The 
following  other  set  functions  also  specify  the  sources  for  input  images: 

Graphi  cs  Export  Set  In  put  Data  Reference  (1-593),  Graph  1  csExportSetlnputFi  1  e  (1-594), 
Graphi  cs  Export  Set  Input  Ha  ndl  e  (1-597),  Graphi  cs  Export  Set  InputGraphl  cs  Importer 
(1-595),  Graphi  csExportSetlnputPi  cture  (1-599),  Graphi  csExportSetlnputGWorl  d 
(1-596),  and  Graphi  csExportSetlnputPixmap  (1-600). 


GraphicsExportGetlnterlaceStyle 

Returns  the  interlace  style  in  a  graphics  export  operation. 

ComponentResul t  Graphi csExportGetlnterl aceStyl e  ( 
Graphi csExportComponent  ci , 
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unsigned  long 


*i nterl aceStyl e  ) ; 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

i nterl aceStyl e 

Points  to  a  variable  to  receive  the  interlace  style.  Valid  values  and 
interpretations  are  defined  by  individual  exporters.  In  QuickTime  4,  the  PNG 
graphics  exporter  supports  the  interlaceStyle  settings  shown  below 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

interlaceStyle  Constants 

kQTPNGI nterl ace None 

No  interlace.  Value  is  0. 
kQTPNGI nterl aceAdam7 

Uses  the  2D  Adam7  algorithm.  Value  is  1. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  Graphics  Exporter  Settings"  (V-2885) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  csExportSetlnterl  aceStyl  e  (1-603). 


GraphicsExportGetMetaData 


Returns  the  current  user  data  setting  in  a  graphics  export  operation. 

ComponentResul t  GraphicsExportGetMetaData  ( 

Graphi csExportComponent  ci  , 

voi d  *userData  ) ; 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 
userData 

A  pointer  to  a  UserData  Record  (IV-2496)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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Version  Notes 

Introduced  in  QuickTime  4.  In  QuickTime  4,  none  of  the  supplied  graphics 
exporters  support  setting  user  data. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  Graphics  Exporter  Settings"  (V-2885) 

See  Also 

For  the  corresponding  set  function,  see  Graph icsExportSetMetaData  (1-604). 


GraphicsExportGetMIMETypeList 


Returns  MIME  types  and  other  information  about  the  graphics  format  in  a  graphics 
export  operation. 

ComponentResul t  GraphicsExportGetMIMETypeList  ( 

Graphi csExportComponent  ci  , 

void  *qtAtomContai nerPtr  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

qtAtomContai nerPtr 

Receives  a  newly-created  QuickTime  atom  container  that  contains  information 
about  the  graphics  format. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  creates  and  returns  a  QuickTime  atom  container  that  contains  the 
format's  name,  as  a  string  in  an  atom  of  type  ’desc'(kMimelnfoDescriptionTag),  and 
optionally  the  MIME  type  as  a  string  in  an  atom  of  type  '  mi  me ' 
(kMimelnfoMimeTypeTag). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Finding  Out  About  Graphics  Export  Image  Formats" 
(V-2884) 
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GraphicsExportGetOutputDataReference 


Gets  the  output  data  reference  handle  in  a  graphics  export  operation. 

ComponentResul t  Graphi csExportGetOutputDataReference  ( 

Graphi csExportComponent  ci  , 

Handle  *dataRef, 

OSType  *dataRefType  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 
dataRef 

Points  to  a  variable  to  receive  the  data  reference  handle. 
dataRefType 

Points  to  a  variable  to  receive  a  constant  that  identifies  the  data  reference  type. 
See  "Data  References"  (IV-2661). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

The  caller  is  responsible  for  disposing  of  the  returned  data  reference  handle. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Destinations  for  Output  Images"  (V-2890) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  csExportSetOutputDataReference 
(1-604). 

GraphicsExportGetOutputFile 

Returns  the  current  output  file  for  a  graphics  export  operation. 

ComponentResul t  GraphicsExportGetOutputFile  ( 

Graphi csExportComponent  ci , 

FSSpec  *theFile  ); 
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ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 
theFi  1  e 

Points  to  a  variable  to  receive  the  FSSpec  (IV-2262). 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Destinations  for  Output  Images"  (V-2890) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  csExportSetOutputFi  1  e  (1-605). 


GraphicsExportGetOutputFileTypeAndCreator 


Gets  the  type  and  creator  codes  for  the  output  file  in  a  graphics  export  operation. 

ComponentResul t  Graphi csExportGetOutputFi 1 eTypeAndCreator  ( 

Graphi csExportComponent  ci  , 

OSType  *fileType, 

OSType  *fileCreator  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component, 
f i 1 eType 

Receives  the  file  type  for  the  new  image  file.  See  "File  Types  and  Creators" 
(IV-2668). 

f i 1 eCreator 

Receives  the  file  creator  for  the  new  image  file.  See  "File  Types  and  Creators" 
(IV-2668). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 
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Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Destinations  for  Output  Images"  (V-2890) 

See  Also 

For  the  corresponding  set  function,  see 

Graph i  csExportSetOutputFi  1  eTypeAndCreator  (1-606). 


GraphicsExportGetOutputHandle 


Returns  the  current  output  handle  for  a  graphics  export  operation. 

ComponentResul t  GraphicsExportGetOutputHandle  ( 

Graphi csExportComponent  ci  , 

Handle  *h  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

h 

Points  to  a  variable  to  receive  the  handle. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Destinations  for  Output  Images"  (V-2890) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  csExportSetOutputHandl  e  (1-606). 


GraphicsExportGetOutputMark 


Returns  the  current  file  position  for  a  graphics  export  operation. 

ComponentResul t  GraphicsExportGetOutputMark  ( 

Graphi csExportComponent  ci  , 

unsigned  long  *mark  ); 
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ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

mark 

Receives  the  current  file  position,  as  a  byte  offset  from  the  beginning  of  the 
output  data  reference. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

Not  all  output  data  types  support  the  current  file  position  feature. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Writing  Graphics  Exporter  Output  Data"  (V-2891) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  csExportSetOutputMark  (1-607). 


GraphicsExportGetOutputOffsetAndMaxSize 

Returns  the  output  starting  offset  and  maximum  size  limit  for  a  graphics  export 
operation. 

ComponentResul t  Graphi csExportGetOutputOffsetAndMaxSize  ( 

Graphi csExportComponent  ci , 
unsigned  long  *offset, 

unsigned  long  *maxSize, 

Boolean  *truncateFi 1 e  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

offset 

On  return,  a  value  describing  the  byte  offset  of  the  image  data  from  the 
beginning  of  the  data  reference.  If  you  are  not  interested  in  this  information, 
you  may  pass  NIL. 
maxSi ze 

On  return,  a  value  describing  the  maximum  size  limit.  If  you  are  not  interested 
in  this  information,  you  may  pass  NIL. 
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truncateFi 1 e 

A  Bool  ean  value;  TRUE  means  to  truncate  the  file,  FALSE  means  not. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Destinations  for  Output  Images"  (V-2890) 

See  Also 

For  the  corresponding  set  function,  see  Graphi csExportSetOutputOffsetAndMaxSi  ze 
(1-608). 


GraphicsExportGetProgressProc 


Returns  the  current  progress  function  for  a  graphics  export  operation. 

ComponentResul t  GraphicsExportGetProgressProc  ( 

Graphi csExportComponent  ci  , 

ICMProgressProcRecordPtr  progressProc  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

progressProc 

A  pointer  to  an  ICMProgressProc  (III— 2093)  callback. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

By  default,  graphics  export  components  have  no  progress  functions. 

Special  Considerations 

This  function  is  always  implemented  by  the  base  graphics  exporter. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Getting  and  Setting  Progress  Procs"  (V-2887) 
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See  Also 

For  the  corresponding  set  function,  see  Graphi  csExportSetProgressProc  (1-608). 


GraphicsExportGetResolution 


Determines  the  resolution  of  a  graphics  exporter  component. 

ComponentResul t  GraphicsExportGetResolution  ( 

Graphi csExportComponent  ci  , 

Fixed  *hori zontal Resol uti on , 

Fixed  *verti cal  Resol uti on  ); 


ci 

A  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

hori zontal Resol uti on 

Points  to  a  variable  to  receive  the  horizontal  resolution, 
verti cal  Resol uti on 

Points  to  a  variable  to  receive  the  vertical  resolution. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  Graphics  Exporter  Settings"  (V-2885) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  csExportSetResol  uti  on  (1-609). 


GraphicsExportGetSettingsAsAtomContainer 


Retrieves  the  current  settings  from  a  graphics  exporter  component. 

ComponentResul t  Graphi csExportGetSetti ngsAsAtomContai ner  ( 
Graphi csExportComponent  ci  , 

void  *qtAtomContai nerPtr  ); 
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ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 
qtAtomContai nerPtr 

Points  to  a  variable  to  receive  a  new  QuickTime  atom  container  containing  the 
current  graphics  exporter  component  settings. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

The  caller  is  responsible  for  disposing  of  the  returned  atom  container. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Obtaining  Graphics  Exporter  Settings"  (V-2885) 

See  Also 

For  the  corresponding  set  function,  see 

Graph  1  csExportSetSetti  ngsFromAtomContai  ner  (1-610). 


GraphicsExportGetSettings  AsT  ext 


Retrieves  the  current  settings  from  the  graphics  export  component  in  a 
user-readable  format. 

ComponentResul t  Graphi csExportGetSettingsAsText  ( 

Graphi csExportComponent  cl, 

Handle  *theText  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 
theText 

Points  to  a  variable  to  receive  a  newly-allocated  handle  containing  text. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

The  caller  is  responsible  for  disposing  of  the  returned  handle. 

Version  Notes 

Introduced  in  QuickTime  4. 
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Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Obtaining  Graphics  Exporter  Settings"  (V-2885) 


GraphicsExportGetT  argetDataSize 


Returns  the  current  desired  maximum  data  size  for  a  graphics  export  operation. 

ComponentResul t  Graphi csExportGetTargetDataSize  ( 

Graphi csExportComponent  ci  , 

unsigned  long  *targetDataSi ze  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 
targetDataSi ze 

Points  to  a  variable  to  receive  the  desired  maximum  data  size  in  bytes. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  Graphics  Exporter  Settings"  (V-2885) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  csExportSetTargetDataSi  ze  (1-611). 


GraphicsExportMayExporterReadlnputData 


Asks  whether  the  image  source  for  a  graphics  export  operation  is  in  a  form  that  the 
exporter  can  read. 

ComponentResul t  Graphi csExportMayExporterReadlnputData  ( 

Graphi csExportComponent  ci  , 

Boolean  *mayReadInputData  ); 


The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 
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mayReadlnputData 

Points  toaBoolean;TRUE  means  that  the  image  source  is  in  a  form  that  the 
exporter  can  read,  FALSE  means  it  is  not. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Some  kinds  of  image  source,  such  as  files  and  handles,  form  a  stream  of  bytes  that 
can  be  read  directly.  Others,  such  as  pictures  and  pixmaps,  do  not.  Format-specific 
graphics  exporters  usually  cannot  transcode  if  they  cannot  read  the  original  data,  so 
those  exporters  which  implement  Graphi  csExportCanT ranscode  (1-552)  will  usually 
first  call  Graphi  cs  Expo  rtMay  Exporter  Read  Input  Data. 

Special  Considerations 

This  function  is  used  by  format-specific  graphics  exporters  when  transcoding. 
Applications  will  not  normally  need  to  call  this  function. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Reading  Graphics  Exporter  Input  Data"  (V-2889) 


GraphicsExportReadlnputData 


Reads  the  original  image  data  in  a  graphics  export  operation. 

ComponentResul t  GraphicsExportReadlnputData  ( 

Graphi csExportComponent  ci  , 
void  *dataPtr, 

unsigned  long  dataOffset, 

unsigned  long  dataSize  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

dataPtr 

A  pointer  to  a  memory  block  to  receive  the  data. 
dataOffset 

The  offset  of  the  image  data  within  the  source  image  data.  The  function  begins 
reading  image  data  from  this  offset. 
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dataSi ze 

The  number  of  bytes  of  image  data  to  read. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  communicates  with  the  appropriate  data  handler  to  retrieve  image 
data. 

Special  Considerations 

This  function  is  used  by  format-specific  graphics  exporters  when  transcoding. 
Applications  will  not  normally  need  to  call  this  function. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Reading  Graphics  Exporter  Input  Data"  (V-2889) 


GraphicsExportReadOutputData 


Reads  output  image  data  in  a  graphics  export  operation. 

ComponentResul t  GraphicsExportReadOutputData  ( 

Graphi csExportComponent  ci  , 
void  *dataPtr, 

unsigned  long  dataOffset, 

unsigned  long  dataSize  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

dataPtr 

A  pointer  to  a  memory  block  to  receive  the  data. 
dataOffset 

The  offset  of  the  image  data  within  the  data  reference.  The  function  begins 
reading  image  data  from  this  offset. 
dataSi ze 

The  number  of  bytes  of  image  data  to  read. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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Special  Considerations 

Not  all  output  data  types  support  this  function. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Writing  Graphics  Exporter  Output  Data"  (V-2891) 


GraphicsExportRequestSettings 


Displays  a  dialog  for  the  user  to  configure  graphics  exporter  settings,  if  applicable. 

ComponentResul t  GraphicsExportRequestSettings  ( 

Graphi csExportComponent  ci  , 

Modal Fi 1 terYDUPP  filterProc, 

void  *yourDataProc  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component, 
f i 1 terProc 

AModalFilterYDProc  (III— 2099)  callback.  If  you  don't  need  one,  pass  NIL. 
yourDataProc 

An  extra  parameter  that  will  be  passed  to  the  Modal  Fi  1  terProc  callback  when  it 
is  called.  If  you  don't  need  one,  pass  N I L. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Some  graphics  exporters  don't  support  settings  dialogs,  and  so  don't  implement 
this  call.  To  find  out  whether  a  graphics  exporter  implements  this  call,  you  can  use 
this  code: 

Call  Component Can  Dot  my Graphi cs Exporter , 

kGraphi csExportRequestSetti ngsSelect) ; 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Obtaining  Graphics  Exporter  Settings"  (V-2885) 
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See  Also 


See  Cal  1  ComponentCanDo  (1-58). 


GraphicsExportSetColorSyncProfile 


Sets  the  ColorSync  profile  to  embed  in  the  image  file  for  a  graphics  export  operation. 

ComponentResul t  Graphi csExportSetCol orSyncProf i 1 e  ( 

Graphi csExportComponent  ci  , 

Handle  col orSyncProf i 1 e  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component, 
col orSyncProf i 1 e 

A  handle  to  the  ColorSync  profile. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

ColorSync  profiles  allow  image  files  to  describe  their  native  colorspace  in  a 
self-contained  manner.  They  can  be  stored  in  atoms  of  type  '  i  i  cc '  (IV-2547). 

Version  Notes 

Introduced  in  QuickTime  4.  Starting  with  QuickTime  4,  the  JPEG,  PNG,  PICT, 
QuickTime  Image  and  TIFF  graphics  exporters  support  embedded  ColorSync 
profiles. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  Graphics  Exporter  Settings"  (V-2885) 

See  Also 

For  the  corresponding  get  function,  see  Graphi  cs  Export  Get  Col  orSyncProf  i  1  e  (1-558). 


GraphicsExportSetCompressionMethod 


Defines  the  compression  method  to  use  in  a  graphics  export  operation. 

ComponentResul t  Graphi csExportSetCompresslonMethod  ( 

Graphi csExportComponent  ci , 

long  compressi onMethod  ); 
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ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component, 
comp  res si onMethod 

A  value  (see  below)  describing  the  compression  algorithm  to  be  used  by  the 
graphics  exporter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

compressionMethod  Constants 

kQTTI FFCompressi on_None 

No  compression.  This  value  is  1. 
kQTTI FFCompressi on_PackBi  ts 

PackBits  compression.  This  value  is  32773L 

Discussion 

In  QuickTime  4,  the  TIFF  graphics  exporter  supports  the  comp  res  si  onMethod  settings 
kQTTI  FFCompressi  on_None  and  kQTTI  FFCompressi  on_PackBi  ts.  Some  image  formats, 
such  as  TIFF,  support  several  compression  methods. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  Graphics  Exporter  Settings"  (V-2885) 

See  Also 

For  the  corresponding  get  function,  see  Graphi  csExportGetCompressi  onMethod 
(1-559). 

GraphicsExportSetCompressionQuality 

Defines  the  compression  quality  for  a  graphics  export  operation. 

ComponentResul t  Graphi csExportSetCompressi onQual i ty  ( 

Graphi csExportComponent  ci , 

CodecQ  spati al Qual i ty  ); 


The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 
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spati al Qual i ty 

A  constant  (see  below)  that  defines  the  currently  specified  quality  value. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

spatialQuality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 
codecNormal Quality 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 

codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field, 
codec Los  si  ess Qual i ty 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

Discussion 

This  setting  is  only  supported  by  lossy  compression  methods. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  Graphics  Exporter  Settings"  (V-2885) 

See  Also 

For  the  corresponding  get  function,  see  Graphi  csExportGetCompressi  onQual  i  ty 
(1-559). 

GraphicsExportSetDepth 

Defines  the  depth  to  use  in  a  graphics  export  operation. 

ComponentResul t  GraphicsExportSetDepth  ( 

Graphi csExportComponent  ci , 

long  depth  ); 


Inside  QuickTime:  Functions  A-H 


1-591 


GraphicsExportSetDontRecompress 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component, 
depth 

A  value  describing  the  depth  of  the  image  data.  Some  image  file  formats 
support  more  than  one  pixel  depth. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  BMP,  JPEG,  Photoshop,  PNG,  PICT,  QuickTime  Image,  TGA  and  TIFF  graphics 
exporters  support  the  depth  setting.  Some  image  file  formats  support  more  than  one 
pixel  depth. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  Graphics  Exporter  Settings"  (V-2885) 

See  Also 

For  the  corresponding  get  function,  see  Graphi  csExportGetDepth  (1-562). 


GraphicsExportSetDontRecompress 


Requests  that  the  original  compressed  data  for  a  graphics  export  operation  not  be 
decompressed  and  recompressed,  but  be  copied  through  to  the  output  file. 

ComponentResul t  Graphi csExportSetDontRecompress  ( 

Graphi csExportComponent  cl, 

Boolean  dontRecompress  ); 


cl 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 
dontRecompress 

If  TRUE,  requests  not  to  recompress  the  image  data. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Even  though  it  is  not  decompressed  and  recompressed,  graphics  data  may  be 
modified  when  it  is  copied  through. 
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Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  Graphics  Exporter  Settings"  (V-2885) 

See  Also 

For  the  corresponding  get  function,  see  Graphi  csExportGetDontRecompress  (1-562). 
To  determine  whether  a  particular  export  setting  is  available,  use 
Cal  1  ComponentCanDo  (1-58). 


GraphicsExportSetlnputDataReference 


Specifies  that  the  source  image  for  a  graphics  export  operation  is  a  compressed 
image  stored  in  a  data  reference. 


Component Res ul t  Graphi cs Export Set  In put Data  Reference 
Graphi csExportComponent  ci  , 

Handle  dataRef, 

OSType  dataRefType, 

ImageDescri pti onHandl e  desc  ); 


( 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

dataRef 

A  QuickTime  data  reference.  See  "Data  References"  (IV-2661). 
dataRefType 

The  type  of  the  data  reference;  see  "Data  References"  (IV-2661). 

desc 

A  handle  to  an  ImageDescri  pti  on  (IV-2285)  structure,  describing  the 
compressed  data. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  can  use  this  function  to  specify  a  source  before  you  call  Graphi  c  s  E x  p  o  r  t  D  o  E x  p  o  r  t 
(1-554).  The  source  can  be  a  QuickTime  graphics  importer  component  instance,  a 
QuickDraw  Pi  cture,  a  graphics  world,  a  Pi  xMap  (IV-2332)  structure,  or  a  piece  of 
compressed  data  described  by  an  ImageDescri  pti  on  (IV-2285)  structure. 
Compressed  data  can  be  in  a  file,  handle,  pointer,  or  other  data  reference.  The 
application  must  make  sure  that  the  source  is  not  disposed  of  before  the  graphics 
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GraphicsExportSetlnputFile 


exporter  instance  is  closed  or  given  a  new  source.  All  of  the  get  and  set  functions  for 
these  sources  are  implemented  by  the  base  graphics  exporter;  format-specific 
importers  should  delegate  all  of  them. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Sources  for  Graphics  Exporter  Input  Images" 
(V-2887) 

See  Also 

For  the  corresponding  get  function,  see  Graphi  csExportGetlnputDataReference 
(1-563).  The  following  other  functions  let  you  get  the  sources  for  input  images: 
Graphi  csExportGetlnputFi  1  e  (1-565),  Graphi  csExportGetlnputHandl  e  (1-568), 

Graphi  csExportGetlnputPtr  (1-574),  Graphi  csExportGetlnputGraphi  cs Importer 
(1-566),  Graphi  csExportGetlnputPi  cture  (1-572),  Graphi  csExportGetlnputGWorl  d 
(1-567),  and  Graphi  csExportGetlnputPi xmap  (1-573). 


GraphicsExportSetlnputFile 


Specifies  that  the  source  image  for  a  graphics  export  operation  is  a  compressed 
image  stored  in  a  file. 

ComponentResul t  GraphicsExportSetlnputFile  ( 

Graphi csExportComponent  ci  , 

const  FSSpec  *theFile, 

ImageDescri pti onHandl e  desc  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 
theFi  1  e 

A  pointer  to  the  FSSpec  (IV-2262)  structure  for  the  file  containing  the  graphics 
data. 

desc 

A  handle  to  an  ImageDescri  pti  on  (IV-2285)  structure  that  describes  the 
compressed  data. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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Discussion 

You  can  use  this  function  to  specify  a  source  before  you  call  Graph  i  c  s  E x  p  o  r  t  D  o  E x  p  o  r  t 
(1-554).  The  source  can  be  a  QuickTime  graphics  importer  component  instance,  a 
QuickDraw  Pi  cture,  a  graphics  world,  a  Pi  xMap  (IV-2332)  structure,  or  a  piece  of 
compressed  data  described  by  an  ImageDescri  pti  on  (IV-2285)  structure. 
Compressed  data  can  be  in  a  file,  handle,  pointer,  or  other  data  reference.  The 
application  must  make  sure  that  the  source  is  not  disposed  of  before  the  graphics 
exporter  instance  is  closed  or  given  a  new  source.  All  of  the  get  and  set  functions  for 
these  sources  are  implemented  by  the  base  graphics  exporter;  format-specific 
importers  should  delegate  all  of  them. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Sources  for  Graphics  Exporter  Input  Images" 
( V-  2887) 

See  Also 

For  the  corresponding  get  function,  see  Graphi  csExportGetlnputFi  1  e  (1-565).  The 
following  other  functions  let  you  get  the  sources  for  input  images: 

Graphi  cs  Expo  rtGet  In  put  Data  Reference  (1-563),  Graphi  csExportGetlnputHandl  e 
(1-568),  Graphi csExportGetlnputPtr  (1-574), 

Graphi  csExportGetlnputGraphi  cslmporter  (1-566),  Graphi  csExportGetlnputPi  cture 
(1-572),  Graphi  cs  Expo  rtGet  InputGWorl  d  (1-567),  and  Graphi  csExportGetlnputPi  xmap 
(1-573). 

GraphicsExportSetlnputGraphicsImporter 

Specifies  that  the  source  image  for  a  graphics  export  operation  is  to  be  drawn  by  a 
graphics  importer  instance. 

ComponentResul t  GraphicsExportSetlnputGraphicsImporter  ( 

Graphi csExportComponent  ci , 

Graphi cs ImportComponent  grip  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

gri  p 

The  source  graphics  importer  component  instance. 


Inside  QuickTime:  Functions  A-H 
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GraphicsExportSetlnputGWorld 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  can  use  this  function  to  specify  a  source  before  you  call  Graph  i  cs  Export  Do  Export 
(1-554).  The  source  can  be  a  QuickTime  graphics  importer  component  instance,  a 
QuickDraw  Pi  cture,  a  graphics  world,  a  PixMap  (IV-2332)  structure,  or  a  piece  of 
compressed  data  described  by  an  ImageDescri  pti  on  (IV-2285)  structure. 
Compressed  data  can  be  in  a  file,  handle,  pointer,  or  other  data  reference.  The 
application  must  make  sure  that  the  source  is  not  disposed  of  before  the  graphics 
exporter  instance  is  closed  or  given  a  new  source.  All  of  the  get  and  set  functions  for 
these  sources  are  implemented  by  the  base  graphics  exporter;  format-specific 
importers  should  delegate  all  of  them. 

Special  Considerations 

It  is  the  caller's  responsibility  to  dispose  of  the  graphics  importer. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Sources  for  Graphics  Exporter  Input  Images" 
( V-  2887) 

See  Also 

For  the  corresponding  get  function,  see  Graphi  csExportGetlnputGraphi  cslmporter 
(1-566).  The  following  other  functions  let  you  get  the  sources  for  input  images: 
Graphi  cs  Expo  rtGet  Input  Data  Reference  (1-563),  Graphi  csExportGetlnputFi  1  e  (1-565), 
Graphi  csExportGetlnputHandl  e  (1-568),  Graphi  csExportGetlnputPtr  (1-574), 

Graphi  cs  Expo  rtGet  Input  Pi  cture  (1-572),  Graphi  cs  Expo  r  t  Get  Input  GWorl  d  (1-567),  and 
Graphi  cs  Expo  rtGet  Input  Pi  xmap  (1-573). 


GraphicsExportSetlnputGWorld 


Specifies  that  the  source  image  for  a  graphics  export  operation  is  a  graphics  world. 

ComponentResul t  GraphicsExportSetlnputGWorld  ( 

Graphi csExportComponent  ci  , 

GWorl dPtr  gworl d  ) ; 


The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 
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GraphicsExportSetlnputHandle 


gworl  d 

The  source  graphics  world.  It  must  be  a  real  graphics  world;  you  may  not  pass 
an  ordinary  color  GrafPort. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  can  use  this  function  to  specify  a  source  before  you  call  Graph  i  c  s  E x p  o  r  t  D  o  E x p  o  r  t 
(1-554).  The  source  can  be  a  QuickTime  graphics  importer  component  instance,  a 
QuickDraw  Pi  cture,  a  graphics  world,  a  Pi  xMap  (IV-2332)  structure,  or  a  piece  of 
compressed  data  described  by  an  ImageDescri  pti  on  (IV-2285)  structure. 
Compressed  data  can  be  in  a  file,  handle,  pointer,  or  other  data  reference.  The 
application  must  make  sure  that  the  source  is  not  disposed  of  before  the  graphics 
exporter  instance  is  closed  or  given  a  new  source.  All  of  the  get  and  set  functions  for 
these  sources  are  implemented  by  the  base  graphics  exporter;  format-specific 
importers  should  delegate  all  of  them. 

Special  Considerations 

The  graphics  exporter  will  never  dispose  the  graphics  world. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Sources  for  Graphics  Exporter  Input  Images" 
(V-  2887) 

See  Also 

For  the  corresponding  get  function,  see  Graphi  csExportGetlnputGWorl  d  (1-567).  The 
following  other  functions  let  you  get  the  sources  for  input  images: 

Graphi  cs  Expo  rtGet  In  put  Data  Reference  (1-563),  Graphi  csExportGetlnputFi  1  e  (1-565), 
Graphi  csExportGetlnputHandl  e  (1-568),  Graphi  csExportGetlnputPtr  (1-574), 

Graphi  csExportGetlnputGraphi  cslmporter  (1-566),  Graphi  csExportGetlnputPi  cture 
(1-572),  and  Graphi  csExportGetlnputPixmap  (1-573). 


GraphicsExportSetlnputHandle 


Specifies  that  the  source  image  for  a  graphics  export  operation  is  a  compressed 
image  referenced  by  a  handle. 

ComponentResul t  GraphicsExportSetlnputHandle  ( 

Graphi csExportComponent  ci  , 

Handle  h, 

ImageDescri pti onHandl e  desc  ); 
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GraphicsExportSetlnputOffsetAndLimit 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component, 
h 

A  handle  to  graphics  data. 

desc 

A  handle  to  an  ImageDescri  pti  on  (IV-2285)  structure  that  describes  the 
compressed  data. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  can  use  this  function  to  specify  a  source  before  you  call  Graph  i  cs  Export  Do  Export 
(1-554).  The  source  can  be  a  QuickTime  graphics  importer  component  instance,  a 
QuickDraw  Pi  cture,  a  graphics  world,  a  Pi  xMap  (IV-2332)  structure,  or  a  piece  of 
compressed  data  described  by  an  ImageDescri  pti  on  (IV-2285)  structure. 
Compressed  data  can  be  in  a  file,  handle,  pointer,  or  other  data  reference.  The 
application  must  make  sure  that  the  source  is  not  disposed  of  before  the  graphics 
exporter  instance  is  closed  or  given  a  new  source.  All  of  the  get  and  set  functions  for 
these  sources  are  implemented  by  the  base  graphics  exporter;  format-specific 
importers  should  delegate  all  of  them. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Sources  for  Graphics  Exporter  Input  Images" 
(V-2887) 

See  Also 

For  the  corresponding  get  function,  see  Graphi  csExportGetlnputHandl  e  (1-568).  The 
following  other  functions  let  you  get  the  sources  for  input  images: 

Graphi  cs  Expo  rtGet  Input  Data  Reference  (1-563),  Graphi  csExportGetlnputFi  1  e  (1-565), 
Graphi  cs  Expo  rtGet  I  nputPtr  (1-574),  Graphi  csExportGetlnputGraphi  cs  Importer 
(1-566),  Graphi  csExportGetlnputPi  cture  (1-572),  Graphi  csExportGetlnputGWorl  d 
(1-567),  and  Graphi  csExportGetlnputPi  xmap  (1-573). 


GraphicsExportSetlnputOffsetAndLimit 

Specifies  the  portion  of  an  input  data  reference,  file,  handle  or  pointer  that  a 
graphics  exporter  is  permitted  to  read. 
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G  raphics  Exports  etlnputPicture 


ComponentResul t  Graphi csExportSetlnputOf f setAndLimi t  ( 
Graphi csExportComponent  ci  , 

unsigned  long  offset, 

unsigned  long  limit  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

offset 

The  byte  offset  of  the  input  image  data  from  the  beginning  of  the  data  reference. 
1  i  mi  t 

The  offset  of  the  byte  following  the  last  byte  of  the  input  image  data.  (If  you 
don't  need  to  apply  any  limit,  pass  (unsigned  1  ong)-l.)  Both  the  offset 
parameter  and  the  limit  parameter  values  are  relative  to  the  start  of  the 
compressed  data.  Graphi csExportGetlnputDataSi ze  (1-564)  and 
Graphi  csExportReadlnputData  (1-586)  take  the  offset  and  limit  values  into 
account  automatically. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  routine  would  be  useful  if,  for  example,  the  source  was  a  JPEG  image 
embedded  within  a  larger  file. 

Special  Considerations 

This  function  is  only  applicable  when  the  input  is  a  data  reference,  file,  handle,  or 
pointer. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Restricting  the  Range  of  an  Input  Image's  Source" 

(V- 2888) 

See  Also 

For  the  corresponding  get  function,  see  Graphi  csExportGetlnputOffsetAndLi  mi  t 
(1-572). 

GraphicsExportSetlnputPicture 

Specifies  that  the  source  image  for  a  graphics  export  operation  is  a  picture. 
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GraphicsExportSetlnputPixmap 


ComponentResul t  Graphi csExportSetlnputPi cture  ( 
Graphi csExportComponent  ci  , 

Pi cHandl e  pi cture  ) ; 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component, 
pi cture 

A  handle  to  the  source  picture. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  can  use  this  function  to  specify  a  source  before  you  call  Graphi  cs  Export  Do  Export 
(1-554).  The  source  can  be  a  QuickTime  graphics  importer  component  instance,  a 
QuickDraw  Pi  cture,  a  graphics  world,  a  Pi  xMap  (IV-2332)  structure,  or  a  piece  of 
compressed  data  described  by  an  ImageDescri  pti  on  (IV-2285)  structure. 
Compressed  data  can  be  in  a  file,  handle,  pointer,  or  other  data  reference.  The 
application  must  make  sure  that  the  source  is  not  disposed  of  before  the  graphics 
exporter  instance  is  closed  or  given  a  new  source.  All  of  the  get  and  set  functions  for 
these  sources  are  implemented  by  the  base  graphics  exporter;  format-specific 
importers  should  delegate  all  of  them. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Sources  for  Graphics  Exporter  Input  Images" 
(V-2887) 

See  Also 

For  the  corresponding  get  function,  see  Graphi  cs  Export  Get  Input  Pi  cture  (1-572).  The 
following  other  functions  let  you  get  the  sources  for  input  images: 

Graphi  cs  Expo  rtGet  Input  Data  Reference  (1-563),  Graphi  csExportGetlnputFi  1  e  (1-565), 
Graphi  csExportGetlnputHandl  e  (1-568),  Graphi  csExportGetlnputPtr  (1-574), 

Graphi  cs  Expo  rtGet  I  nputGraphi  cslmporter  (1-566),  Graphi  cs  Expo  rtGet  I  nputGWorl  d 
(1-567),  and  Graphi csExportGetlnputPi xmap  (1-573). 


GraphicsExportSetlnputPixmap 

Specifies  that  the  source  image  for  a  graphics  export  operation  is  a  pi  xmap. 
ComponentResul t  GraphicsExportSetlnputPixmap  ( 
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GraphicsExportSetlnputPixmap 


Graphi csExportComponent  ci  , 

PixMapHandle  pixmap  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component, 
pi xmap 

The  source  PixMap  (IV-2332)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  can  use  this  function  to  specify  a  source  before  you  call  Graphi  c  s  E x  p  o  r  t  D  o  E x  p  o  r  t 
(1-554).  The  source  can  be  a  QuickTime  graphics  importer  component  instance,  a 
QuickDraw  Pi  cture,  a  graphics  world,  a  Pi  xMap  (IV-2332)  structure,  or  a  piece  of 
compressed  data  described  by  an  ImageDescri  pti  on  (IV-2285)  structure. 
Compressed  data  can  be  in  a  file,  handle,  pointer,  or  other  data  reference.  The 
application  must  make  sure  that  the  source  is  not  disposed  of  before  the  graphics 
exporter  instance  is  closed  or  given  a  new  source.  All  of  the  get  and  set  functions  for 
these  sources  are  implemented  by  the  base  graphics  exporter;  format-specific 
importers  should  delegate  all  of  them. 

Special  Considerations 

It  is  the  caller's  responsibility  to  dispose  of  the  pi  xmap. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Sources  for  Graphics  Exporter  Input  Images" 
(V-  2887) 

See  Also 

For  the  corresponding  get  function,  see  Graphi  csExportGetlnputPixmap  (1-573).  The 
following  other  functions  let  you  get  the  sources  for  input  images: 

Graphi  cs  Expo  rtGet  In  put  Data  Reference  (1-563),  Graphi  csExportGetlnputFi  1  e  (1-565), 
Graphi  csExportGetlnputHandl  e  (1-568),  Graphi  csExportGetlnputPtr  (1-574), 

Graphi  csExportGetlnputGraphi  cslmporter  (1-566),  Graphi  csExportGetlnputPi  cture 
(1-572),  and  Graphi  csExportGetlnputGWorl  d  (1-567). 
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GraphicsExportSetlnputPtr 


GraphicsExportSetlnputPtr 


Specifies  that  the  source  image  for  a  graphics  export  operation  is  a  compressed 
image  stored  at  a  fixed  address  in  memory. 

ComponentResul t  GraphicsExportSetlnputPtr  ( 


Graphi csExportComponent  ci  , 

Ptr  p , 

unsigned  long  size, 

ImageDescri pti onHandl e  desc  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

P 

A  pointer  to  a  value  the  image. 

si  ze 

A  value  describing  the  size  of  the  image  data  in  bytes. 

desc 

A  handle  to  an  ImageDescri  pti  on  (IV-2285)  structure  that  describes  the 
compressed  data. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  can  use  this  function  to  specify  a  source  before  you  call  Graphi  cs  Export  Do  Export 
(1-554).  The  source  can  be  a  QuickTime  graphics  importer  component  instance,  a 
QuickDraw  Pi  cture,  a  graphics  world,  a  Pi  xMap  (IV-2332)  structure,  or  a  piece  of 
compressed  data  described  by  an  ImageDescri  pti  on  (IV-2285)  structure. 
Compressed  data  can  be  in  a  file,  handle,  pointer,  or  other  data  reference.  The 
application  must  make  sure  that  the  source  is  not  disposed  of  before  the  graphics 
exporter  instance  is  closed  or  given  a  new  source.  All  of  the  get  and  set  functions  for 
these  sources  are  implemented  by  the  base  graphics  exporter;  format-specific 
importers  should  delegate  all  of  them. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Sources  for  Graphics  Exporter  Input  Images" 
(V-2887) 
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GraphicsExportSetlnterlaceStyle 


See  Also 

For  the  corresponding  get  function,  see  Graphi  csExportGetlnputPtr  (1-574).  The 
following  other  functions  let  you  get  the  sources  for  input  images: 

Graphi  cs  Expo  rtGet  In  put  Data  Reference  (1-563),  Graphi  csExportGetlnputFi  1  e  (1-565), 
Graphi  cs  Expo  rtGet  InputHandl  e  (1-568),  Graphi  cs  Expo  rtGet  InputGraphi  cs  Importer 
(1-566),  Graphi  csExportGetlnputPi  cture  (1-572),  Graphi  csExportGetlnputGWorl  d 
(1-567),  and  Graphi  csExportGetlnputPixmap  (1-573). 


GraphicsExportSetlnterlaceStyle 


Defines  the  interlace  style  for  a  graphics  export  operation. 

ComponentResul t  Graphi csExportSetlnterl aceStyl e  ( 
Graphi csExportComponent  ci  , 

unsigned  long  i nterl aceStyl e  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component, 
i nterl aceStyl e 

The  new  interlace  style  to  use.  Valid  values  and  interpretations  are  defined  by 
individual  exporters.  In  QuickTime  4,  the  PNG  graphics  exporter  supports  the 
i  nterl  aceStyl  e  settings  shown  below. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

interlaceStyle  Constants 

kQTPNGInterl aceNone 

No  interlace.  Value  is  0. 
kQTPNGInterl aceAdam7 

Uses  the  2D  Adam7  algorithm.  Value  is  1. 

Discussion 

A  common  use  for  this  function  is  in  the  PNG  and  GIF  formats,  which  rearrange 
data  so  that  low-resolution  images  can  be  displayed  from  incomplete  data  streams. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  Graphics  Exporter  Settings"  (V-2885) 
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GraphicsExportSetMetaData 


See  Also 

For  the  corresponding  get  function,  see  Graphi  csExportGetlnterl  aceStyl  e  (1-575). 


GraphicsExportSetMetaData 


Defines  supplemental  data  for  a  graphics  export  operation,  such  as  copyright  text. 

ComponentResul t  GraphicsExportSetMetaData  ( 

Graphi csExportComponent  ci  , 

voi d  *userData  ) ; 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 
userData 

A  pointer  to  user  data.  The  value  you  pass  should  have  the  type  userData, 
which  is  a  pointer  to  a  UserData  Record  (IV-2496). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

In  QuickTime  4,  none  of  the  supplied  graphics  exporters  support  setting  user  data. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  Graphics  Exporter  Settings"  (V-2885) 

See  Also 

For  the  corresponding  get  function,  see  Graphi  csExportGetMetaData  (1-576). 


GraphicsExportSetOutputDataReference 


Returns  the  current  output  data  reference  for  a  graphics  export  operation. 

ComponentResul t  Graphi csExportSetOutputDataReference  ( 

Graphi csExportComponent  ci  , 

Handle  dataRef, 

OSType  dataRefType  ); 
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GraphicsExportSetOutputFile 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 
dataRef 

A  QuickTime  data  reference. 
dataRefType 

The  type  of  the  data  reference;  see  "Data  References"  (IV-2661). 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Destinations  for  Output  Images"  (V-2890) 

See  Also 

For  the  corresponding  get  function,  see  Graphi csExportGetOutputDataReference 
(1-578). 

GraphicsExportSetOutputFile 

Defines  the  output  file  for  a  graphics  export  operation. 

ComponentResul t  GraphicsExportSetOutputFile  ( 

Graphi csExportComponent  ci , 

const  FSSpec  *theFile  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 
theFi 1 e 

an  FSSpec  (IV-2262)  structure  that  identifies  the  file. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Destinations  for  Output  Images"  (V-2890) 


Inside  QuickTime:  Functions  A-H 
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GraphicsExportSetOutputFileTypeAndCreator 


See  Also 

For  the  corresponding  get  function,  see  Graphi  csExportGetOutputFi  1  e  (1-578). 


GraphicsExportSetOutputFileTypeAndCreator 


Sets  the  file  type  and  creator  codes  for  the  output  file  of  a  graphics  export  operation. 

ComponentResul t  Graphi csExportSetOutputFi 1 eTypeAndCreator  ( 

Graphi csExportComponent  ci  , 

OSType  fileType, 

OSType  fileCreator  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

f  i  1 eType 

The  file  type  for  the  new  image  file,  such  as  'JPEG'.  See  "File  Types  and 
Creators"  (IV-2668). 

f  i  1 eCreator 

The  file  creator  for  the  new  image  file.  This  parameter  may  be  0,  in  which  case 
a  default  file  creator  for  this  file  type  is  used.  See  "File  Types  and  Creators" 
(IV-2668). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Destinations  for  Output  Images"  (V-2890) 

See  Also 

For  the  corresponding  get  function,  see 

Graphi  csExportGetOutputFi  1  eTypeAndCreator  (1-579). 


GraphicsExportSetOutputHandle 


Sets  a  handle  to  the  output  of  a  graphics  export  operation. 

ComponentResul t  GraphicsExportSetOutputHandle  ( 

Graphi csExportComponent  ci  , 
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GraphicsExportSetOutputMark 


Handle  h  ); 

ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

h 

The  output  handle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Destinations  for  Output  Images"  (V-2890) 

See  Also 

For  the  corresponding  get  function,  see  Graphi  csExportGetOutputHandl  e  (1-580). 


GraphicsExportSetOutputMark 


Seeks  to  the  specified  file  position  in  a  graphics  export  operation. 

ComponentResul t  GraphicsExportSetOutputMark  ( 

Graphi csExportComponent  ci  , 

unsigned  long  mark  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

mark 

The  new  file  position,  specified  as  a  byte  offset  from  the  beginning  of  the  output 
data  reference. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Writing  Graphics  Exporter  Output  Data"  (V-2891) 


Inside  QuickTime:  Functions  A-H 
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GraphicsExportSetOutputOffsetAndMaxSize 


See  Also 

For  the  corresponding  get  function,  see  Graphi  csExportGetOutputMark  (1-580). 


GraphicsExportSetOutputOffsetAndMaxSize 


Specifies  the  output  starting  offset  and  maximum  size  limit  for  a  graphics  export 
operation. 

ComponentResult  Graphi csExportSetOutputOffsetAndMaxSi ze  ( 

Graphi csExportComponent  ci  , 
unsigned  long  offset, 

unsigned  long  maxSize, 

Boolean  truncateFile  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

offset 

The  byte  offset  of  the  image  data  from  the  beginning  of  the  data  reference. 
maxSi ze 

A  value  describing  the  maximum  size  limit. 
truncateFi 1 e 

A  Boolean  value;  TRUE  means  to  truncate  the  file. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  Destinations  for  Output  Images"  (V-2890) 

See  Also 

For  the  corresponding  get  function,  see  Graphi csExportGetOutputOffsetAndMaxSi  ze 
(1-581). 

GraphicsExportSetProgressProc 

Installs  a  progress  function  in  a  graphics  export  operation. 

ComponentResult  GraphicsExportSetProgressProc  ( 
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GraphicsExportSetResolution 


Graphi csExportComponent  ci  , 

ICMProgressProcRecordPtr  progressProc  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 
progressProc 

Points  to  an  ICMProgressProc  (III— 2093)  callback.  If  you  passavalue  of-1, 
QuickTime  provides  a  standard  progress  function.  If  you  want  to  remove  the 
existing  progress  function,  pass  N I L. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  always  implemented  by  the  base  graphics  exporter. 

Special  Considerations 

If  your  progress  function  does  any  drawing,  you  should  take  care  to  set  a  safe 
graphics  state  before  doing  so,  and  to  restore  the  graphics  state  afterwards.  In 
particular,  the  current  graphics  device  may  be  an  offscreen  device. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Getting  and  Setting  Progress  Procs"  (V-2887) 

See  Also 

For  the  corresponding  get  function,  see  Graphi  csExportGetProgressProc  (1-582). 


GraphicsExportSetResolution 


Defines  the  resolution  to  store  in  the  image  file  for  a  graphics  export  operation. 

ComponentResul t  GraphicsExportSetResolution  ( 

Graphi csExportComponent  ci  , 

Fixed  hori zontal Resol uti on , 

Fixed  verti cal  Resol uti on  ); 


The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 
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GraphicsExportSetSettingsFromAtomContainer 


horizontal  Resolution 

A  value  describing  the  horizontal  resolution  of  the  image,  where  the  upper  byte 
is  dots  per  inch.  The  value  0x00480000  represents  72.0  dpi. 
verti cal  Resol uti on 

A  value  describing  the  vertical  resolution  of  the  image,  where  the  upper  byte  is 
dots  per  inch.  The  value  0x00480000  represents  72.0  dpi. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  Graphics  Exporter  Settings"  (V-2885) 

See  Also 

For  the  corresponding  get  function,  see  Graphi  csExportGetResol  uti  on  (1-583). 


GraphicsExportSetSettingsFromAtomContainer 


Sets  the  graphics  exporter  component's  current  configuration  to  match  the  settings 
in  a  passed  atom  container. 

ComponentResul t  Graphi csExportSetSettingsFromAtomContainer  ( 

Graphi csExportComponent  ci  , 

void  *qtAtomContai ner  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

qtAtomContai ner 

A  pointer  to  a  QuickTime  atom  container  that  contains  settings. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  settings  atom  container  may  contain  atoms  other  than  those  expected  by  the 
graphics  exporter  component  or  may  be  missing  certain  atoms.  This  function  will 
use  only  the  settings  it  understands. 

Version  Notes 

Introduced  in  QuickTime  4. 
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GraphicsExportSetTargetDataSize 


Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Obtaining  Graphics  Exporter  Settings"  (V-2885) 


GraphicsExportSetT  argetDataSize 


Defines  a  desired  maximum  data  size  for  a  graphics  export  operation  and  asks  for 
a  quality  that  does  not  exceed  that  size. 

ComponentResul t  Graphi csExportSetTargetDataSize  ( 

Graphi csExportComponent  ci  , 

unsigned  long  targetDataSi ze  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 
targetDataSi ze 

A  value  that  describes  the  maximum  size  of  the  image  data  in  bytes. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Accessing  Graphics  Exporter  Settings"  (V-2885) 


GraphicsExportW  riteOutputData 


Writes  output  image  data  in  a  graphics  export  operation. 

ComponentResul t  Graphi csExportWri teOutputData  ( 
Graphi csExportComponent  ci  , 

const  void  *dataPtr, 

unsigned  long  dataSize  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
exporter  component. 

dataPtr 

A  pointer  to  a  memory  block  containing  the  data. 


Inside  QuickTime:  Functions  A-H 
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GraphicsImagelmportGetSequenceEnabled 


dataSi ze 

The  number  of  bytes  of  image  data  to  write. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  used  by  format-specific  graphics  exporters  to  write  output  data. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Writing  Graphics  Exporter  Output  Data"  (V-2891) 


GraphicsImagelmportGetSequenceEnabled 


Undocumented 

ComponentResul t  Graphi csImagelmportGetSequenceEnabl ed  ( 
Graphi clmageMovi elmportComponent  ci  , 

Bool ean  *enabl e  ) ; 


ci 

The  component  instance  that  identifies  your  connection  to  the  movie  importer 
component. 

enabl e 

A  pointer  to  a  Bool  ean  that  returns  TRUE  if  enabled,  FALSE  otherwise. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

See  Also 

For  the  corresponding  set  function,  see  Graphi  csImagelmportSetSequenceEnabl  ed 
(1-612). 

GraphicsImagelmportSetSequenceEnabled 

Undocumented 
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GraphicsImportDoesDrawAllPixels 


ComponentResul t  Graphi cs ImagelmportSetSequenceEnabl ed  ( 
Graphi clmageMovi elmportComponent  ci  , 

Boolean  enable  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  movie  importer 
component, 
enabl e 

Pass  TRUE  to  enable,  FALSE  to  disable. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

See  Also 

For  the  corresponding  get  function,  see  Graphi  csImagelmportGetSequenceEnabl  ed 
(1-612). 

GraphicsImportDoesDrawAllPixels 

Asks  whether  the  graphics  importer  expects  to  draw  every  pixel. 

ComponentResul t  Graphi cs ImportDoesDrawAl 1  Pixel s  ( 

Graphi cs ImportComponent  ci , 

short  *drawsAl 1  Pixel s  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

drawsAl 1  Pi xel s 

A  pointer  to  a  value  (see  below)  that  describes  the  predicted  drawing  behavior. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

drawsAIIPixels  Constants 

graphi cs ImporterDrawsAl 1  Pixel s 

Every  pixel  in  the  boundary  rectangle  will  be  drawn.  Value  is  0. 
graphi cs ImporterDoesntDrawAl 1  Pixel s 

Some  pixels  in  the  boundary  rectangle  will  not  be  drawn.  Value  is  1. 
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GraphicsImportDoExportlmageFileDialog 


graph i cs Importer Don tKnowlfDrawAl  1  Pixels 

The  graphics  importer  cannot  determine  whether  all  pixels  will  be  drawn. 
Value  is  2. 

Discussion 

Some  image  file  formats  permit  non-rectangular  images  or  images  with  transparent 
regions.  When  such  an  image  is  drawn,  not  every  pixel  in  the  boundary  rectangle 
will  be  changed.  Graph  i  cs  Import  Does  DrawAl  1  Pi  xel  s  lets  you  try  to  find  out  whether 
this  will  be  the  case.  For  instance,  you  might  choose  to  erase  the  area  behind  the 
image  before  drawing.  If  the  graphics  import  component  supports  this  function, 
drawsAl  1  Pi  xel  s  will  contain  one  of  the  constants  shown  above  on  return. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Getting  Image  Characteristics"  (V-2878) 

Related  Java  Methods 

qu i c kti me. std. image. Graph icslmporter. does DrawAl 1  Pi xel s ( ) 


See  Also 

Format-specific  graphics  importers  always  implement 
Graphi  csImportGetlmageDescri  pti  on  (1-638)  and  may  optionally  implement 
GraphicsImportGetNatural  Bounds  (1-642),  Graphi  csImportGetDataOffsetAndSi  ze 
(1-624),  Graphi  csImportVal  i  date  (1-665),  and  Graphi  csImportGetMetaData  (1-640),  as 
well  as  Graphi  cs  Import  Does  DrawAl  1  Pixel  s. 


GraphicsImportDoExportlmageFileDialog 


Presents  a  dialog  box  letting  the  user  save  an  imported  image  in  a  foreign  file 
format. 


ComponentResul t  Graphi csImportDoExportlmageFi 1 eDial og  ( 
Graphi csImportComponent  ci  , 
const  FSSpec 
Stri ngPtr 


Modal FilterYDUPP 

OSType 

FSSpec 

Seri ptCode 


*i nDefaul tSpec , 
prompt , 
f i 1 terProc , 
*outExportedType , 
*outExportedSpec , 
*outScri ptTag  ) ; 
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ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component, 
i nDef aul tSpec 

A  pointer  to  an  FSSpec  (IV-2262)  that  suggests  a  default  name  for  the  file.  If  you 
don't  want  to  suggest  a  default  name,  pass  N I L. 

prompt 

A  pointer  to  a  prompt  string  that  appears  in  the  standard  put  dialog  box;  it  may 
be  NIL,  in  which  case  a  default  string  is  used, 
f i 1 terProc 

A  modal  filter  function  to  be  passed  to  the  Mac  OS  function  CustomPutFi  1  e;  see 
Inside  Macintosh:  Files  (listed  in  the  bibliography)  for  more  information.  If  you 
don't  need  to  filter  events,  pass  NIL. 
outExportedType 

A  pointer  to  a  variable  that  will  receive  the  type  of  the  export  file  that  was 
chosen  by  the  user.  If  you  don't  want  this  information,  pass  N I L.  See  "File  Types 
and  Creators"  (IV-2668). 

outExportedSpec 

A  pointer  to  a  variable  that  will  receive  the  FSSpec  (IV-2262)  of  the  file  that  was 
written.  If  you  don't  want  this  information,  pass  NIL. 
outScri ptTag 

A  pointer  to  a  variable  that  will  receive  the  script  system  in  which  the  exported 
file  name  is  to  be  displayed.  See  "Localization  Codes"  (IV-2673).  If  you  don't 
want  this  information,  pass  N I L. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  presents  the  user  with  an  extended  Standard  File  dialog  box  that 
allows  the  image  currently  in  use  by  the  graphics  import  component  to  be  exported 
to  a  file,  in  a  format  of  the  user's  choice. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Saving  Image  Files"  (V-2881) 

Related  Java  Methods 

qui  cktime .  i  o .  QTFi  1  e . f romGraphi cs Importer! ) , 

qui ckti me . std . image . Graph i cs Importer . d o Export  I mageFi 1 eDi al og ( ) 


Inside  QuickTime:  Functions  A-H 
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GraphicsImportDraw 


GraphicsImportDraw 

Draws  an  imported  image. 

ComponentResul t  GraphicsImportDraw  ( 
Graphi csImportComponent  ci  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  draws  the  image  currently  in  use  by  the  graphics  import  component 
to  the  graphics  port  and  device  specified  by  Graphi  cs  ImportSetGWorl  d  (1-660). 
GraphicsImportDraw  takes  into  account  all  settings  previously  specified  for  the 
image,  such  as  the  source  rectangle,  transformation  matrix,  clipping  region, 
graphics  mode,  and  image  quality. 

Special  Considerations 

The  base  graphics  importer's  drawing  function  uses  the  results  of 
Graphi  csImportGetlmageDescri  pti  on  (1-638)  and 

Graphi  csImportGetDataOffsetAndSi  ze  (1-624)  to  create  a  decompression  sequence, 
which  it  uses  to  draw  the  image.  Subsequent  draw  operations  with  the  same 
connection  may  reuse  the  decompression  sequence.  Other  graphics  importers  may 
override  this  behavior. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Drawing  Imported  Images"  (V-2880) 

Related  Java  Methods 

qui ckti me. std . image. Graphi cs Importer ,draw( ) 


GraphicsImportExportlmageFile 


Saves  an  imported  image  in  a  foreign  file  format. 

ComponentResul t  GraphicsImportExportlmageFile  ( 
GraphicsImportComponent  ci  , 

OSType  fileType, 
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OSType 

const  FSSpec 
Seri ptCode 


f i 1 eCreator , 
*f  ss , 

scriptTag  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component, 
f i 1 eType 

The  file  type  for  the  new  image  file,  such  as  'JPEG'.  See  "File  Types  and 
Creators"  (IV-2668). 

f i 1 eCreator 

The  file  creator  for  the  new  image  file.  See  "File  Types  and  Creators"  (IV-2668). 
You  may  pass  0,  in  which  case  a  default  file  creator  for  this  file  type  is  used. 

f  ss 

A  pointer  to  the  FSSpec  (IV-2262)  structure  that  identifies  the  file  that  is  to 
receive  the  exported  image, 
scri ptTag 

The  script  system  in  which  the  file  name  is  to  be  displayed;  see  "Localization 
Codes"  (IV-2673).  If  you  have  established  the  name  and  location  of  the  file 
using  one  of  the  Standard  File  Package  functions,  use  the  script  code  returned 
in  the  reply  record  (reply .  sf Scri  pt).  Otherwise,  specify  the  system  script  by 
setting  the  scri  ptTag  parameter  to  the  value  smSystemScri  pt.  See  Inside 
Macintosh:  Files  (listed  in  the  bibliography)  for  more  information  about  script 
specifications. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  creates  a  new  file  containing  the  image  currently  in  use  by  the 
graphics  import  component.  The  new  file  is  compressed  in  a  format  corresponding 
to  the  provided  file  type.  If  a  non-identity  matrix  has  been  applied  to  the  graphics 
import  component,  this  matrix  is  applied  to  the  image  before  export.  Since  most 
image  formats  don't  support  nonzero  top-left  coordinates,  the  matrix  is  temporarily 
adjusted  to  ensure  that  the  exported  image's  bounds  have  top-left  coordinates  at 
(0,0).  If  the  matrix  does  not  map  the  graphics  import  component's  source  rectangle 
to  a  rectangle,  there  will  be  extra  white  space  left  around  the  image. 

Special  Considerations 

Graphics  import  components  can  save  data  in  several  formats,  including 
QuickDraw  pictures  and  QuickTime  Image  files.  This  capability  is  only  needed  by 
applications  that  perform  file  format  translation.  Applications  that  only  wish  to 
draw  the  image  can  use  Graphi  csImportDraw  (1-616). 
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GraphicsImportGetAliasedDataReference 


Version  Notes 

In  QuickTime  3,  the  supported  export  file  types  are  kQTFi  1  eTypePi  cture, 
kQTFi  1  eTypeQui  ckTi  me  Image,  kQTFi  1  eTypeBMP,  kQTFi  1  eTypeJPEG,  and 
kQTFi  1  eTypePhotoShop.  QuickTime  4  uses  graphics  exporter  components  to 
implement  image  export. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Saving  Image  Files"  (V-2881) 

Related  Java  Methods 

quicktime.std.image.GraphicsImporter. export  Image Fi  1  e( ) 


GraphicsImportGetAliasedDataReference 


Deprecated. 

ComponentResul t  GraphicsImportGetAl i asedDataReference  ( 
GraphicsImportComponent  ci  , 

Handle  *dataRef, 

OSType  *dataRefType  ); 


Version  Notes 

This  function  is  listed  for  historical  purposes  only.  It  may  be  unsupported  or 
removed  in  future  versions  of  QuickTime. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


GraphicsImportGetAsPicture 


Creates  a  QuickDraw  picture  handle  to  an  imported  image. 

ComponentResul t  GraphicsImportGetAsPicture  ( 
GraphicsImportComponent  ci  , 

PicHandle  *picture  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component, 
pi cture 

Points  to  a  handle  to  a  Pi  cture  (IV-2331)  structure  that  is  to  receive  the  image. 
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GraphicsImportGetBoundsRect 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  creates  a  new  QuickDraw  picture  handle  containing  the  image 
currently  in  use  by  the  graphics  import  component.  If  possible,  the  image  will 
remain  in  the  compressed  format.  For  example,  if  the  image  is  from  a  JFIF  file,  the 
picture  will  contain  compressed  JPEG  data.  It  is  the  responsibility  of  the  caller  to 
dispose  of  the  picture  handle. 

Special  Considerations 

Graphics  import  components  can  save  data  in  several  formats,  including 
QuickDraw  pictures  and  QuickTime  Image  files.  This  capability  is  only  needed  by 
applications  that  perform  file  format  translation.  Applications  that  only  wish  to 
draw  the  image  can  use  Graphi  csImportDraw  (1-616). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Saving  Image  Files"  (V-2881) 

Related  Java  Methods 

qui cktime . qd . Pi ct . f romGraphi cs Importer ( ) , 

qui ckti me . std . image . Graphi cs Importer . get As  Pi cturel ) 


GraphicsImportGetBoundsRect 


Returns  the  bounding  rectangle  for  drawing  an  imported  image. 

ComponentResul t  GraphicsImportGetBoundsRect  ( 

Graphi cs ImportComponent  ci  , 

Rect  *bounds  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

bounds 

A  pointer  to  a  Rect  (IV-2399)  structure  describing  the  bounding  rectangle  that 
has  been  defined  for  the  image. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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GraphicsImportGetClip 


Discussion 

This  is  a  convenience  function.  It  is  implemented  by  calling 

Graphics  ImportGetMatrix  (1-639)  and  Graphi  cs  ImportGetNatural  Bounds  (1-642)  and 
using  the  results  to  calculate  the  drawing  rectangle. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Setting  Drawing  Parameters"  (V-2879) 

Related  Java  Methods 

qu i ckti me. std. image. Graph icsImporter.getBounds RectO 


See  Also 

For  the  corresponding  set  function,  see  Graphi  csImportSetBoundsRect  (1-649). 


GraphicsImportGetClip 


Returns  the  current  clipping  region  for  an  imported  image. 

ComponentResul t  GraphicsImportGetClip  ( 

Graphi csImportComponent  ci  , 

RgnHandl e  *cl i pRgn  ) ; 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

cl i pRgn 

A  handle  to  the  MacRegi  on  (IV-2303)  structure  that  has  been  defined  as  the 
clipping  region  for  the  image.  Returns  N I L  if  there  is  no  clipping  region. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  caller  must  dispose  of  the  returned  region  handle. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Setting  Drawing  Parameters"  (V-2879) 
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GraphicsImportGetColorSyncProfile 


Related  Java  Methods 

qui cktime . qd . Regi on . f romGraphi cs Importer ( ) , 
qui ckti me . std . image . Graphi cs Importer . getCl i p ( ) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  cs  ImportSetCl  i  p  (1-650). 


GraphicsImportGetColorSyncProfile 


Returns  a  ColorSync  profile  for  an  imported  image,  if  one  is  embedded  in  the  image 
file. 

ComponentResul t  Graphi cs ImportGetCol orSyncProfi 1 e  ( 

Graphi cs ImportComponent  ci  , 

Handle  *profile  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

prof  i  1  e 

A  pointer  to  receive  a  handle  containing  a  ColorSync  profile,  or  N I L  if  the  image 
file  does  not  contain  one. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Some  graphics  importers  don't  implement  this  function.  The  caller  is  responsible  for 
disposing  of  the  returned  handle. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Graphis  Importers"  (V-2876) 


GraphicsImportGetDataFile 


Returns  the  file  containing  the  graphics  data  for  an  imported  image. 

ComponentResul t  GraphicsImportGetDataFile  ( 

Graphi cs ImportComponent  ci  , 

FSSpec  *theFile  ); 


Inside  QuickTime:  Functions  A-H 


1-621 


GraphicsImportGetDataFile 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component, 
t  h  e  F  i  1  e 

A  pointer  in  which  to  return  the  FSSpec  (IV-2262)  structure  of  the  file  containing 
the  graphics  data. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error.  If  the 
data  source  is  not  a  file,  the  function  returns  paramErr. 

Discussion 

Use  this  function  to  get  the  file  system  specification  record  for  the  file  where  the 
imported  graphics  data  resides. 

Special  Considerations 

Graphics  importer  components  use  QuickTime  data  handler  components  to  obtain 
their  data.  Applications,  however,  will  use  graphics  importer  functions  rather  than 
directly  calling  a  data  handler.  Besides  GraphicsImportGetDataFile,  these  functions 
include  Graphi  csImportSetDataFi  1  e  (1-651),  Graphi  csImportSetDataHandl  e  (1-652), 
Graphi  csImportGetDataHandl  e  (1-623),  Graphi  csImportSetDataReference  (1-653), 
Graphi  csImportSetDataReferenceOffsetAndLi  mi  t  (1-654),  and 

Graphi  cs  Import  Get  Data  Ref  erenceOff  set  And  Li  mi  t  (1-627).  These  functions  allow  the 
data  source  to  be  a  file,  a  handle,  or  a  QuickTime  data  reference.  You  only  need  to 
use  these  functions  if  you  open  the  graphics  importer  component  directly.  You 
don't  need  to  call  them  if  you  use  one  of  the  GetGraphi  cs  Importer...  functions  such 
as  GetGraphi csImporterForDataRef  (1-412).  The  GetGraphi  cslmporter...  functions 
automatically  open  the  graphics  importer  component  and  set  its  data  source. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  a  Graphics  Import  Data  Source"  (V-2882) 

Related  Java  Methods 

qui ckti me . i o . QTFi 1 e . f romGraphi cs Importer! ) , 

qu i c kti me. std. image. Graphi cslmporter. get Da ta  File! ) 


See  Also 

For  the  corresponding  set  function,  see  Graphi  csImportSetDataFi  1  e  (1-651). 
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Inside  QuickTime:  Functions  A-H 


GraphicsImportGetDataHandle 


GraphicsImportGetDataHandle 


Returns  a  handle  to  imported  graphics  data. 

ComponentResul t  GraphicsImportGetDataHandle  ( 
Graphi cs ImportComponent  ci  , 

Handle  *h  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

h 

A  pointer  in  which  to  return  a  handle  to  the  graphics  data. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error.  If  the 
data  source  is  not  a  handle,  the  function  returns  paramErr. 

Discussion 

You  use  this  function  to  get  the  handle  that  the  graphics  data  resides  in.  The  handle 
belongs  to  the  component  instance.  You  shouldn't  dispose  of  it. 

Special  Considerations 

Graphics  importer  components  use  QuickTime  data  handler  components  to  obtain 
their  data.  Applications,  however,  will  use  graphics  importer  functions  rather  than 
directly  calling  a  data  handler.  Besides  Graphi  csImportGetDataHandl  e,  these 
functions  include  Graphi  csImportSetDataFi  1  e  (1-651),  Graphi  csImportSetDataHandl  e 
(1-652),  Graphi  cs  ImportGetDataFi  1  e  (1-621),  Graphi  cs  Import  Set  Data  Reference 
(1-653),  Graphi  cs  ImportSetDataReferenceOf  f  set  And  Li  mi  t  (1-654),  and 
Graphi  cs  ImportGetDataReferenceOf  f  set  And  Li  mi  t  (1-627).  These  functions  allow  the 
data  source  to  be  a  file,  a  handle,  or  a  QuickTime  data  reference.  You  only  need  to 
use  these  functions  if  you  open  the  graphics  importer  component  directly.  You 
don't  need  to  call  them  if  you  use  one  of  the  GetGraphicsImporter...  functions  such 
as  GetGraphi  cs  Importer  For  Data  Ref  (1-412).  The  GetGraphi  cs  Importer...  functions 
automatically  open  the  graphics  importer  component  and  set  its  data  source. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  a  Graphics  Import  Data  Source"  (V-2882) 

Related  Java  Methods 

qui ckti me . std . Image . Graph! cs Importer . getDataHandlel), 
qui cktime . uti 1 . QTHandl e . f romGraphi cs Importer Data ( ) 


Inside  QuickTime:  Functions  A-H 


1-623 


GraphicsImportGetDataOffsetAndSize 


See  Also 

For  the  corresponding  set  function,  see  Graphi  csImportSetDataHandl  e  (1-652). 


GraphicsImportGetDataOffsetAndSize 


Returns  the  offset  and  size  of  the  compressed  image  data  within  an  imported  image 
file. 

ComponentResul t  Graphi csImportGetDataOffsetAndSize  ( 

GraphicsImportComponent  ci  , 

unsigned  long  *offset, 

unsi gned  1 ong  *si ze  ) ; 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

offset 

A  pointer  to  a  value  describing  the  byte  offset  of  the  image  data  from  the 
beginning  of  the  data  source. 

si  ze 

A  pointer  to  a  value  describing  the  size  of  the  image  data  in  bytes. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns  the  offset  and  size  of  the  actual  image  data  within  the  data 
source.  By  default,  the  offset  returned  is  0  and  the  size  returned  is  the  size  of  the  file. 
Flowever,  some  graphics  import  components  will  override  this  function  to  skip 
over  unneeded  information  at  the  beginning  or  end  of  the  file. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Getting  Image  Characteristics"  (V-2878),  "Managing 
Graphis  Importers"  (V-2876) 

Related  Java  Methods 

quicktime.std.image.GraphicsIrriporter. getDataOffset ( ) , 
qu i c kt i me. std. image. Graph icslmporter. get Da taSizet) 


1-624 
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GraphicsImportGetDataOffsetAndSize64 


See  Also 

See  Graphi  csImportGetDataOffsetAndSi  ze64  (1-625).  Format-specific  graphics 
importers  always  implement  Graphi  cs  ImportGetlmageDescri  pti  on  (1-638)  and  may 
optionally  implement  the  Graphi  csImportGetNatural  Bounds  (1-642), 

Graphi  cs  ImportVal  i  date  (1-665),  Graphi  cs  Import  Get  Met  a  Data  (1-640),  and 
Graphi  cs  ImportDoesDrawAl  1  Pi xel  s  (1-613),  as  well  as 
Graphi CsImportGetDataOffsetAndSi ze. 


GraphicsImportGetDataOffsetAndSize64 


Provides  a  64-bit  version  of  Graphi  csImportGetDataOffsetAndSi  ze. 

ComponentResul t  Graphi cs ImportGetDataOf fsetAndSi ze64  ( 

Graphi cs ImportComponent  ci  , 

wide  *offset, 

wide  *size  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

offset 

A  pointer  to  a  value  describing  the  byte  offset  of  the  image  data. 

si  ze 

A  pointer  to  the  size  of  the  data,  in  bytes. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Format-specific  importers  may  delegate  this  function,  in  which  case  the  base 
importer's  implementation  will  call  the  32-bit  equivalent, 

Graphi  csImportGetDataOffsetAndSi  ze  (1-624).  If  neither  function  is  implemented  by 
the  format-specific  importer,  then  both  functions  will  return  an  offset  of  0  and  the 
full  size  of  the  data  reference,  taking  into  account  any  data  reference  offset  and  limit. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Graphis  Importers"  (V-2876) 

See  Also 

See  Graphi  csImportGetDataOffsetAndSi  ze  (1-624). 


Inside  QuickTime:  Functions  A-H 
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GraphicsImportGetDataReference 


GraphicsImportGetDataReference 


Returns  a  data  reference  to  imported  graphics  data. 

ComponentResul t  GraphicsImportGetDataReference  ( 
Graphi csImportComponent  ci  , 

Handle  *dataRef, 

OSType  *dataReType  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 
dataRef 

A  pointer  in  which  to  return  a  QuickTime  data  reference.  If  you  don't  want  this 
information, pass  NIL. 
dataReType 

A  pointer  to  receive  the  type  of  the  data  reference;  see  "Data  References" 
(IV-2661).  If  you  don't  want  this  information,  pass  N I L. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  use  this  function  to  get  the  data  reference  that  the  graphics  data  resides  in.  The 
Graphi  csImportGetDataHandl  e  (1-623)  and  GraphicsImportGetDataFile  (1-621) 
functions  call  Graphi  cs  I  mportGet  Data  Reference  and  then  manipulate  the  result 
accordingly.  The  caller  should  dispose  of  the  returned  dataRef. 

Special  Considerations 

Graphics  importer  components  use  QuickTime  data  handler  components  to  obtain 
their  data.  Applications,  however,  will  use  graphics  importer  functions  rather  than 
directly  calling  a  data  handler.  Besides  Graphi  cs  I  mportGet  Data  Reference,  these 
functions  include  Graphi  cs  ImportSetData  Fi  1  e  (1-651),  Graphi  cs  ImportSetDataHandl  e 
(1-652),  Graph  i  cslmport  Get  Da  taFile  (1-621),  GraphicsImportGetDataReference 
(1-653),  GraphicsImportSetDataReferenceOffsetAndLimit  (1-654),  and 
Graphi  cslmport  Get  Data  Ref  erenceOff  set  And  Li  mi  t  (1-627).  These  functions  allow  the 
data  source  to  be  a  file,  a  handle,  or  a  QuickTime  data  reference.  You  only  need  to 
use  these  functions  if  you  open  the  graphics  importer  component  directly.  You 
don't  need  to  call  them  if  you  use  one  of  the  GetGraphi  cs  Importer...  functions  such 
as  GetGraphi  csImporterForDataRef  (1-412).  The  GetGraphi  cslmporter...  functions 
automatically  open  the  graphics  importer  component  and  set  its  data  source. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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GraphicsImportGetDataReferenceOffsetAndLimit 


Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  a  Graphics  Import  Data  Source"  (V-2882) 

Related  Java  Methods 

qui ckti me . std . image . Graphi cs Importer . getDataReferencefypel ) 


See  Also 

For  the  corresponding  set  function,  see  Graphi  cs  Import  Set  Data  Reference  (1-653). 


GraphicsImportGetDataReferenceOffsetAndLimit 


Returns  the  data  reference  starting  offset  and  data  size  limit  for  an  imported  image. 

Component Res ul t  Graphi cs ImportGetDataReferenceOf f set And  Li  mi t  ( 

Graphi cs ImportComponent  ci  , 

unsigned  long  *offset, 

unsigned  long  *limit  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component, 
offset 

A  pointer  to  a  value  specifying  the  byte  offset  of  the  image  data  from  the 
beginning  of  the  data  reference. 

1  i  mi  t 

The  offset  of  the  byte  following  the  last  byte  of  the  image  data. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns  the  values  set  by  the 

Graphi  cs  ImportSetDataReferenceOf fsetAndLimi  t  (1-654)  function.  By  default,  the 
offset  is  0  and  the  limit  is  Maxi nt  (2A32  -  1). 

Special  Considerations 

Graphics  importer  components  use  QuickTime  data  handler  components  to  obtain 
their  data.  Applications,  however,  will  use  graphics  importer  functions  rather  than 
directly  calling  a  data  handler.  Besides 

Graphi  cs  ImportGetDataReferenceOf  f  set  And  Li  mi  t,  these  functions  include 
Graphi  cs  ImportSetDataFi  1  e  (1-651),  Graphi  cs  ImportSetDataHandl  e  (1-652), 

Graphi  cs  ImportGetData  Fi  1  e  (1-621),  Graphi  cs  Import  Set  Data  Reference  (1-653), 
Graphi  cs  ImportSetDataReferenceOf  f  set  And  Li  mi  t  (1-654),  and 


Inside  QuickTime:  Functions  A-H 
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GraphicsImportGetDataReferenceOffsetAndLimit64 


Graphi csImportGetDataReference  (1-626).  These  functions  allow  the  data  source  to 
be  a  file,  a  handle,  or  a  QuickTime  data  reference.  You  only  need  to  use  these 
functions  if  you  open  the  graphics  importer  component  directly.  You  don't  need  to 
call  them  if  you  use  one  of  the  GetGraphi  cs  Importer...  functions  such  as 
GetGraphi  csImporterForDataRef  (1-412).  The  GetGraphi  cslmporter...  functions 
automatically  open  the  graphics  importer  component  and  set  its  data  source. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Graphis  Importers"  (V-2876),  "Specifying  a 
Graphics  Import  Data  Source"  (V-2882) 

See  Also 

See  Graphi  cs  ImportGetDataReferenceOff  setAndLi mi  t64  (1-628).  For  the 
corresponding  set  function,  see  Graphi  csImportSetDataReferenceOffsetAndLi  mi  t 
(1-654). 

GraphicsImportGetDataReferenceOffsetAndLimit64 


Provides  a  64-bit  version  of  Graphi  cs  ImportGetDataReferenceOff  setAndLi  mi  t 
(1-627). 

Component Res ul t  Graphi cs ImportGetDataReferenceOff set And  Li  mi t64  ( 

Graphi csImportComponent  ci  , 

wide  *offset, 

wide  *1  i mi t  ) ; 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component, 
offset 

A  pointer  to  receive  a  value  specifying  the  offset  of  the  byte  data  following  the 
last  byte  of  the  image  data. 

limit 

A  pointer  to  the  data  limit. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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GraphicsImportGetDefaultClip 


Discussion 

The  only  difference  between  this  function  and 

Graphi  cs  ImportGetDataReferenceOf  f  set  And  Li  mi  t  (1-627)  is  that  the  offset 
parameter  and  the  limit  parameter  are  64-bit  integers  instead  of  32-bit  integers. 

Special  Considerations 

New  applications  should  use  this  function  instead  of  the  32-bit  version. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Graphis  Importers"  (V-2876) 

See  Also 

See  Graphi  cs  ImportGetDataReferenceOff  set  And  Li  mi  t  (1-627).  For  the  corresponding 
set  function,  see  Graphi  cs  ImportSetDataReferenceOff  set  And  Li  mi  t64  (1-656). 


GraphicsImportGetDefaultClip 


Returns  the  default  clipping  region  for  an  imported  image,  if  one  is  stored  there. 

ComponentResul t  GraphicsImportGetDefaultClip  ( 

Graphi cs ImportComponent  ci , 

RgnHandle  *defaultRgn  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

def aul tRgn 

A  pointer  to  a  handle  to  a  MacRegi  on  (IV-2303)  structure  to  receive  the  default 
clipping  region. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Returns  badComponentSel  ector  if  there  is  no  clipping  region. 

Special  Considerations 

Most  graphics  importers  don't  implement  this  function.  The  caller  is  responsible  for 
disposing  of  the  returned  region. 

Version  Notes 

Introduced  in  QuickTime  4. 
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GraphicsImportGetDefaultGraphicsMode 


Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Graphis  Importers"  (V-2876) 


GraphicsImportGetDefaultGraphicsMode 


Returns  the  default  graphics  mode  for  an  imported  image,  if  one  is  stored  there. 

ComponentResult  Graphi csImportGetDefaul tGraphi csMode  ( 
GraphicsImportComponent  cl, 

long  *defaul tGraphi csMode , 

RGBColor  *defaul tOpCol or  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

defaul tGraphi csMode 

A  pointer  to  receive  the  graphics  mode;  see  "Graphics  Transfer  Modes" 
(IV-2670). 

defaul tOpCol or 

A  pointer  to  receive  a  color;  see  "Color  Constants"  (IV-2657). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error.  If  this 
function  returns  badComponentSel  ector,  you  should  assume  a  mode 
of  ditherCopy. 

Special  Considerations 

Most  graphics  importers  don't  implement  this  function. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Graphis  Importers"  (V-2876) 


GraphicsImportGetDefaultMatrix 

Returns  the  default  matrix  for  an  imported  image,  if  one  is  stored  there. 

ComponentResult  GraphicsImportGetDefaultMatrix  ( 
GraphicsImportComponent  ci , 
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GraphicsImportGetDefaultSourceRect 


Matri xRecord 


*def aul tMatrix  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

def aul tMatri x 

Receives  a  matrix  record. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

If  this  function  returns  badComponentSel  ector,  you  should  assume  an  identity 
matrix. 

Special  Considerations 

Most  graphics  importers  don't  implement  this  function. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Graphis  Importers"  (V-2876) 


GraphicsImportGetDefaultSourceRect 


Returns  the  default  source  rectangle  for  an  imported  image,  if  one  is  stored  there. 

ComponentResul t  Graphi cs ImportGetDef aul tSourceRect  ( 

Graphi cs ImportComponent  ci  , 

Rect  *def aul tSourceRect  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

def aul tSourceRect 

Pointer  to  receive  a  Rect  (IV-2399)  structure  that  describes  the  default  source 
rectangle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error.  If  this 
function  returns  badComponentSel  ector,  the  source  rectangle  is  equal 
to  the  image's  natural  bounds. 
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GraphicsImportGetDestRect 


Special  Considerations 

Most  graphics  importers  don't  implement  this  function. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Graphis  Importers"  (V-2876) 


GraphicsImportGetDestRect 


Returns  the  destination  rectangle  for  an  imported  image. 

ComponentResul t  GraphicsImportGetDestRect  ( 

Graphi csImportComponent  cl, 

Rect  *destRect  ) ; 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

destRect 

A  pointer  to  receive  a  Rect  (IV-2399)  structure  that  describes  the  destination 
rectangle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

If  the  source  rectangle  is  equal  to  the  natural  bounds,  this  function  is  equivalent  to 
Graphi  csImportGetBounds Rect  (1-619). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Graphis  Importers"  (V-2876) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  csImportSetDestRect  (1-657). 


GraphicsImportGetExportlmageTypeList 

Returns  information  about  available  export  formats  for  a  graphics  importer. 
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GraphicsImportGetExportSettingsAsAtomContainer 


ComponentResul t  Graphi cs ImportGetExportlmageTypeLi st  ( 
Graphi cs ImportComponent  ci  , 

void  *qtAtomContai nerPtr  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 
qtAtomContai nerPtr 

A  pointer  to  a  QuickTime  atom  container  that  is  to  receive  the  type  list. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  creates  and  returns  a  QuickTime  atom  container  of  type  '  expo ' 
(IV-2535)  containing  information  about  the  file  types  that  can  be  exported  by  the 
graphics  import  component.  For  each  file  type,  the  atom  container  contains  the 
following  child  atoms:  ' f ty p '  (IV-2539),  the  exported  file  type;  'mime'  (IV-2561), 
the  MIME  type  for  this  format  (optional);  '  ext  ’  (IV-2536),  the  suggested  file 
extension  for  this  format;  and  '  desc '  (IV-2528),  a  human-readable  name  for  this 
format.  The  '  ftyp'  atom  contains  an  OS  Type;  the  other  atoms  contain  nonterminated 
strings. 

Special  Considerations 

It  is  the  responsibility  of  the  caller  to  dispose  of  the  '  expo '  atom  container. 

Version  Notes 

In  QuickTime  3,  the  supported  export  file  types  are  kQTFi  1  eTypePi  cture, 

kQTFi  1 eTypeQui ckTi  me  I  mage,  kQTFi  1  eTypeBMP,  kQTFi  1  eTypeJPEG,  and 

kQTFi  1  eTypePhotoShop.  In  QuickTime  4,  the  generic  graphics  importer  builds  this 

atom  container  from  the  values  returned  by  the  installed  graphics  exporter 

components. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Saving  Image  Files"  (V-2881) 

Related  Java  Methods 

qui ckti me . std . image . Graphi cs Importer . getExportlmageTypeLi st( ) , 
qui cktime . std .movi es . AtomContai ner . f romGraphi cs Importer  Export  Image! ) 


GraphicsImportGetExportSettingsAsAtomContainer 

Retrieves  settings  for  image  files  exported  by  the  graphics  importer. 
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GraphicsImportGetFlags 


Component Res ul t  Graph i csImportGetExportSetti ngsAsAtomContai ner  ( 
GraphicsImportComponent  ci  , 

void  *qtAtomContai nerPtr  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 
qtAtomContai nerPtr 

A  pointer  to  a  QuickTime  atom  container  that  is  to  receive  the  settings 
information. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  creates  and  returns  a  new  QuickTime  atom  container  which  holds 
information  about  how  images  will  be  saved  by  Graphi  cs  Import  Export  Image  Fi  1  e 
(1-616). 

Special  Considerations 

It  is  the  responsibility  of  the  caller  to  dispose  of  this  atom  container. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Saving  Image  Files"  (V-2881) 

Related  Java  Methods 

qu i ckti me. std. image. Graph icslmporter. get  Expo rtSetti ngsAsAtomContai ner ( ) , 
qui ckti me . std .movi es . AtomContai ner . f romGraphi cs Importer  Expo rtSetti ngs ( ) 


GraphicsImportGetFlags 


Returns  the  current  flags  of  a  graphics  importer  component. 

ComponentResul t  GraphicsImportGetFlags  ( 
GraphicsImportComponent  ci  , 

1  ong  *f 1 ags  ) ; 


The  component  instance  that  identifies  your  connection  to  a  graphics  importer 
component. 
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GraphicsImportGetGraphicsMode 


flags 

Pointer  to  a  long  integer  to  receive  the  current  flags  (see  below). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

kGraphi cs Importer Don tDoGamma Cor recti  on 

The  graphics  importer  does  not  perform  gamma  correction. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Graphis  Importers"  (V-2876) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  cs  ImportSetFl  ags  (1-658). 


GraphicsImportGetGraphicsMode 


Returns  the  graphics  transfer  mode  for  an  imported  image. 

ComponentResul t  GraphicsImportGetGraphicsMode  ( 

Graphi cs ImportComponent  ci  , 

long  *graphi csMode , 

RGBColor  *opColor  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component, 
graphi csMode 

A  pointer  to  a  long  integer;  see  "Graphics  Transfer  Modes"  (IV-2670).  The 
function  returns  the  QuickDraw  graphics  transfer  mode  setting  for  the  image. 
Set  to  N I L  if  you  are  not  interested  in  this  information. 

opCol or 

A  pointer  to  an  RGBColor  (IV-2403)  structure.  The  function  returns  the  color 
currently  specified  for  blend  and  transparent  operations.  Set  to  N I L  if  you  are 
not  interested  in  this  information. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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GraphicsImportGetG  World 


Discussion 

Use  this  function  to  find  out  the  current  graphics  transfer  mode  and  color  to  use  for 
blending  and  transparent  operations.  The  default  graphics  mode  is  ditherCopy  and 
the  default  opCol  or  is  50%  gray. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Setting  Drawing  Parameters"  (V-2879) 

Related  Java  Methods 

qu i c kti me. std. image. Graph icsImporter.getGraphics Model) 


See  Also 

For  the  corresponding  set  function,  see  Graphi  csImportSetGraphi  csMode  (1-659). 


GraphicsImportGetGWorld 


Returns  the  current  graphics  port  and  device  for  drawing  an  imported  image. 

ComponentResul t  GraphicsImportGetGWorld  ( 

Graphi csImportComponent  ci  , 

CGrafPtr  *port, 

GDHandle  *gd  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

port 

Returns  a  pointer  to  the  CGraf  Port  (IV-2168)  structure  for  the  current 
destination  graphics  port.  Set  to  N I L  if  you  are  not  interested  in  this  information, 
gd 

Returns  a  pointer  to  the  GDev  i  ce  (IV-2264)  structure  for  the  destination  graphics 
device.  Set  to  N I L  if  you  are  not  interested  in  this  information. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns  the  graphics  port  and  device  that  will  be  used  to  draw  the 
image.  The  graphics  world  is  initialized  to  the  current  port  and  device  when  the 
graphics  importer  component  is  opened. 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Drawing  Imported  Images"  (V-2880) 

Related  Java  Methods 

qui ckti me . std . image . Graphi cs Importer . getGWorl  d( ) , 
qui cktime . qd . QDGraphi cs . f romGraphi cs Importer ( ) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  cs  ImportSetGWorl  d  (1-660). 


GraphicsImportGetlmageCount 


Returns  the  number  of  images  in  an  imported  image  file. 

ComponentResul t  GraphicsImportGetlmageCount  ( 

Graphi cs ImportComponent  ci  , 

unsigned  long  *imageCount  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component, 
i mageCount 

Points  to  a  variable  to  receive  the  number  of  images. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Most  image  file  formats  don't  support  multiple  images.  Of  the  image  formats 
supported  by  QuickTime  4,  however,  TIFF  files  can  support  multiple  images, 
Photoshop  files  can  contain  multiple  layers  and  FlashPix  files  can  contain  multiple 
resolutions.  The  base  graphics  importer  returns  a  count  of  1. 

Special  Considerations 

Format-specific  importers  for  multiple-image  formats  should  override  this 
function;  other  importers  should  delegate  it. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Graphis  Importers"  (V-2876) 
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GraphicsImportGetlmageDescription 


Returns  image  description  information  for  an  imported  image. 

ComponentResul t  Graphi csImportGetlmageDescripti on  ( 

Graphi csImportComponent  ci  , 

ImageDescri pti onHandl e  *desc  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

desc 

Points  to  a  handle  to  an  ImageDescri  pti  on  (IV-2285)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns  an  ImageDescri  pti  on  (IV-2285)  structure  containing 
information  such  as  the  format  of  the  compressed  data,  its  bit  depth,  natural 
bounds,  and  resolution. 

Special  Considerations 

The  caller  is  responsible  for  disposing  of  the  returned  image  description  handle. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Getting  Image  Characteristics"  (V-2878) 

Related  Java  Methods 

quicktime.std.image.GraphicsImporter.getlmageDescriptionO, 
qui ckti me . std . i mage . ImageDescri pti on . f romGraphi cs Importer! ) 


See  Also 

Format-specific  graphics  importers  always  implement 

Graphi  csImportGetlmageDescri  pti  on  and  may  optionally  implement 

Graphi csImportGetNatural Bounds  (1-642),  Graphi  csImportGetDataOffsetAndSi ze 

(1-624),  Graphi  csImportVal  i  date  (1-665),  Graphi  csImportGetMetaData  (1-640),  and 

Graphi  csImportDoesDrawAl  1  Pixels  (1-613). 


GraphicsImportGetlmagelndex 

Returns  the  current  image  index  for  an  imported  image. 


1-638 


Inside  QuickTime:  Functions  A-H 
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ComponentResul t  GraphicsImportGetlmagelndex  ( 
Graphi cs ImportComponent  ci  , 

unsigned  long  *imagelndex  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component, 
imagelndex 

Points  to  a  variable  to  receive  the  image  index.  Image  indexes  are  one-based;  0 
is  considered  a  special  index  by  some  importers,  and  treated  the  same  as  1  by 
others.  The  default  image  index  is  1. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  base  graphics  importer  implements  this  function.  Format-specific  importers 
should  delegate  it. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Graphis  Importers"  (V-2876) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  cs  Import  Set  Image  Index  (1-661). 


GraphicsImportGetMatrix 


Returns  the  transformation  matrix  to  be  used  for  drawing  an  imported  image. 

ComponentResul t  GraphicsImportGetMatrix  ( 

Graphi cs ImportComponent  ci  , 

MatrixRecord  *matrix  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component, 
matri x 

A  pointer  to  a  MatrixRecord  (IV-2304)  structure  that  defines  the  transformation 
matrix  that  applies  to  the  image. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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Discussion 

The  transformation  matrix  is  initialized  to  the  identity  matrix  when  the  graphics 
import  component  is  instantiated. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Setting  Drawing  Parameters"  (V-2879) 

Related  Java  Methods 

qu i c kt i me. std. image. Graph icslmporter. get Matrix!) 


See  Also 

For  the  corresponding  set  function,  see  Graphics  I  mportSetMatrix  (1-661). 


GraphicsImportGetMetaData 


Extracts  user  data  from  an  imported  image  file. 

ComponentResul t  GraphicsImportGetMetaData  ( 
Graphi csImportComponent  ci  , 

voi  d  *userData  ) ; 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

userData 

A  pointer  to  a  UserData  Record  (IV-2496)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  may  create  a  new  user  data  structure  by  calling  NewUserData  (11-1124). 
Alternatively,  you  can  obtain  a  pointer  to  an  existing  one  by  calling 
GetMovi  eUserData  (1-499),  GetT rackUserData  (1-546)  or  GetMedi  aUserData  (I — 456).  If 
the  user  data  passed  to  GraphicsImportGetMetaData  belongs  to  a  movie,  track  or 
media,  then  whatever  user  data  is  extracted  will  be  added  to  that  movie,  track  or 
media. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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G  raphicsImportG  etMIMETypeList 


Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Getting  Image  Characteristics"  (V-2878) 

Related  Java  Methods 

qui ckti me . std . image . Graphi cs Importer . getMetaData ( ) 

See  Also 

Format-specific  graphics  importers  always  implement 

Graphi  cs  ImportGetlmageDescri  pti  on  (1-638)  and  may  optionally  implement 
Gra phi cs ImportGetNatural Bounds  (1-642),  Graphi  cs Import Get Data Off setAndSi  ze 
(1-624),  Graphi  cs  ImportVal  i  date  (1-665),  and  Graphi  cs  Import  Does  DrawAl  1  Pi  xel  s 
(1-613),  as  well  as  Graphi  csImportGetMetaData. 


GraphicsImportGetMIMETypeList 


Returns  a  list  of  MIME  types  supported  by  the  graphics  importer  component. 

ComponentResul t  GraphicsImportGetMIMETypeList  ( 

Graphi cs ImportComponent  ci  , 

void  *qtAtomContai nerPtr  ); 


ci 

Specifies  an  instance  of  a  graphics  importer  component. 
qtAtomContai nerPtr 

A  pointer  to  a  QuickTime  atom  container  of  type  'mime'  (IV-2561)  that  contains 
a  list  of  MIME  types  supported  by  the  graphics  import  component. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  graphics  import  component  can  support  MIME  types  that  correspond  to 
graphics  formats  it  supports.  To  make  a  list  of  these  MIME  types  available  to 
applications  or  other  software,  it  must  implement  Graphi  cs  ImportGetMIMETypeLi  st. 
To  indicate  that  your  graphics  import  component  supports  this  function,  set  the 
hasMovi  elmportMIMELi  st  flag  in  the  componentFl  ags  field  of  your  component's 
ComponentDescri  pti  on  (IV-2212)  structure. 

Special  Considerations 

This  function  does  not  access  any  file-specific  information. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Getting  MIME  Types"  (V-2881) 

Related  Java  Methods 

qu ickti me. std. image. Graph icsImporter.getMIMETypeListt ) , 
qui  ckti  me .  std  .  movi  es  .  AtomContai  ner  .  f  romGraphl  csImporterMIMEO 


GraphicsImportGetNaturalBounds 


Returns  the  bounding  rectangle  of  an  imported  image. 

ComponentResul t  GraphicsImportGetNaturalBounds  ( 
Graphi csImportComponent  ci  , 

Rect  *natural Bounds  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

natural  Bounds 

A  pointer  to  a  Rect  (IV-2399)  structure  that  describes  the  size  of  the  bounding 
rectangle  for  the  image. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Use  this  function  to  determine  the  native  size  of  the  image  associated  with  a 
graphics  importer  component.  The  natural  bounds  are  always  zero-based.  This  is  a 
convenience  function  that  simply  calls  Graphi  cs  ImportGetlmageDescri  pti  on  (1-638) 
and  extracts  the  width  and  height  fields. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Getting  Image  Characteristics"  (V-2878) 

Related  Java  Methods 

qui  ckti  me.  std.  image.  Graph  icsImporter.getNaturalBoundsO 


See  Also 

Format-specific  graphics  importers  always  implement 

Graphi  csImportGetlmageDescri  pti  on  (1-638)  and  may  optionally  implement 

Graphi  csImportGetDataOffsetAndSi  ze  (1-624),  Graphi  csImportVal  i  date  (1-665), 
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Graphi  cs ImportGetMetaData  (1-640),  and  Graphl  cs  Import  Does  Dr  awAl  1  Pixel  s  (1-613), 
as  well  as  Graphi  csImportGetNatural  Bounds. 


GraphicsImportGetProgressProc 


Returns  the  current  progress  function  for  a  graphics  import  operation. 

ComponentResul t  GraphicsImportGetProgressProc  ( 

Graphi cs ImportComponent  ci  , 

ICMProgressProcRecordPtr  progressProc  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

progressProc 

A  pointer  to  an  ICMProgressProc  (III— 2093)  callback. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

By  default,  graphics  import  components  have  no  progress  functions. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Setting  Drawing  Parameters"  (V-2879) 

See  Also 

For  the  corresponding  set  function,  see  Graphi  cs  Import  Set  ProgressProc  (1-662). 


GraphicsImportGetQuality 


Returns  the  image  quality  value  for  an  imported  image. 

ComponentResul t  GraphicsImportGetQuality  ( 

Graphi cs ImportComponent  ci  , 

CodecQ  *quality  ); 


The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 


Inside  QuickTime:  Functions  A-H 


1-643 


GraphicsImportGetQuality 


qual i ty 

A  pointer  to  a  constant  (see  below)  that  defines  the  currently  specified  quality 
value. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

quality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics, 
codec Normal Qual i ty 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 

codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field. 
codecLosslessQuality 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

Discussion 

The  quality  value  indicates  how  precisely  the  decompressor  will  decompress  the 
image  data.  Some  decompressors  may  choose  to  ignore  some  image  data  to 
improve  decompression  speed. 

Version  Notes 

With  QuickTime  3  the  default  quality  is  codecHi  ghQual  i  ty. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Setting  Drawing  Parameters"  (V-2879) 

Related  Java  Methods 

qu ickti me. std. image. Graph icsImporter.getQualityO 


See  Also 

Lor  the  corresponding  set  function,  see  Graphi csImportSetQual  i  ty  (1-663). 
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GraphicsImportGetSourceRect 


Returns  the  current  source  rectangle  for  an  imported  image. 

ComponentResul t  GraphicsImportGetSourceRect  ( 

Graphi cs ImportComponent  ci  , 

Rect  *sourceRect  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

sourceRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  defines  the  source  rectangle 
currently  specified  for  the  image. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns  the  current  source  rectangle,  as  specified  by 

Graphi  csImportSetSource Rect  (1-664).  The  default  source  rectangle  is  the  image's 

natural  bounds. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Setting  Drawing  Parameters"  (V-2879) 

Related  Java  Methods 

qui ckti me . std . image . Graphi cs Importer . get Source Rect ( ) 


See  Also 

For  the  corresponding  set  function,  see  Graphi  csImportSetSourceRect  (1-664) . 


GraphicsImportReadData 


Reads  imported  image  data. 

ComponentResul t  GraphicsImportReadData  ( 
Graphi cs ImportComponent  ci  , 
void  *dataPtr, 

unsigned  long  dataOffset, 

unsigned  long  dataSize  ); 
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GraphicsImportReadData64 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 
dataPtr 

A  pointer  to  a  memory  block  to  receive  the  data. 
dataOffset 

The  offset  of  the  image  data  within  the  data  reference.  The  function  begins 
reading  image  data  from  this  offset. 
dataSi ze 

The  number  of  bytes  of  image  data  to  read. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  communicates  with  the  appropriate  data  handler  to  retrieve  image 
data.  Typically,  only  developers  of  graphics  importer  components  will  need  to  use 
this  function.  This  function  should  always  be  used  to  retrieve  data  from  the  data 
source,  rather  than  reading  the  data  directly.  This  function  automatically  honors 
any  offset  and  limit  values  set  with  Graph  i  csImportSetDataReferenceOffsetAndLi  mi  t 
(1-654).  For  instance,  if  the  offset  is  set  to  100  and  Graphi  csImportReadData  is  called 
to  read  bytes  from  dataOffset  5,  it  will  return  bytes  starting  at  actual  offset  105. 

Special  Considerations 

This  function  is  used  by  format-specific  graphics  import  components  to  read  data 
from  the  data  source.  It  is  implemented  by  the  base  graphics  importer. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Graphis  Importers"  (V-2876),  "Retrieving 
Graphics  Import  Image  Data"  (V-2883) 

Related  Java  Methods 

quicktime.std.image.GraphicsImporter.readDataO 

See  Also 

See  Graphi  cs  Import  Re  ad  Data  64  (1-646). 

GraphicsImportReadData64 

Provides  a  64-bit  version  of  Graphi  csImportReadData  (1-645). 
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GraphicsImportSaveAsPicture 


ComponentResul t  Graphi cs ImportReadData64  ( 
Graphi cs ImportComponent  ci  , 
void  *dataPtr, 

const  wide  *dataOffset, 

unsigned  long  dataSize  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 
dataPtr 

A  pointer  to  a  memory  block  to  receive  the  data. 
dataOf f set 

A  pointer  to  the  offset  of  the  image  data  within  the  data  reference. 
dataSi ze 

The  number  of  bytes  of  image  data  to  read. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  a  64-bit  analog  of  Graphi  csImportReadData  (1-645).  Format-specific 
importers  may  call  either  version. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Graphis  Importers"  (V-2876) 

See  Also 

See  Graphi  csImportReadData  (1-645). 


GraphicsImportSaveAsPicture 


Creates  a  QuickDraw  picture  file  for  an  imported  image. 

ComponentResul t  GraphicsImportSaveAsPicture  ( 

Graphi cs ImportComponent  ci  , 

const  FSSpec  *fss, 

ScriptCode  scriptTag  ); 


The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 
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fss 

A  pointer  to  an  FSSpec  (IV-2262)  structure  that  defines  the  file  to  receive  the 
image, 
scri ptTag 

The  script  system  in  which  the  file  name  is  to  be  displayed;  see  "Localization 
Codes"  (IV-2673).  If  you  have  established  the  name  and  location  of  the  file 
using  one  of  the  Standard  File  Package  functions,  use  the  script  code  returned 
in  the  reply  record  (reply.  sfScript).  Otherwise,  specify  the  system  script  by 
setting  the  scri  ptTag  parameter  to  the  value  smSystemScri  pt.  See  Inside 
Macintosh:  Files  (listed  in  the  bibliography)  for  more  information  about  script 
specifications. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  creates  a  new  QuickDraw  picture  file  containing  the  image  currently 
in  use  by  the  graphics  import  component.  If  possible,  the  image  will  remain  in  the 
compressed  format.  For  example,  if  the  image  is  from  a  JFIF  file,  the  picture  will 
contain  compressed  JPEG  data.  Applications  that  only  wish  to  draw  the  image  can 
use  Graphl  cs  Import  Dr  aw  (1-616). 

Special  Considerations 

Graphics  import  components  can  save  data  in  several  formats,  including 
QuickDraw  pictures  and  QuickTime  Image  files.  This  capability  is  only  needed  by 
applications  that  perform  file  format  translation. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Saving  Image  Files"  (V-2881) 

Related  Java  Methods 

quicktime.std.image.Graphi cs Importer . save As  Pi cture( ) 


GraphicsImportSaveAsQuickTimelmageFile 


Creates  a  QuickTime  Image  file  of  an  imported  image. 

ComponentResul t  Graphi csImportSaveAsQui ckTimelmageFi 1 e  ( 
GraphicsImportComponent  ci  , 

const  FSSpec  *fss, 

ScriptCode  scriptTag  ); 
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ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

f  ss 

A  pointer  to  the  FSSpec  (IV-2262)  that  defines  the  file  to  receive  the  image, 
scri ptTag 

The  script  system  in  which  the  file  name  is  to  be  displayed;  see  "Localization 
Codes"  (IV-2673).  If  you  have  established  the  name  and  location  of  the  file 
using  one  of  the  Standard  File  Package  functions,  use  the  script  code  returned 
in  the  reply  record  (reply .  sf  Scri  pt).  Otherwise,  specify  the  system  script  by 
setting  the  scri  ptTag  parameter  to  the  value  smSystemScri  pt.  See  Inside 
Macintosh:  Files  (listed  in  the  bibliography)  for  more  information  about  script 
specifications. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  creates  a  new  QuickTime  Image  file  containing  the  image  currently  in 
use  by  the  graphics  import  component.  If  possible,  the  image  remains  in  the 
compressed  format.  For  example,  if  the  image  is  from  a  JFIF  file,  the  QuickTime 
Image  file  will  contain  compressed  JPEG  data. 

Special  Considerations 

Graphics  import  components  can  save  data  in  several  formats,  including 
QuickDraw  pictures  and  QuickTime  Image  files.  This  capability  is  only  needed  by 
applications  that  perform  file  format  translation.  Applications  that  only  wish  to 
draw  the  image  can  use  the  Graphi  cs  ImportDraw  (1-616)  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Saving  Image  Files"  (V-2881) 

Related  Java  Methods 

qui ckti me . std . image . Graphi cs Importer . saveAsQui ckTimelmageFi 1 e( ) 


GraphicsImportSetBoundsRect 


Defines  the  rectangle  in  which  to  draw  an  imported  image. 

ComponentResul t  GraphicsImportSetBoundsRect  ( 

Graphi cs ImportComponent  ci  , 
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const  Rect 


*bounds  )  ; 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

bounds 

A  pointer  to  a  Rect  (IV-2399)  structure  that  describes  the  bounding  rectangle 
into  which  the  image  will  be  drawn. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  use  this  function  to  define  the  rectangle  into  which  the  graphics  image  should 
be  drawn.  The  function  creates  a  transformation  matrix  to  map  the  image's  natural 
bounds  to  the  specified  bounds  and  then  calls  Graphi  cs  ImportSetMatri  x  (1-661). 

Special  Considerations 

Because  this  function  affects  the  transformation  matrix,  you  should  use 

Graph icsImportSetMatrix  (1-66 1 )  instead  of  this  function  if  you  also  need  to  specify 

more  complex  transformations  of  the  matrix. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Setting  Drawing  Parameters"  (V-2879) 

Related  Java  Methods 

qu  i  ckti  me.  std.  image.  Graph  icsImporter.setBounds RectO 


See  Also 

For  the  corresponding  get  function,  see  Graphi  cs  Import  Get  Bounds  Rect  (1-619).  If  the 
source  rectangle  is  equal  to  the  natural  bounds,  Graphi  csImportSetBoundsRect  is 
equivalent  to  Graphi  csImportSetDestRect  (1-657). 


GraphicsImportSetClip 


Defines  the  clipping  region  for  drawing  an  imported  image. 

ComponentResul t  GraphicsImportSetClip  ( 

Graphi csImportComponent  ci  , 

RgnHandl e  cl i pRgn  ) ; 
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ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component, 
cl  i  pRgn 

A  handle  to  a  Mac  Reg  i  on  (IV-2303)  structure  that  defines  the  clipping  region  in 
the  destination  coordinate  system.  Set  to  N I L  to  disable  clipping.  The  graphics 
import  component  makes  a  copy  of  this  region. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Because  all  drawing  operations  ignore  the  port  clipping  region,  you  must  use  this 
function  to  clip  an  image.  The  graphics  importer  component  draws  only  that 
portion  of  the  image  that  lies  within  the  specified  clipping  region. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Setting  Drawing  Parameters"  (V-2879) 

Related  Java  Methods 

qui ckti me . std . image . Graphi cs Importer . setCl i p ( ) 


See  Also 

For  the  corresponding  get  function,  see  Graphi  csImportGetCl  i  p  (1-620). 


GraphicsImportSetDataFile 


Specifies  the  file  that  contains  imported  graphics  data. 

ComponentResul t  GraphicsImportSetDataFile  ( 

Graphi cs ImportComponent  ci  , 

const  FSSpec  *theFile  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

theFi  1  e 

A  pointer  to  an  FSSpec  (IV-2262)  structure  that  defines  the  file  containing  the 
graphics  data.  The  returned  file  will  be  opened  for  read  access. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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GraphicsImportSetDataHandle 


Special  Considerations 

Graphics  importer  components  use  QuickTime  data  handler  components  to  obtain 
their  data.  Applications,  however,  will  use  graphics  importer  functions  rather  than 
directly  calling  a  data  handler.  Besides  Graphi  cs  ImportSetData  Fi  1  e,  these  functions 
include  Graphi  csImportGetDataFi  1  e  (1-621),  Graphi  csImportSetDataHandl  e  (1-652), 
Graphi  csImportGetDataHandl  e  (1-623),  Graphi  csImportSetDataReference  (1-653), 
Graphi  csImportSetDataReferenceOffsetAndLi  mi  t  (1-654),  and 

Graphi  cs  Import  Get  Data  Ref  erenceOff  set  And  Li  mi  t  (1-627).  These  functions  allow  the 
data  source  to  be  a  file,  a  handle,  or  a  QuickTime  data  reference.  You  only  need  to 
use  these  functions  if  you  open  the  graphics  importer  component  directly.  You 
don't  need  to  call  them  if  you  use  one  of  the  GetGraphi  cs  Importer...  functions  such 
as  GetGraphi csImporterForDataRef  (1-412).  The  GetGraphi  cslmporter...  functions 
automatically  open  the  graphics  importer  component  and  set  its  data  source. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  a  Graphics  Import  Data  Source"  (V-2882) 

Related  Java  Methods 

qu i c kti me. std. image. Graphi cslmporter. set Da taFilet) 


See  Also 

For  the  corresponding  get  function,  see  Graphi  cs  ImportGetDataFi  1  e  (1-621). 


GraphicsImportSetDataHandle 


Specifies  the  handle  that  references  imported  graphics  data. 

ComponentResul t  GraphicsImportSetDataHandle  ( 

Graphi csImportComponent  ci  , 

Handl e  h  ) ; 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

h 

Specifies  a  handle  containing  graphics  data.  The  format  of  the  data  in  the 
handle  is  the  same  as  that  found  in  a  file. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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Discussion 

The  graphics  importer  component  doesn't  make  a  copy  of  this  data.  Therefore,  you 
must  not  dispose  this  handle  until  the  graphics  importer  has  been  closed. 

Special  Considerations 

Graphics  importer  components  use  QuickTime  data  handler  components  to  obtain 
their  data.  Applications,  however,  will  use  graphics  importer  functions  rather  than 
directly  calling  a  data  handler.  Besides  Graphi  csImportSetDataHandl  e,  these 
functions  include  Graphi  csImportGetDataFi  1  e  (1-621),  Graphi  csImportSetDataFi  1  e 
(1-651),  Graphi  cs  ImportGetDataHandl  e  (1-623),  Graphi  cs  Import  Set  Data  Reference 
(1-653),  Graphi  cs  ImportSetDataReferenceOf  f  set  And  Li  mi  t  (1-654),  and 
Graphi  cs  ImportGetDataReferenceOf  f  set  And  Li  mi  t  (1-627).  These  functions  allow  the 
data  source  to  be  a  file,  a  handle,  or  a  QuickTime  data  reference.  You  only  need  to 
use  these  functions  if  you  open  the  graphics  importer  component  directly.  You 
don't  need  to  call  them  if  you  use  one  of  the  GetGraphi  cslmporter...  functions  such 
as  GetGraphi  cs  Importer  For  Data  Ref  (1-412).  The  GetGraphi  cslmporter...  functions 
automatically  open  the  graphics  importer  component  and  set  its  data  source. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  a  Graphics  Import  Data  Source"  (V-2882) 

Related  Java  Methods 

qui ckti me . std . image . Graphi  cslmporter.  setDataHandlel) 


See  Also 

For  the  corresponding  get  function,  see  Graphi  csImportGetDataHandl  e  (1-623). 


GraphicsImportSetDataReference 


Specifies  the  data  reference  for  imported  graphics  data. 

ComponentResul t  GraphicsImportSetDataReference  ( 
Graphi cs ImportComponent  ci , 

Handle  dataRef, 

OSType  dataReType  ); 


The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 
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dataRef 

A  handle  to  a  QuickTime  data  reference. 
dataReType 

The  data  reference  type.  See  "Data  References"  (IV-2661). 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Applications  typically  don't  use  this  function.  The  Graphi  cs  ImportSetData  Fi  1  e 
(1-651)  and  Graphi  cs  ImportSetDataHandl  e  (1-652)  functions  both  call  this  function, 
with  the  appropriate  data  reference  and  data  reference  type.  This  function  makes  a 
copy  of  the  passed  data  reference,  so  it  is  safe  to  dispose  of  the  handle  immediately 
after  the  call. 

Special  Considerations 

Graphics  importer  components  use  QuickTime  data  handler  components  to  obtain 
their  data.  Applications,  however,  will  use  graphics  importer  functions  rather  than 
directly  calling  a  data  handler.  Besides  Graphi  cs  Import  Set  Data  Reference,  these 
functions  include  Graphi  cs  ImportGetData  Fi  1  e  (1-621),  Graphi  cs  ImportSetDataHandl  e 
(1-652),  Graphi  csImportGetDataHandl  e  (1-623),  Graphi  csImportSetDataFi  1  e  (1-651), 
Graphi  csImportSetDataReferenceOffsetAndLi  mi  t  (1-654),  and 

Graphi  cs  ImportGetData  Ref  erenceOff  set  And  Li  mi  t  (1-627).  These  functions  allow  the 
data  source  to  be  a  file,  a  handle,  or  a  QuickTime  data  reference.  You  only  need  to 
use  these  functions  if  you  open  the  graphics  importer  component  directly.  You 
don't  need  to  call  them  if  you  use  one  of  the  GetGraphi  cs  Importer...  functions  such 
as  GetGraphi csImporterForDataRef  (1-412).  The  GetGraphi  cslmporter...  functions 
automatically  open  the  graphics  importer  component  and  set  its  data  source. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Specifying  a  Graphics  Import  Data  Source"  (V-2882) 

Related  Java  Methods 

qu i c kt i me. std.image.GraphicsImporter. set Data  Reference!) 


See  Also 

For  the  corresponding  get  function,  see  Graphi  csImportGetDataReference  (1-626). 


GraphicsImportSetDataReferenceOffsetAndLimit 

Specifies  the  data  reference  starting  offset  and  data  size  limit  for  an  imported  image. 
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Component Res ul t  Graphi cs Import Set Data  Ref erenceOf f set And  Li  mi t  ( 
Graphi cs ImportComponent  ci  , 

unsigned  long  offset, 

unsigned  long  limit  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

offset 

The  byte  offset  of  the  image  data  from  the  beginning  of  the  data  reference. 

1  i  mi  t 

A  pointer  to  a  value  specifying  the  offset  of  the  byte  following  the  last  byte  of 
the  image  data. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

A  data  reference  typically  refers  to  an  entire  file.  However,  there  are  times  when  the 
data  being  referenced  is  embedded  in  a  larger  file.  In  these  cases,  it  is  necessary  to 
indicate  where  the  data  begins  in  the  data  reference  and  where  it  ends.  This  function 
lets  you  specify  the  starting  offset  and  ending  offset.  All  requests  to  read  data  are 
then  relative  to  the  specified  offset,  and  are  pinned  to  the  data  size,  so  the  graphics 
import  component  cannot  accidentally  read  outside  the  end  (or  beginning)  of  the 
segment. 

Special  Considerations 

Graphics  importer  components  use  QuickTime  data  handler  components  to  obtain 
their  data.  Applications,  however,  will  use  graphics  importer  functions  rather  than 
directly  calling  a  data  handler.  Besides 

Graphi  cs  Import  Set  Data  Ref  erenceOf  f  set  And  Li  mi  t,  these  functions  include 
Graphi  cs  ImportGetData  Fi  1  e  (1-621),  Graphi  cs  ImportSetDataHandl  e  (1-652), 

Graphi  cs ImportGetDataHandl  e  (1-623),  Graphi  csImportSetDataReference  (1-653), 
Graphi  cs  ImportSetData  Fi  1  e  (1-651),  and 

Graphi  cs  ImportGetDataRef erenceOf fsetAndLimi  t  (1-627).  These  functions  allow  the 
data  source  to  be  a  file,  a  handle,  or  a  QuickTime  data  reference.  You  only  need  to 
use  these  functions  if  you  open  the  graphics  importer  component  directly.  You 
don't  need  to  call  them  if  you  use  one  of  the  GetGraphi  cslmporter...  functions  such 
as  GetGraphi  cs  Importer  For  Data  Ref  (1-412).  The  GetGraphi  cslmporter...  functions 
automatically  open  the  graphics  importer  component  and  set  its  data  source. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Functions  A-H 


1-655 


GraphicsImportSetDataReferenceOffsetAndLimit64 


Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Graphis  Importers"  (V-2876),  "Specifying  a 
Graphics  Import  Data  Source"  (V-2882) 

See  Also 

See  Graphl  cs ImportSetDataReferenceOff setAndLI mi  t64  (1-656).  For  the 
corresponding  get  function,  see  Graphi  cs  ImportGetDataReferenceOf  f  set  And  Li  mi  t 
(1-627). 

GraphicsImportSetDataReferenceOffsetAndLimit64 


Provides  a  64-bit  version  of  Graphi  cs  ImportSetDataReferenceOff  set  And  Li  mi  t 
(1-654). 

Component Res ul t  Graphi cs ImportSetDataReferenceOff set And  Li  mi t64  ( 
GraphicsImportComponent  ci  , 

const  wide  *offset, 

const  wide  *1 imi t  ) ; 


ci 

A  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

offset 

A  pointer  to  a  value  specifying  the  byte  offset  of  the  image  data  from  the 
beginning  of  the  data  source, 
limit 

A  pointer  to  a  value  specifying  the  offset  of  the  byte  following  the  last  byte  of 
the  image  data. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  a  64-bit  analog  of  Graphi  cs  ImportSetDataReferenceOff  set  And  Li  mi  t 
(1-654). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Graphis  Importers"  (V-2876) 
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See  Also 

See  Graphi  cs  ImportSetDataReferenceOff  set  And  Li  mi  t  (1-654).  For  the  corresponding 
get  function,  see  Graphi  cs  Import  Get  Data  Ref  erenceOffsetAnd  Li  mi  t64  (1-628). 


GraphicsImportSetDestRect 


Sets  the  destination  rectangle  for  a  graphics  import  operation. 

ComponentResul t  GraphicsImportSetDestRect  ( 

Graphi cs ImportComponent  ci  , 

const  Rect  *destRect  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 
destRect 

Points  to  a  Rect  (IV-2399)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Use  this  function  to  define  the  rectangle  into  which  the  extracted  source  rectangle 
should  be  drawn.  This  function  creates  a  transformation  matrix  to  map  the  source 
rectangle  to  the  specified  destination  rectangle  and  then  calls  the 
Graphi  cs  ImportSetMatri x  (1-661)  function. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Graphis  Importers"  (V-2876) 

See  Also 

For  the  corresponding  get  function,  see  Graphi  csImportGetDestRect  (1-632).  If  the 
source  rectangle  is  equal  to  the  natural  bounds,  this  function  is  equivalent  to 
Graphi  csImportSetBoundsRect  (1-649). 


GraphicsImportSetExportSettingsFromAtomContainer 

Determines  settings  for  the  export  of  imported  image  files. 
ComponentResul t  Graphi cs Import Set Export Sett i ngsFromAtomContai ner  ( 
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Graphi  csImportComponent  ci  , 

void  *qtAtomContai ner  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 
qtAtomContai ner 

A  pointer  to  a  QuickTime  atom  container  that  holds  new  settings  information. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  extracts  export  settings  from  a  QuickTime  atom  container.  These 
settings  configure  how  images  will  be  saved  by  Graphi  cs  Import  Export  ImageFi  1  e 
(1-616). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Saving  Image  Files"  (V-2881) 

Related  Java  Methods 

qui ckti me . std . i mage . Graphi cs Importer . set  Expo rtSetti ngsFromAtomContai ner ( ) 


GraphicsImportSetFlags 


Sets  the  flags  for  a  graphics  importer  component. 

ComponentResul t  GraphicsImportSetFlags  ( 
Graphi csImportComponent  ci  , 

1 ong  f 1 ags  ) ; 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

fl  ags 

The  new  flags  (see  below)  to  use. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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flags  Constants 

kGraphi cs ImporterDontDoGammaCor recti  on 

The  graphics  importer  will  not  perform  gamma  correction. 


Version  Notes 

Introduced  in  QuickTime  4. 


Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Graphis  Importers"  (V-2876) 

See  Also 

For  the  corresponding  get  function,  see  Graph  icsImportGetFlags  (1-634). 


GraphicsImportSetGraphicsMode 


Sets  the  graphics  transfer  mode  for  an  imported  image. 

ComponentResul t  GraphicsImportSetGraphicsMode  ( 
Graphi cs ImportComponent  ci  , 

long  graphi csMode , 

const  RGBColor  *opColor  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component, 
graphi csMode 

The  graphics  transfer  mode  to  use  for  drawing  the  image;  see  "Graphics 
Transfer  Modes"  (IV-2670). 

opCol or 

A  pointer  to  an  RGBColor  (IV-2403)  structure  that  describes  the  color  to  use  for 
blending  and  transparent  operations. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Use  this  function  to  specify  the  graphics  transfer  mode  and  color  to  use  for  blending 
and  transparent  operations. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Setting  Drawing  Parameters"  (V-2879) 
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GraphicsImportSetGWorld 


Related  Java  Methods 

qu i c kti me. std. image. Graph icsImporter.setGraphics Model) 


See  Also 

For  the  corresponding  get  function,  see  Graphi  csImportGetGraphi  csMode  (1-635). 


GraphicsImportSetGWorld 


Sets  the  graphics  port  and  device  for  drawing  an  imported  image. 

ComponentResul t  GraphicsImportSetGWorld  ( 

Graphi csImportComponent  ci  , 

CGrafPtr  port, 

GDHandl e  gd  ) ; 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

port 

A  pointer  to  the  CGraf  Port  (IV-2168)  structure  that  defines  the  destination 
graphics  port  or  graphics  world.  Set  to  N I L  to  use  the  current  port, 
gd 

A  handled  to  the  GDevi  ce  (IV-2264)  structure  that  defines  the  destination 
graphics  device.  Set  to  N I L  to  use  the  current  device.  If  the  port  parameter 
specifies  a  graphics  world,  set  this  parameter  to  N I L  to  use  that  graphics  world's 
device. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  graphics  world  is  initialized  to  the  current  port  and  device  when  the  graphics 
importer  component  is  opened.  Use  this  function  to  select  another  port  or  device. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Drawing  Imported  Images"  (V-2880) 

Related  Java  Methods 

qu ic kti me. std. image. Graph icslmporter. set GWorldO 


See  Also 

For  the  corresponding  get  function,  see  Graphi  cs  ImportGetGWorl  d  (1-636). 
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GraphicsImportSetlmagelndex 


Specifies  the  image  index  for  an  imported  image. 

ComponentResul t  GraphicsImportSetlmagelndex  ( 
Graphi cs ImportComponent  ci  , 

unsigned  long  imagelndex  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

imagelndex 

The  image  index.  Image  indexes  are  one-based;  0  is  considered  a  special  index 
by  some  importers,  and  treated  the  same  as  1  by  others.  The  default  image 
index  is  1. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  base  graphics  importer  ensures  that  the  image  index  is  no  greater  than  the 
image  count  returned  by  Graphi  cs  ImportGet  ImageCount  (1-637). 

Special  Considerations 

The  base  graphics  importer  implements  this  function.  Format-specific  importers 
should  delegate  it. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Graphis  Importers"  (V-2876) 

See  Also 

For  the  corresponding  get  function,  see  Graphi  csImportGetlmagelndex  (1-638). 


GraphicsImportSetMatrix 


Defines  the  transformation  matrix  to  use  for  drawing  an  imported  image. 

ComponentResul t  GraphicsImportSetMatrix  ( 

Graphi cs ImportComponent  ci  , 

const  MatrixRecord  *matrix  ); 
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1-661 


GraphicsImportSetProgressProc 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component, 
matri x 

A  pointer  to  a  matrix  structure  that  specifies  how  to  transform  the  image  during 
decompression.  For  example,  you  can  use  a  transformation  matrix  to  scale  or 
rotate  the  image.  To  set  the  matrix  to  identity,  pass  N I L  in  this  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  establishes  the  transformation  matrix  to  be  applied  to  an  image,  which 
determines  where  and  how  it  will  be  drawn. 

Special  Considerations 

This  function  affects  the  bounding  rectangle  defined  for  the  image.  You  can  specify 
where  an  image  will  be  drawn  by  setting  either  a  transformation  matrix  or  a 
bounding  rectangle,  but  it  is  usually  more  convenient  for  applications  to  set  a 
bounding  rectangle  using  the  Graphi  csImportSetBoundsRect  (1-649)  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Setting  Drawing  Parameters"  (V-2879) 

Related  Java  Methods 

quicktime.std.image.GraphicsImporter.setMatrixO 


See  Also 

For  the  corresponding  get  function,  see  Graphi  csImportGetMatrix  (1-639). 


GraphicsImportSetProgressProc 


Installs  a  progress  procedure  to  call  while  drawing  an  imported  image. 

ComponentResul t  GraphicsImportSetProgressProc  ( 

Graphi csImportComponent  ci  , 

ICMProgressProcRecordPtr  progressProc  ); 


The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 
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GraphicsImportSetQuality 


progressProc 

Points  to  an  ICMProgressProc  (III— 2093)  callback.  If  you  passavalue  of-1, 
QuickTime  provides  a  standard  progress  function.  If  you  want  to  remove  the 
existing  progress  function,  pass  N I L. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  sets  a  progress  function  that  will  be  installed  in  the  image 
decompression  sequence  used  to  draw  the  image. 

Special  Considerations 

If  your  progress  function  does  any  drawing,  you  should  take  care  to  set  a  safe 
graphics  state  before  doing  so,  and  to  restore  the  graphics  state  afterwards.  In 
particular,  the  current  graphics  device  may  be  an  offscreen  device. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Setting  Drawing  Parameters"  (V-2879) 

See  Also 

For  the  corresponding  get  function,  see  Graphi  csImportGetProgressProc  (1-643). 


GraphicsImportSetQuality 


Sets  the  image  quality  value  for  an  imported  image. 

ComponentResul t  GraphicsImportSetQuality  ( 

Graphi cs ImportComponent  ci  , 

CodecQ  quality  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component, 
quality 

Contains  a  constant  (see  below)  that  defines  the  desired  image  quality  for 
decompression.  Values  for  this  parameter  are  on  the  same  scale  as  compression 
quality. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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GraphicsImportSetSourceRect 


quality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics, 
codec Normal  Qua  1 i ty 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 

codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field. 
codecLosslessQuality 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

Discussion 

The  quality  parameter  controls  how  precisely  the  decompressor  decompresses  the 
image  data.  Some  decompressors  may  choose  to  ignore  some  image  data  to 
improve  decompression  speed. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Setting  Drawing  Parameters"  (V-2879) 

Related  Java  Methods 

qu ickti me. std. image. Graph icsImporter.setQualityt) 


See  Also 

For  the  corresponding  get  function,  see  Graphi  cs  ImportGetQual  i  ty  (1-643). 


GraphicsImportSetSourceRect 


Sets  the  source  rectangle  to  use  for  an  imported  image. 

ComponentResul t  GraphicsImportSetSourceRect  ( 
GraphicsImportComponent  ci  , 

const  Rect  *sourceRect  ); 
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GraphicsImportValidate 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 
sourceRect 

A  pointer  to  a  Rect  (IV-2399)  structure  defining  the  portion  of  the  image  to 
decompress.  This  rectangle  must  lie  within  the  boundary  rectangle  of  the 
source  image.  Set  to  N I L  to  use  the  entire  image. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  provides  a  way  to  use  only  a  portion  of  the  source  image. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Setting  Drawing  Parameters"  (V-2879) 

Related  Java  Methods 

qui cktime . std . i mage . Graphi cs Importer . s et Source Rect ( ) 


See  Also 

For  the  corresponding  get  function,  see  Graphi  csImportGetSourceRect  (1-645). 


Graphicslmport  V  alidate 


Validates  image  data  for  a  data  reference  to  an  imported  image. 

ComponentResul t  GraphicsImportValidate  ( 

Graphi cs ImportComponent  ci  , 

Boolean  * v a t id  ); 


ci 

The  component  instance  that  identifies  your  connection  to  the  graphics 
importer  component. 

valid 

Pointer  to  a  Bool  ean  value.  On  return,  this  parameter  is  set  to  TRUE  if  the  the 
graphics  importer  component  can  draw  the  data  reference.  If  the  graphics 
importer  component  cannot  draw  the  data  reference,  this  parameter  is  set  to 
FALSE. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error.  Not 
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HasMovieChanged 


all  graphics  importer  components  implement  this  function.  A 
component  that  does  not  implement  the  function  will  return  the 
badComponentSel  ector  result  code.  This  does  not  indicate  that  the  file 
is  valid  or  invalid. 

Discussion 

This  function  allows  a  graphics  importer  component  to  determine  if  its  current  data 
reference  contains  valid  image  data.  For  example,  a  JFIF  graphics  importer 
component  might  check  for  the  presence  of  a  JFIF  marker  at  the  start  of  the  data 
stream.  This  function  is  provided  for  applications  to  use  to  determine  what  type  of 
image  data  a  particular  file  may  contain.  Sometimes  a  file  may  not  have  the  correct 
file  type  or  file  extension.  In  this  case,  the  application  will  not  know  which  graphics 
importer  component  to  use.  By  iterating  through  all  graphics  importer  components 
and  calling  Graph  icsImportVali  date  for  each  one,  it  may  be  possible  to  locate  a 
graphics  importer  component  that  can  draw  the  specified  file. 

Special  Considerations 

Graphi  csImportVal  i  date  does  not  perform  an  exhaustive  check  on  the  file.  It  is 
possible  for  Graphi  csImportVal  i  date  to  claim  a  data  reference  is  valid  but  for 
Graphi  csImportDraw  (1-616)  to  return  an  error  due  to  bad  data.  Format-specific 
importers  that  implement  the  Graphi  csImportVal  i  date  call  should  have  the 
canMovi  elmportVal  i  dateFi  1  e  bit  set  in  the  f  1  ags  field  of  their  ComponentDescri  pti  on 
(IV-2212)  structures. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Getting  Image  Characteristics"  (V-2878) 

Related  Java  Methods 

quickti me. std.image.GraphicsImporter. validate!) 


HasMovieChanged 

Determines  whether  a  movie  has  changed  and  needs  to  be  saved. 
Boolean  HasMovieChanged  ( 
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HitTestDSequenceData 


Movie  theMovie  ); 
theMovi  e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  Returns  TRUE  if  the  movie  has  changed,  FALSE  otherwise. 

Discussion 

Your  application  can  clear  the  movie  changed  flag,  indicating  that  the  movie  has  not 
changed,  by  calling  Cl  earMovi  eChanged  (1-89). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Saving  Movies"  (V-2715) 

Related  Java  Methods 

qui cktime . std .movi es . Movi e . hasChangedt ) 


HitT  estDSequenceData 


Undocumented 


OSErr  HitTestDSequenceData  ( 


ImageSequence 
voi  d 
Si  ze 
Poi  nt 
1  ong 
1  ong 


seqlD, 
*data , 
dataSi ze , 
where , 

*hi  t , 


seqlD 

The  unique  sequence  identifier  that  was  returned  by  the 
DecompressSequenceBegi  n  (1-238)  function. 

data 

A  pointer  to  data. 
dataSi ze 

The  size  of  the  data. 
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HitTestDSequenceData 


where 

A  Point  (IV-2339)  structure  that  defines  the  hit  location, 
hi  t 

Undocumented 
hi  t FI ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

hitFlags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Related  Java  Methods 

quicktime.std.image.DSequence.hitTestDataO 
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ICMDecompressComplete 


I 


ICMDecompressComplete 


Signals  the  completion  of  a  decompression  operation. 

void  ICMDecompressComplete  ( 

ImageSequence 
OSErr 
short 

ICMCompl eti onProcRecordPtr 
seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi  n  (1-238). 

err 

Indicates  whether  the  operation  succeeded  or  failed.  Set  this  parameter  to  0  for 
successful  operations.  For  failed  operations,  set  the  error  code  appropriate  for 
the  failure.  For  canceled  operations  (for  example,  when  the  ICM  calls  your 
component's  ImageCodecFl  ush  (11-708)  function),  set  this  parameter  to  -1. 

fl  ag 

Completion  flags  (see  below).  Note  that  you  may  set  more  than  one  of  these 
flags  to  1. 
compl eti onRtn 

A  pointer  to  an  ICMCompl  eti  onProcRecord  (IV-2279)  structure.  That  structure 
identifies  the  application's  completion  function  and  contains  a  reference 
constant  associated  with  the  frame.  Your  component  obtains  this  structure  as 
part  of  the  CodecDecompressParams  (IV-2190)  structure  provided  by  the  Image 
Compression  Manager  at  the  start  of  the  decompression  operation. 

flag  Constants 

codecCompl eti on Source 

Your  component  is  done  with  the  source  buffer.  Set  this  flag  to  1  when  you  are 
done  with  the  processing  associated  with  the  source  buffer. 
codecCompl eti onDest 

Your  component  is  done  with  the  destination  buffer.  Set  this  flag  to  1  when  you 
are  done  with  the  processing  associated  with  the  destination  buffer. 


seqlD, 
err , 
fl  ag , 

compl eti onRtn  ); 
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ICMDecompressCompleteS 


codecCompl etionDontUnshield 

Set  this  flag  to  1  when  you  do  not  want  the  ICM  to  unshield  the  cursor  as  it 
normally  would.  Only  codecs  that  are  completely  managing  the  cursor 
themselves  should  set  this  flag.  See  "Hardware  Cursors"  in  Inside  Macintosh: 
QuickTime  (listed  in  the  bibliography)  for  more  information. 

Discussion 

Your  component  must  call  this  function  at  the  end  of  decompression  operations. 

Special  Considerations 

Prior  to  QuickTime  2.0,  decompressor  components  called  the  application's 
completion  function  directly.  For  compatibility,  that  method  is  still  supported 
except  for  scheduled  asynchronous  decompression  operations,  which  must  use  the 
ICMDecompressCompl  ete  call.  Newer  decompressors  should  always  use 
ICMDecompressCompl  ete  rather  than  calling  the  completion  function  directly, 
regardless  of  the  type  of  decompression  operation. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Image  Compression  Manager  Utility  Functions" 
(V-2799) 

See  Also 

See  ICMDecompressCompleteS  (11-672). 


ICMDecompressCompleteS 


Undocumented 


OSErr  ICMDecompressCompleteS  ( 
ImageSequence 
OSErr 
short 

ICMCompl etionProcRecordPtr 


seqlD , 
err , 
fl  ag , 

compl eti onRtn  ) ; 


seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegl n  (1-238). 


Indicates  whether  the  operation  succeeded  or  failed.  See  "Error  Codes" 
(IV-2663). 
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ICMGetPixelFormatlnfo 


fl  ag 

Undocumented 
compl eti onRtn 

A  pointer  to  an  ICMCompl  eti  onProcRecord  (IV-2279)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flag  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


ICMGetPixelFormatlnfo 


Retrieves  pixel  format  information. 

OSErr  ICMGetPixelFormatlnfo  ( 

OSType  Pixel  Format, 

ICMPixel FormatlnfoPtr  thelnfo  ); 


Pi xel Format 

A  constant  that  identifies  the  format;  see  "Pixel  Formats"  (IV-2686). 
thelnfo 

A  pointer  to  your  ICMPixel  Format  Info  (IV-2282)  structure  in  which  information 
is  returned.  You  should  initialize  the  si  ze  field  of  this  structure  with 
si  zeof  ( I  CM  Pi  xel  Format  Inf  o).  The  function  will  not  copy  more  than  this  number 
of  bytes  into  the  structure.  On  return,  the  size  field  contains  the  actual  size  of 
the  data  structure.  If  this  amount  is  greater  the  size  you  passed  in,  that  means 
you  didn't  retrieve  all  of  the  information. 


function  result  Returns  cDepthErrifthepixelformatisnotvalid.Forothererrors,see 
"Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  ImageCompressi  on .  h 
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ICMSequenceGetChainMember 


Related  Java  Methods 

qui ckti me . std . i mage . ICMPi xel Format  Info .isValidPixel Format! ) , 
qui ckti me . std . i mage . ICMPi xel Format  Info . get Pi xel Format  Info! ) 


See  Also 

For  the  corresponding  set  function,  see  ICMSetPixel  Formatlnfo  (11-678). 


ICMSequenceGetChainMember 


Undocumented 

OSErr  ICMSequenceGetChainMember  ( 
ImageSequence  seqlD, 

ImageSequence  *retSeqID, 

1 ong  f 1 ags  ) ; 


seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi n  (1-238). 

retSeqlD 

Undocumented 
fl  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


ICMSequenceGetlnfo 


Gets  multiprocessing  properties  for  compression  and  decompression  sequences. 

OSErr  ICMSequenceGetlnfo  ( 

ImageSequence  seqlD, 

OSType  which, 
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ICMSequenceLockBits 


void  *data  ); 

seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi  n  (1-238). 

whi  ch 

A  constant  (see  below)  that  determines  the  property  to  be  returned. 

data 

The  value  of  the  property  indicated  by  the  which  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

which  Constants 

kICMSequenceTaskWei ght 

The  multiprocessing  task  weight. 
kICMSequenceTaskName 

The  multiprocessing  task  name.  The  task  name  has  no  performance  impact,  but 
it  can  be  helpful  while  debugging. 

Discussion 

This  function  determines  if  ICM  clients  have  requested  that  multiprocessor  tasks 
assisting  compression  and  decompression  operations  use  specific  task  weights  and 
task  names. 

Special  Considerations 

Apple's  multiprocessing  capability  supports  both  cooperatively  scheduled  tasks 
and  preemptively  scheduled  tasks.  The  support  for  preemptively  tasks  allow 
applications  to  create  symmetrically  scheduled  preemptive  tasks  that  can  be  run  on 
a  single  processor  machine,  and  will  take  full  advantage  of  multiple  processors 
when  they  are  installed. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

See  Also 

For  the  corresponding  set  function,  see  ICMSequenceSetlnfo  (11-676). 


ICMSequenceLockBits 

Undocumented 


Inside  QuickTime:  Function  l-Q 


11-675 


ICMSequenceSetlnfo 


OSErr  ICMSequenceLockBi ts  ( 
ImageSequence  seqlD, 

PixMapPtr  dst, 

1 ong  f 1 ags  ) ; 


seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi n  (1-238). 

dst 

A  pointer  to  a  PixMap  (IV-2332)  structure, 
fl  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


ICMSequenceSetlnfo 


Sets  multiprocessing  properties  for  compression  and  decompression  sequences. 

OSErr  ICMSequenceSetlnfo  ( 

ImageSequence  seqlD, 

OSType  which, 

void  *data, 

Si ze  dataSi ze  ) ; 

seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi n  (1-238). 
whi  ch 

A  constant  (see  below)  that  determines  the  property  to  be  set. 

data 

The  value  of  the  property  to  be  set. 


11-676 


Inside  QuickTime:  Function  l-Q 


ICMSequenceUnlockBits 


dataSi ze 

The  length  in  bytes  of  the  data  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

which  Constants 

kICMSequenceTaskWei ght 

The  multiprocessing  task  weight. 
kICMSequenceTaskName 

The  multiprocessing  task  name.  The  task  name  has  no  performance  impact,  but 
it  can  be  helpful  while  debugging. 

Discussion 

This  function  lets  ICM  clients  request  that  multiprocessor  tasks  assisting 
compression  and  decompression  operations  use  specific  task  weights  and  task 
names. 

Special  Considerations 

Apple's  multiprocessing  capability  supports  both  cooperatively  scheduled  tasks 
and  preemptively  scheduled  tasks.  The  support  for  preemptively  tasks  allow 
applications  to  create  symmetrically  scheduled  preemptive  tasks  that  can  be  run  on 
a  single  processor  machine,  and  will  take  full  advantage  of  multiple  processors 
when  they  are  installed. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

See  Also 

For  the  corresponding  get  function,  see  ICMSequenceGetlnfo  (11-674). 


ICMSequenceUnlockBits 


Undocumented 

OSErr  ICMSequenceUnlockBits  ( 

ImageSequence  seqlD, 

long  flags  ); 

seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi  n  (1-238). 


Inside  QuickTime:  Function  l-Q 


11-677 


ICMSetPixelFormatlnfo 


fl  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


ICMSetPixelFormatlnfo 

Lets  you  define  your  own  pixel  format. 

OSErr  ICMSetPixelFormatlnfo  ( 

OSType  Pi xel Format , 

ICMPi xel FormatlnfoPtr  thelnfo  ); 

Pi xel Format 

A  pixel  format  constant.  See  "Pixel  Formats"  (IV-2686). 
thelnfo 

A  pointer  to  an  ICMPi  xel  Format  Info  (IV-2282)  structure  containing  a  definition 
of  the  new  pixel  format. 

function  result  Returns  paramErr  if  the  format  is  already  defined.  See  "Error  Codes" 
(IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Related  Java  Methods 

qui ckti me . std . i mage . ICMPi xel Format  Info . set Pi xel Formatlnfot ) 

See  Also 

For  the  corresponding  get  function,  see  ICMGetPixel  Formatlnfo  (11-673). 
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ICMShieldSequenceCursor 


ICMShieldSequenceCursor 


Hides  the  cursor  during  decompression  operations. 

OSErr  ICMShieldSequenceCursor  ( 

ImageSequence  seqlD  ); 

seqlD 

The  unique  sequence  identifier,  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi  n  (1-238),  for  which  to  shield  the  cursor. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

For  correct  image  display  behavior,  the  cursor  must  be  shielded  (hidden)  during 
decompression.  By  default,  the  Image  Compression  Manager  handles  the  cursor  for 
you,  hiding  it  at  the  beginning  of  a  decompression  operation  and  revealing  it  at  the 
end.  With  scheduled  asynchronous  decompression,  however,  the  ICM  cannot  do  as 
precise  a  job  of  managing  the  cursor,  because  it  does  not  know  exactly  when 
scheduled  operations  actually  begin  and  end.  While  the  ICM  can  still  manage  the 
cursor,  it  must  hide  the  cursor  when  each  request  is  queued,  rather  than  when  the 
request  is  serviced.  This  may  result  in  the  cursor  remaining  hidden  for  long  periods 
of  time.  To  achieve  better  cursor  behavior,  you  can  choose  to  manage  the  cursor  in 
your  decompressor  component.  If  you  so  choose,  you  can  use  this  function  to  hide 
the  cursor;  the  ICM  displays  the  cursor  when  you  call  ICMDecompressCompl  ete 
(11-671).  In  this  manner,  the  cursor  is  hidden  only  when  your  component  is 
decompressing  and  displaying  the  frame. 

Special  Considerations 

This  function  may  be  called  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Image  Compression  Manager  Utility  Functions" 

(V- 2799) 

Related  Java  Methods 

qui cktime . std . image . DSequence . shi el dCursor( ) 


Inside  QuickTime:  Function  l-Q 
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IDHCancelNotification 


IDHCancelNotification 


Undocumented 

ComponentResul t  IDHCancelNotification  ( 
Componentlnstance  idh 

IDHNoti ficati onID  noti ficati onID  ); 


i  dh 

Undocumented 
noti fi cati onID 
Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  IsochronousDataHandl  er.  h 


IDHCancelPendinglO 


Undocumented 

ComponentResul t  IDHCancelPendinglO  ( 
Componentlnstance  idh 

IDHParameterBl ock  *pb  ); 


i  dh 

Undocumented 

pb 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  IsochronousDataHandl  er.  h 
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Inside  QuickTime:  Function  l-Q 


IDHCloseDevice 


IDHCloseDevice 


Undocumented 

ComponentResul t  IDHCloseDevice  ( 

Componentlnstance  idh  ); 

i  dh 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  IsochronousDataHandl  er .  h 


IDHDisposeNotification 


Undocumented 

ComponentResul t  IDHDisposeNotification  ( 
Componentlnstance  idh 

IDHNoti f i cati onID  noti fi cati onID  ); 


i  dh 

Undocumented 
noti fi cati onID 
Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  IsochronousDataHandl  er .  h 


IDHGetDeviceClock 

Undocumented 

ComponentResul t  IDHGetDeviceClock  ( 


Inside  QuickTime:  Function  l-Q 
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IDHGetDeviceConfiguration 


Componentlnstance  idh 

Component  *cl ock  ) ; 


i  dh 

Undocumented 
cl  ock 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  IsochronousDataHandl  er.  h 


IDHGetDeviceConfiguration 


Undocumented 

ComponentResul t  IDHGetDeviceConfiguration  ( 
Componentlnstance  idh 
QTAtomSpec  *confi gurati onID  ); 


i  dh 

Undocumented 
confi gurati onID 
Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  IsochronousDataHandl  er.  h 


IDHGetDeviceControl 


Undocumented 

ComponentResul t  IDHGetDeviceControl  ( 
Componentlnstance  idh 
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Inside  QuickTime:  Function  l-Q 


IDHGetDeviceList 


Componentlnstance  *devi ceControl  ); 
i  dh 

Undocumented 
devi ceControl 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  IsochronousDataHandl  er .  h 


IDHGetDeviceList 


Undocumented 

ComponentResul t  IDHGetDeviceList  ( 
Componentlnstance  idh 

QTAtomContai ner  *deviceList  ); 


i  dh 

Undocumented 
devi  ceLi  st 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  IsochronousDataHandl  er  .  h 


IDHGetDeviceStatus 


Undocumented 

ComponentResul t  IDHGetDeviceStatus  ( 
Componentlnstance  idh 

const  QTAtomSpec  *conf igurati onID 


Inside  QuickTime:  Function  l-Q 
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IDHNewNotification 


IDHDevi ceStatus  *status  ); 

i  dh 

Undocumented 
confi gurati onID 
Undocumented 
status 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  IsochronousDataHandl  er.  h 

IDHNewNotification 

Undocumented 

ComponentResul t  IDHNewNotification  ( 

Componentlnstance  idh 

IDHDevicelD  devicelD 

IDHNotificationProc  notificationProc 

void  *userData 

IDHNoti fi cati onID  *notifi cati onID  ); 

i  dh 

Undocumented 
devi celD 

Undocumented 
noti f i cati onProc 
Undocumented 
userData 

Undocumented 
noti fi cati onID 
Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


11-684 


Inside  QuickTime:  Function  l-Q 


IDHNotifyMeWhen 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  IsochronousDataHandl  er .  h 


IDHNotifyMeWhen 


Undocumented 

ComponentResul t  IDHNotifyMeWhen  ( 

Componentlnstance  idh 

IDHNoti f i cati onID  noti fi cati onID 

IDHEvent  events  ); 

i  dh 

Undocumented 
noti fi cati onID 
Undocumented 
events 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  IsochronousDataHandl  er  .  h 


IDHOpenDevice 


Undocumented 

ComponentResul t  IDHOpenDevice  ( 
Componentlnstance  idh 

UInt32  permissions  ); 


i  dh 

Undocumented 
permi ssi ons 

Undocumented 


Inside  QuickTime:  Function  l-Q 
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IDHRead 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  IsochronousDataHandl  er.  h 


IDHRead 


Undocumented 

ComponentResul t  IDHRead  ( 

Componentlnstance  idh 

IDHParameterBl ock  *pb  ); 

i  dh 

Undocumented 

pb 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  IsochronousDataHandl  er.  h 


IDHReleaseBuffer 


Undocumented 

ComponentResul t  IDHReleaseBuffer  ( 
Componentlnstance  idh 

IDHParameterBl ock  *pb  ); 


i  dh 

Undocumented 


pb 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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Inside  QuickTime:  Function  l-Q 


IDHSetDeviceConfiguration 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  IsochronousDataHandl  er .  h 


IDHSetDeviceConfiguration 

Undocumented 

ComponentResul t  IDHSetDeviceConfiguration  ( 

Componentlnstance  idh 

const  QTAtomSpec  *conf igurati onID  ); 

i  dh 

Undocumented 
conf i gurati onID 
Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  IsochronousDataHandl  er  .  h 


IDHUpdateDeviceList 


Undocumented 

ComponentResul t  IDHUpdateDeviceList  ( 
Componentlnstance  idh 

QTAtomContai ner  *deviceList  ); 


i  dh 

Undocumented 
devi  ceLi  st 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Inside  QuickTime:  Function  l-Q 


11-687 


IDHWrite 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  IsochronousDataHandl  er.  h 


IDHWrite 


Undocumented 

ComponentResul t  IDHWrite  ( 
Componentlnstance  idh 

IDHParameterBl ock  *pb  ); 


i  dh 

Undocumented 

pb 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  IsochronousDataHandl  er.  h 


ImageCodecBandCompress 


Asks  your  component  to  compress  an  image  or  a  band  of  an  image. 

ComponentResul t  ImageCodecBandCompress  ( 

Componentlnstance  ci  , 

CodecCompressParams  *params  ); 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

params 

A  pointer  to  a  CodecCompressParams  (IV-2184)  structure.  The  Image 
Compression  Manager  places  the  appropriate  parameter  information  in  that 
structure. 
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Inside  QuickTime:  Function  l-Q 


ImageCodecBandDecompress 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  image  being  compressed  may  be  part  of  a  sequence. 

Special  Considerations 

Only  compressors  receive  this  request. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 


ImageCodecBandDecompress 


Asks  your  component  to  decompress  a  frame. 

ComponentResul t  ImageCodecBandDecompress  ( 
Componentlnstance  ci  , 

CodecDecompressParams  *params  ); 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
params 

A  pointer  to  a  CodecDecompressParams  (IV-2190)  structure.  The  Image 
Compression  Manager  places  the  appropriate  parameter  information  in  that 
structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

For  scheduled  asynchronous  decompression  operations,  the  Image  Compression 
Manager  supplies  a  reference  to  an  ICMFrameT i meRecord  (IV-2281)  structure  in  this 
function's  CodecDecompressParams  (IV-2190)  structure  parameter.  The 
ICMFrameTi meRecord  structure  contains  time  information  governing  the  scheduled 
decompression  operation,  including  the  time  at  which  the  frame  must  be  displayed. 
For  synchronous  or  immediate  asynchronous  decompress  operations,  the  frame 
time  is  set  to  NIL. 

When  your  component  has  finished  the  decompression  operation,  it  must  call  the 
completion  function.  In  the  past,  for  asynchronous  operations,  your  component 
called  that  function  directly.  For  scheduled  asynchronous  decompression 


Inside  QuickTime:  Function  l-Q 
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ImageCodecBeginBand 


operations,  your  component  should  call  ICMDecompressCompl  ete  (11-671). 

If  your  component  sets  the  codecCanAsyncWhen  flag  in  predecompress  but  cannot 
support  scheduled  asynchronous  decompression  for  a  given  frame,  it  must  return 
an  error  code  of  codecCantWhenErr.  If  your  component's  queue  is  full,  it  should 
return  an  error  code  of  codecCantQueueErr.  Only  decompressors  receive  these 
requests. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.  h 


ImageCodecBeginBand 


Called  before  drawing  a  band  or  frame;  it  allows  your  image  decompressor 
component  to  save  information  about  a  band  before  decompressing  it. 

ComponentResul t  ImageCodecBeginBand  ( 

Componentlnstance  ci  , 

CodecDecompressParams  *params, 

I mageSubCodec Decompress  Record  *drp , 

1 ong  f 1 ags  ) ; 


ci 

An  image  codec  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
params 

A  pointer  to  a  CodecDecompressParams  (IV-2190)  structure. 

drp 

A  pointer  to  an  ImageSubCodecDecompressRecord  (IV-2289)  structure, 
fl  ags 

Currently  unused;  set  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  image  decompressor  component  receives  the  address  of  the  destination  pixel 
map  in  the  baseAddr  field  of  the  drp  parameter.  This  address  includes  an  adjustment 
for  the  offset.  Note  that  if  the  bit  depth  of  the  pixel  map  is  less  than  8,  your  image 
decompressor  component  must  adjust  for  the  bit  offset. 
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ImageCodecBusy 


The  codecData  field  of  the  d  r p  parameter  contains  a  pointer  to  the  compressed  video 
data.  The  userDecompressRecord  field  of  the  drp  parameter  contains  a  pointer  to 
storage  for  the  decompression  operation.  The  storage  is  allocated  by  the  base  image 
decompressor  after  it  calls  the  ImageCodecInl  ti  al  i  ze  (11-724)  function.  The  size  of 
the  storage  is  determined  by  the  decompressRecordSi  ze  field  of  the 
ImageSubCodecDecompressCapabi  1  i  ti  es  (IV-2288)  structure  that  is  returned  by 
ImageCodecInitialize  (11-724).  Your  image  decompressor  component  should  use 
this  storage  to  store  any  additional  information  needed  about  the  frame  in  order  to 
decompress  it. 

Changes  your  image  decompressor  component  makes  to  the 

ImageSubCodecDecompressRecord  or  CodecDecompressParams  structures  are  preserved 
by  the  base  image  decompressor.  For  example,  if  your  component  does  not  need  to 
decompress  all  of  the  data,  it  can  change  the  pointer  to  the  data  to  be  decompressed 
that  is  stored  in  the  codecData  field  of  the  ImageSubCodecDecompressRecord  structure. 

Special  Considerations 

Your  component  must  implement  this  function.  Also,  the  base  image  decompressor 
never  calls  ImageCodecBegi  nBand  at  interrupt  time.  If  your  component  supports 
asynchronous  scheduled  decompression,  it  may  receive  more  than  one 
ImageCodecBegi  nBand  call  before  receiving  an  ImageCodecDrawBand  (11-697)  call. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Base  Image  Decompressor  Functions"  (V-2805) 


ImageCodecBusy 


Lets  your  component  report  whether  it  is  performing  an  asynchronous  operation. 

ComponentResul t  ImageCodecBusy  ( 

Componentlnstance  ci  , 

ImageSequence  seq  ); 


An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
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ImageCodecCancelTrigger 


seq 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi n  (1-238). 

function  result  Your  component  should  return  a  result  code  value  of  1  if  an 

asynchronous  operation  is  in  progress;  it  should  return  a  result  code 
value  of  0  if  the  component  is  not  performing  an  asynchronous 
operation.  You  can  indicate  an  error  by  returning  a  negative  result 
code.  See  "Error  Codes"  (IV-2663). 

Special  Considerations 

Both  compressors  and  decompressors  may  receive  this  request. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.  h 


ImageCodecCancelT  rigger 


Cancels  an  image  codec's  ImageCodecTimeTriggerProc  (III— 2096)  callback. 

ComponentResul t  ImageCodecCancelTrigger  ( 

Componentlnstance  ci  ); 


ci 

An  image  codec  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCodec. h 


ImageCodecCreateStandardParameterDialog 


Creates  a  parameters  dialog  box  for  a  specified  effect. 

ComponentResul t  ImageCodecCreateStandardParameterDial og  ( 
Componentlnstance  ci  , 
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ImageCodecCreateStandardParameterDialog 


QTAtomContai ner 
QTAtomContai ner 
QTParameterDi al ogOpti ons 
Di al ogPtr 
short 

QTParameterDi al og 


parameterDescri pti on , 
parameters , 
di al ogOpti ons  , 
exi sti ngDi al og  , 
exi  sti  ngllserltem, 
*createdDi al og  ); 


ci 

An  effects  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131).  The  dialog  box  that 
is  created  will  allow  the  user  to  specify  the  parameters  of  this  effect. 
parameterDescri pti  on 

The  parameter  description  atom  container  for  this  effect.  You  can  obtain  a  valid 
parameter  description  by  calling  ImageCodecGetParameterLi  st  (11-717).  A 
parameter  is  optionally  tweenable  if  defined  as  kAtomlnterpol  atelsOpti  onal  in 
its  parameter  description  atom. 

parameters 

The  atom  container  that  will  receive  the  user's  chosen  parameter  values  once 
the  dialog  has  been  dismissed, 
di al ogOpti ons 

Controls  how  parameters  containing  tween  data  are  presented  in  the  created 
dialog  box.  IfdialogOptions  contains  0,  two  values  are  collected  for  each 
parameter  that  can  be  tweened,  and  the  usual  tweening  operation  will  be 
performed  for  the  duration  of  the  effect  being  controlled.  For  other  values,  see 
below. 

exi sti ngDi al og 

An  existing  dialog  box  that  will  have  the  controls  from  the  standard  parameters 
dialog  box  added  to  it.  Set  this  parameter  to  N I L  if  you  want  this  function  to 
create  a  stand-alone  dialog  box. 

exi  sti  ngllserltem 

The  number  of  the  user  item  in  the  existing  dialog  box  that  should  be  replaced 
with  controls  from  the  standard  parameter  dialog  box.  You  should  only  pass  a 
value  to  this  parameter  if  the  exi  sti  ngDi  a  1  og  parameter  is  not  NIL. 
createdDi al og 

On  return,  a  reference  to  the  dialog  created  and  displayed  by  the  function.  This 
reference  is  required  by  several  other  low-level  effects  functions.  It  will  contain 
a  valid  dialog  identifier  even  if  you  requested  that  the  controls  from  the 
standard  parameter  dialog  box  be  incorporated  into  an  existing  dialog  box. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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ImageCodecCreateStandardParameterDialog 


dialogOptions  Constants 

pdOptionsCollectOneValue 

Only  one  value  can  be  entered  for  parameters  that  are  optionally  tweenable. 
This  means  that  optionally-tweened  parameters  will  not  be  tweened. 

pdOptionsAll owOpti onal Interpol  at  ions 

The  user  interface  for  optionally-tweened  parameters  will  be  constructed  to 
take  tweened  values.  Setting  this  flag  selects  the  "advanced"  user  interface 
mode.  If  the  user  interface  supports  this  mode  of  operation,  then  a  tween  value 
can  be  entered  for  this  parameter  when  the  user  interface  is  in  the  mode.  An 
example  of  an  advanced  mode  is  the  standard  parameters  dialog  box;  if  you 
hold  down  the  option  key  while  selecting  an  effect,  any  parameters  that  have 
the  kAtom  Interpol  a  te  Is  Opt  i  onal  flag  set  will  allow  a  tween  value  to  be  entered. 

Discussion 

This  is  a  low-level  function  that  can  be  used  to  create  a  standard  parameter  dialog 
box  for  a  specified  effect,  allowing  the  user  to  set  the  parameter  values  for  the  effect. 
You  can  optionally  request  that  the  controls  from  the  dialog  box  be  included  within 
a  dialog  box  of  the  calling  application.  The  following  sample  code  shows  how  to 
create  a  standard  parameter  dialog  box  and  add  effects  controls: 

//  ImageCodecCreateStandardParameterDial og  coding  example 
//  See  “Discovering  QuickTime,”  page  303 

pMovabl eModal Di al og  =  GetNewDi al og( kExtraDi al ogID ,  NIL,  (Wi ndowPtr ) -1) ; 
if  (pMovabl eModal Di al og  !=  NIL)  { 

ImageCodecCreateStandardParameterDialogt 
complnstance , 
qtacParameterDescription, 
qtacEffectSampl e , 
pdOpti  ons Model DialogBox, 
pMovableModalDialog, 
kExtraUserltemID, 

&1  CreatedDi al ogID) ; 

ShowWi ndow( pMovabl eModal Di a  1 og ) ; 

SelectWindow(pMovableModalDialog); 

SetPort(pMovableModalDialog) ; 

} 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


11-694 


Inside  QuickTime:  Function  l-Q 


ImageCodecDismissStandardParameterDialog 


Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Low-Level  Effects  Functions"  (V-2898) 

See  Also 

The  high-level  version  of  this  function  is  QTCreateStandardParameterDi  al  og 
(11-1161). 

ImageCodecDismissStandardParameterDialog 


Retrieves  values  from  a  standard  parameter  dialog  box  created  by  the  low-level 
ImageCodecCreateStandardParameterDi  al  og  (11-692)  function,  then  closes  the  dialog 
box. 

ComponentResul t  ImageCodecDi smi ssStandardParameterDi al og  ( 

Componentlnstance  ci  , 

QTParameterDi al og  createdDi al og  ); 


ci 

An  effect  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131).  This  must  be  the 
instance  passed  to  ImageCodecCreateStandardParameterDi  al  og  (11-692)  to  create 
the  dialog  box. 

createdDi al og 

A  reference  to  the  dialog  box  created  by  the  call  to 
ImageCodecCreateStandardParameterDi al og. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  should  be  called  after  the  ImageCodecIsStandardParameterDi  alogEvent 
(11-726)  function  returns  codecParameterDi  al  ogConf  i  rm  or  userCancel  edErr,  which 
indicate  that  the  user  has  dismissed  the  dialog  box.  The  function  dismisses  the 
dialog  box,  deallocating  any  memory  allocated  during  the  call  to 
ImageCodecCreateStandardParameterDi  al  og  (11-692). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Low-Level  Effects  Functions"  (V-2898) 
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ImageCodecDisposelmageGWorld 


ImageCodecDisposelmageGWorld 


Disposes  of  an  image  graphics  world  associated  with  an  image  codec. 

ComponentResul t  ImageCodecDisposelmageGWorld  ( 

Componentlnstance  ci  , 

GWorl dPtr  theGW  ) ; 


ci 

An  image  codec  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

theGW 

A  pointer  to  a  CGraf  Port  (IV-2168)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.  h 


ImageCodecDisposeMemory 


Disposes  codec-allocated  memory. 

ComponentResul t  ImageCodecDisposeMemory  ( 
Componentlnstance  ci  , 

Ptr  data  ) ; 


ci 

An  image  compressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

data 

A  pointer  to  the  previously  allocated  memory  block. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  component  receives  the  ImageCodecDi  sposeMemory  request  whenever  an 
application  calls  CDSequenceDi  sposeMemory  (1-77). 
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ImageCodecDrawBand 


Special  Considerations 

When  a  codec  instance  is  closed,  it  must  ensure  that  all  blocks  allocated  by  that 
instance  are  disposed  and  call  ICMMemoryDi sposedProc  (III— 2092). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Base  Image  Decompressor  Functions"  (V-2805) 


ImageCodecDrawBand 


Decompresses  a  band  or  frame. 

ComponentResul t  ImageCodecDrawBand  ( 

Componentlnstance  ci  , 

ImageSubCodecDecompressRecord  *drp  ); 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

drp 

A  pointer  to  an  ImageSubCodecDecompressRecord  (IV-2289)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

When  the  base  image  decompressor  calls  your  image  decompressor  component's 
ImageCodecDrawBand  function,  your  component  must  perform  the  decompression 
specified  by  the  fields  of  the  ImageSubCodecDecompressRecord  (IV-2289)  structure. 
The  structure  includes  any  changes  your  component  made  to  it  when  performing 
the  ImageCodecBeginBand  (11-690)  function.  If  your  component  supports 
asynchronous  scheduled  decompression,  it  may  receive  more  than  one 
ImageCodecBegi  nBand  call  before  receiving  an  ImageCodecDrawBand  call. 

Special  Considerations 

Your  component  must  implement  this  function.  If  the 
ImageSubCodecDecompressRecord  structure  specifies  a  progress  function  or 
data-loading  function,  the  base  image  decompressor  never  calls  this  function  at 
interrupt  time.  If  not,  the  base  image  decompressor  may  call  this  function  at 
interrupt  time. 


Inside  QuickTime:  Function  l-Q 
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ImageCodecDroppingFrame 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.  h 

Programming  summary:  "Base  Image  Decompressor  Functions"  (V-2805) 


ImageCodecDroppingFrame 


Undocumented 

ComponentResul t  ImageCodecDroppingFrame  ( 

Componentlnstance  ci  , 

const  ImageSubCodecDecompressRecord  *drp  ); 


ci 

An  image  codec  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

drp 

A  pointer  to  an  ImageSubCodecDecompressRecord  (IV-2289)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec. h 


ImageCodecEffectBegin 

Undocumented 

ComponentResul t  ImageCodecEffectBegin  ( 

Componentlnstance  effect, 

CodecDecompressParams  *p, 

EffectsFrameParamsPtr  ePtr  ); 

effect 

An  effect  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
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ImageCodecEffectCancel 


P 

A  pointer  to  a  CodecDecompressParams  (IV-2190)  structure. 

ePtr 

A  pointer  to  a  Effects  FramePa  rams  (IV-2242)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 


ImageCodecEffectCancel 


Undocumented 

ComponentResul t  ImageCodecEffectCancel  ( 

Componentlnstance  effect, 

EffectsFrameParamsPtr  p  ); 

effect 

An  effect  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

P 

A  pointer  to  a  Effects  FramePa  rams  (IV-2242)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 


ImageCodecEffectConvertEffectSourceToFormat 


Undocumented 

ComponentResul t  ImageCodecEffectConvertEffectSourceToFormat  ( 
Componentlnstance  effect, 

Ef f ectSourcePtr  sourceToConvert, 

ImageDescri pti onHandl e  requestedDesc  ); 
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ImageCodecEffectDisposeSMPTEFrame 


effect 

An  effect  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
sourceToConvert 
Undocumented 
requestedDesc 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 


ImageCodecEffectDisposeSMPTEFrame 

Undocumented 

ComponentResul t  ImageCodecEffectDisposeSMPTEFrame  ( 

Componentlnstance  effect, 

SMPTEFrameReference  frameRef  ); 

effect 

An  effect  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

frameRef 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCodec.  h 


ImageCodecEffectGetSpeed 

Undocumented 
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ImageCodecEffectPrepareSMPTEFrame 


ComponentResul t  ImageCodecEf f ectGetSpeed  ( 

Componentlnstance  effect, 

QTAtomContai ner  parameters. 

Fixed  *pFPS  ); 

effect 

An  effect  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

parameters 

Undocumented 

pFPS 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 


ImageCodecEffectPrepareSMPTEFrame 


Undocumented 

ComponentResul t  ImageCodecEffectPrepareSMPTEFrame  ( 

Componentlnstance  effect, 

PixMapPtr  destPixMap, 

SMPTEFrameReference  *returnValue  ); 

effect 

An  effect  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

destPi xMap 

Undocumented 
returnVal ue 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 
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ImageCodecEffectRenderFrame 


Programming  Info 

C  interface  file:  ImageCodec.  h 


ImageCodecEffectRenderFrame 


Undocumented 

ComponentResul t  ImageCodecEffectRenderFrame  ( 

Componentlnstance  effect, 

EffectsFrameParamsPtr  p  ); 

effect 

An  effect  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

P 

A  pointer  to  an  EffectsFrameParams  (IV-2242)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.  h 


ImageCodecEffectRenderSMPTEFrame 


Undocumented 

ComponentResul t  ImageCod 
Componentlnstance 
Pi xMapPtr 

SMPTEFrame Reference 
Fi  xed 
Fi  xed 
Rect 

Matri xRecord 
SMPTEWi peType 
1  ong 
1  ong 

SMPTEF1 ags 
Fi  xed 
1  ong 


EffectRenderSMPTEFrame  ( 
effect , 
destPi xMap , 
f rameRef , 

effect Per cent age  Even  , 
effectPercentageOdd , 
*pSourceRect , 

*pMatri x , 
effectNumber , 
xRepeat , 
yRepeat , 
fl ags , 
penWi dth , 
strokeVal ue  ) ; 
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ImageCodecEffectRenderSMPTEFrame 


effect 

An  effect  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
destPi xMap 

Undocumented 
f rameRef 

Undocumented 
effectPercentageEven 
Undocumented 
ef fectPercentageOdd 
Undocumented 
pSourceRect 

Undocumented 
pMatri x 

Undocumented 
ef fectNumber 

Undocumented 

xRepeat 

Undocumented 

yRepeat 

Undocumented 
fl  ags 

Undocumented 
penWi dth 

Undocumented 
strokeVal ue 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCodec.h 
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ImageCodecEffectSetup 


ImageCodecEffectSetup 


Undocumented 

ComponentResul t  ImageCodecEffectSetup  ( 

Componentlnstance  effect, 

CodecDecompressParams  *p  ); 

effect 

An  effect  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 


P 

A  pointer  to  a  CodecDecompressParams  (IV-2190)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.  h 


ImageCodecEndBand 


Notifies  your  image  decompressor  component  that  decompression  of  a  band  has 
finished  or  that  it  was  terminated  by  the  Image  Compression  Manager. 

ComponentResul t  ImageCodecEndBand  ( 


Componentlnstance  ci  , 

Images ubCodec Decompress  Record  *drp , 
OSErr  result, 

1  ong  f 1 ags  ) ; 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

drp 

A  pointer  to  an  ImageSubCodecDecompressRecord  (IV-2289)  structure, 
resul t 

A  result  code, 
fl  ags 

Currently  unused;  set  to  0. 
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ImageCodecExtractAndCombineFields 


function  result  Returns  noErr  if  the  band  or  frame  was  drawn  successfully.  If  it  is 
any  other  value,  the  band  or  frame  was  not  drawn.  See  "Error 
Codes"  (IV-2663). 

Discussion 

Your  image  decompressor  component  is  not  required  to  implement  this  function. 
After  your  image  decompressor  component  handles  a  call  to  this  function,  it  can 
perform  any  tasks  that  are  required  when  decompression  is  finished,  such  as 
disposing  of  data  structures  that  are  no  longer  needed.  Because  this  function  can  be 
called  at  interrupt  time,  your  component  cannot  use  it  to  dispose  of  data  structures; 
this  must  occur  after  handling  the  function. 

Special  Considerations 

The  base  image  decompressor  may  call  ImageCodecEndBand  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Base  Image  Decompressor  Functions"  (V-2805) 


ImageCodecExtractAndCombineFields 


Performs  field  operations  on  video  data. 


ComponentResul t  ImageCodecExtractAndCombi neFi el ds  ( 


Componentlnstance 
1  ong 
voi  d 
1  ong 

ImageDescri pti onHandl e 
voi  d 
1  ong 

ImageDescri pti onHandl e 
voi  d 
1  ong 

ImageDescri pti onHandl e 


ci  , 

fi  el  d FI  ags  , 
*datal , 
dataSi zel , 
descl , 

*data2 , 
dataSi ze2 , 
desc2 , 

*outputData , 
*outDataSi ze , 
descOut  ); 


An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef aul  tComponent  (11-1131). 
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ImageCodecExtractAndCombineFields 


f  i  el d FI ags 

Flags  (see  below)  that  specify  the  operation  to  be  performed.  A  correctly 
formed  request  will  specify  two  input  fields,  mapping  one  to  the  odd  output 
field  and  the  other  to  the  even  output  field, 
datal 

A  pointer  to  a  buffer  containing  the  compressed  image  data  for  the  first  input 
field. 

dataSi zel 

The  size  of  the  datal  buffer, 
descl 

An  ImageDescri  pti  on  (IV-2285)  structure  describing  the  format  and 
characteristics  of  the  data  in  the  datal  buffer. 
data2 

A  pointer  to  a  buffer  containing  the  compressed  image  data  for  the  second 
input  field.  Set  to  N I L  if  the  requested  operation  uses  only  one  input  frame. 

dataSi ze2 

The  size  of  the  data 2  buffer.  Set  to  0  if  the  requested  operation  uses  only  one 
input  frame. 
desc2 

An  ImageDescri  pti  on  (IV-2285)  structure  describing  the  format  and 
characteristics  of  the  data  in  the  data2  buffer.  Set  to  N I L  if  the  requested 
operation  uses  only  one  input  frame. 
outputData 

A  pointer  to  a  buffer  to  receive  the  resulting  frame. 
outDataSi ze 

On  output  this  parameter  returns  the  actual  size  of  the  new  compressed  image 
data. 
descOut 

The  desired  format  of  the  resulting  frames.  Typically  this  is  the  same  format 
specified  by  the  descl  and  desc2  parameters. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

fieldFlags  Constants 

evenFieldlToEvenFieldOut 

Maps  the  even  field  specified  by  the  datal  parameter  to  the  even  output  field. 
evenFieldlToOddFieldOut 

Maps  the  even  field  specified  by  the  datal  parameter  to  the  odd  output  field. 
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ImageCodecExtractAndCombineFields 


oddFi  el  dlToEvenFi  el  dOut 

Maps  the  odd  field  specified  by  the  datal  parameter  to  the  even  output  field. 
oddFi el dlToOddFi el dOut 

Maps  the  odd  field  specified  by  the  datal  parameter  to  the  odd  output  field. 
evenFi  el  d2To EvenFi  el  dOut 

Maps  the  even  field  specified  by  the  data2  parameter  to  the  even  output  field. 
evenFi el d2To0ddFi el dOut 

Maps  the  even  field  specified  by  the  data2  parameter  to  the  odd  output  field. 
oddFi  el  d2To EvenFi  el  dOut 

Maps  the  odd  field  specified  by  the  data2  parameter  to  the  even  output  field. 
oddFi el d2To0ddFi el dOut 

Maps  the  odd  field  specified  by  the  data2  parameter  to  the  odd  output  field. 

Discussion 

This  function  allows  fields  from  two  separate  images,  compressed  in  the  same 
format,  to  be  combined  into  a  new  compressed  frame.  Typically  the  operation 
results  in  an  image  of  identical  quality  to  the  source  images.  Fields  of  a  single  image 
may  also  be  duplicated  or  reversed  by  this  function.  The  component  selector  for  this 
function  is: 

klmageCodecExtractAndCombi neFi el dsSel  ect  =  0x0015 

Special  Considerations 

This  codec  routine  implements  the  functionality  of  the 

ImageFi  el  dSequenceExtractCombi  ne  (11-747)  function.  If  your  codec  is  capable  of 
separately  compressing  both  fields  of  a  video  frame,  you  should  incorporate 
support  for  this  function.  Your  codec  must  ensure  that  it  understands  the  image 
formats  specified  by  descl  and  desc2  parameters,  as  these  may  not  be  the  same  as 
the  codec's  native  image  format.  The  image  format  specified  by  the  descOut 
parameter  will  be  the  same  as  the  codec's  native  image  format. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Base  Image  Decompressor  Functions"  (V-2805) 

See  Also 

See  ImageFi  el  dSequenceExtractCombi  ne  (11-747). 


Inside  QuickTime:  Function  l-Q 
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ImageCodecFlush 


ImageCodecFlush 


Empties  an  image  decompressor  component's  input  queue  of  pending  scheduled 
frames. 

ComponentResul t  ImageCodecFlush  ( 

Componentlnstance  ci  ); 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  component  receives  the  ImageCodecFlush  function  whenever  the  Image 
Compression  Manager  needs  to  cancel  the  display  of  all  scheduled  frames.  Your 
decompressor  should  empty  its  queue  of  scheduled  asynchronous  decompression 
requests.  For  each  request,  your  component  must  call  ICMDecompressCompl  ete 
(11-671).  Be  sure  to  set  the  err  parameter  to  -1,  indicating  that  the  request  was 
canceled.  Also,  you  must  set  both  the  codecCompl  eti  onSource  and 
codecCompl  eti  onDest  flags  to  1. 

Special  Considerations 

Your  component's  ImageCodecFl  ush  function  maybe  called  at  interrupt  time.  Only 
decompressor  components  that  support  scheduled  asynchronous  decompression 
receive  this  call. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Base  Image  Decompressor  Functions"  (V-2805) 


ImageCodecFlushFrame 


Undocumented 

ComponentResul t  ImageCodecFlushFrame  ( 
Componentlnstance  ci  , 

UInt32  f 1 ags  ) ; 
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ImageCodecGetBaseMPWorkFunction 


ci 

An  image  codec  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
fl  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 


ImageCodecGetBaseMPWorkFunction 


Gets  an  image  codec's  ComponentMPWorkFuncti  onProc  (III— 2077)  callback. 


ComponentResul  t  ImageCodecGetBaseMPWorkFuncti  on  ( 
Componentlnstance  ci  , 

ComponentMPWorkFuncti onUPP  *workFuncti on , 

void  **refCon, 

ImageCodecMPDrawBandUPP  drawProc, 

void  *drawProcRefCon  ); 


ci 

An  image  codec  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
workFuncti on 

On  return,  a  pointer  to  a  ComponentMPWorkFuncti  onProc  (III— 2077)  callback. 
refCon 

On  return,  a  handle  to  the  reference  constant  that  is  passed  to  the 
ComponentMPWorkFuncti  onProc  callback. 

drawProc 

An  ImageCodecMPDrawBandProc  (III— 2095)  callback. 
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ImageCodecGetCodecInfo 


drawProcRefCon 

A  pointer  to  a  reference  constant  that  is  passed  to  your 
ImageCodecMPDrawBandProc  callback.  Use  this  parameter  to  point  to  a  data 
structure  containing  any  information  your  function  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 


ImageCodecGetCodecInfo 


Notifies  your  codec  whenever  an  application  calls  GetCodecInfo  (1-385). 

ComponentResul t  ImageCodecGetCodecInfo  ( 

Componentlnstance  cl  , 

Codeclnfo  *1 nfo  ) ; 


cl 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

1  nfo 

A  pointer  to  a  Coded  nfo  (IV-2202)  structure  to  update.  Your  component  should 
report  its  capabilities  by  formatting  the  structure  in  the  location  specified  by 
this  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Both  compressors  and  decompressors  may  receive  this  request. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 


ImageCodecGetCompressedlmageSize 


Notifies  your  codec  whenever  an  application  calls  GetCompressedlmageSi  ze  (1-396). 
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ImageCodecGetCompressionTime 


Component Res ul t  ImageCodecGetCompressedlmageSi ze 


Componentlnstance 
ImageDescri pti onHandl e 
Ptr 
1  ong 

ICMDataProc Record Ptr 
1  ong 


ci  , 
desc , 
data , 

but f erSi ze , 
dataProc, 
*dataSize  ); 


( 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

desc 

A  handle  to  the  ImageDescri  pti  on  (IV-2285)  structure  that  defines  the 
compressed  image  for  the  operation. 

data 

A  pointer  to  the  compressed  image  data, 
but f erSi ze 

The  size  of  the  buffer  to  be  used  by  the  data-loading  function  specified  by  the 
dataProc  parameter.  If  the  application  did  not  specify  a  data-loading  function 
this  parameter  is  NIL. 

dataProc 

A  pointer  to  an  ICMDataProcRecord  structure.  If  the  data  stream  is  not  all  in 
memory  when  the  application  calls  GetCompressedlmageSi  ze  (1-396),  your 
component  may  call  an  application  function  that  loads  more  compressed  data. 
dataSi ze 

A  pointer  to  a  field  that  is  to  receive  the  size,  in  bytes,  of  the  compressed  image. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

Only  decompressors  receive  this  request. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 


ImageCodecGetCompressionTime 


Notifies  your  codec  whenever  an  application  calls  GetCompressi  onT i me  (1-401). 


Inside  QuickTime:  Function  l-Q 
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ImageCodecGetCompressionTime 


ComponentResul t  ImageCo 
Componentlnstance 
Pi xMapHandl e 
const  Rect 
short 
CodecQ 
CodecQ 

unsigned  long 


decGetCompressi onTime  ( 
ci  , 
src , 

*srcRect , 
depth , 

*spati al Qual i ty , 
*temporal Qual i ty , 
*time  ); 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef aul  tComponent  (11-1131). 

src 

A  handle  to  the  source  image.  The  source  image  is  stored  in  a  Pi  xMap  (IV-2332) 
structure.  Applications  may  use  the  time  information  you  return  for  more  than 
one  image.  Consequently,  your  compressor  should  not  consider  the  contents  of 
the  image  when  determining  the  maximum  compression  time.  Rather,  you 
should  consider  only  the  quality  level,  pixel  depth,  and  image  size.  This 
parameter  may  also  be  set  to  N I L.  In  this  case  the  application  has  not  supplied  a 
source  image;  your  component  should  use  the  other  parameters  to  determine 
the  characteristics  of  the  image  to  be  compressed. 
srcRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  defines  the  portion  of  the  source 
image  to  compress, 
depth 

The  depth  at  which  the  image  is  to  be  compressed.  Values  of  1,  2, 4,  8, 16,  24, 
and  32  indicate  the  number  of  bits  per  pixel  for  color  images.  Values  of  33,  34, 
36,  and  40  indicate  1-bit,  2-bit,  4-bit,  and  8-bit  grayscale,  respectively,  for 
grayscale  images, 
spati al Qual i ty 

A  pointer  to  a  field  containing  the  desired  compressed  image  quality  (see 
below).  The  compressor  sets  this  field  to  the  closest  actual  quality  that  it  can 
achieve. 

temporal Qual i ty 

A  pointer  to  a  field  containing  the  desired  sequence  temporal  quality  (see 
below).  The  compressor  sets  this  field  to  the  closest  actual  quality  that  it  can 
achieve. 

time 

A  pointer  to  a  field  to  receive  the  compression  time,  in  milliseconds.  If  your 
component  cannot  determine  the  amount  of  time  required  to  compress  the 
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ImageCodecGetDecompressLatency 


image,  set  this  field  to  0.  Check  to  see  if  the  value  of  this  field  is  N I L  and,  if  so, 
do  not  write  to  location  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

spatialQuality  and  temporalQuality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 
codecNormal Quality 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 

codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field, 
codec Los  si essQual  i  ty 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec .  h 


ImageCodecGetDecompressLatency 


Retrieves  the  video  latency  value  from  a  specified  video  codec. 

ComponentResul t  ImageCodecGetDecompressLatency  ( 
Componentlnstance  ci  , 

TimeRecord  *latency  ); 


A  video  codec  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 


Inside  QuickTime:  Function  l-Q 
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ImageCodecGetMaxCompressionSize 


1  atency 

Pointer  to  a  Ti  me  Record  (IV-2486)  structure  containing  the  latency  time  required 
for  that  codec. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  ImageCodec.h 


ImageCodecGetMaxCompressionSize 


Notifies  your  codec  whenever  an  application  calls  GetMaxCompressi  onSi  ze  (1-420). 


ComponentResul t  ImageCodecGetMaxCompressi onSi ze  ( 
Componentlnstance  cl , 


Pi xMapHandl e 
const  Rect 
short 
CodecQ 
1  ong 


src , 

*srcRect , 
depth , 
qual i ty , 
*size  ); 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef aul  tComponent  (11-1131). 

src 

A  handle  to  the  source  image.  The  source  image  is  stored  in  a  Pi  xMap  (IV-2332) 
structure.  Applications  use  the  size  information  you  return  to  allocate  buffers 
that  may  be  used  for  more  than  one  image.  Consequently,  your  compressor 
should  not  consider  the  contents  of  the  image  when  determining  the  maximum 
compressed  size.  Rather,  you  should  consider  only  the  quality  level,  pixel 
depth,  and  image  size.  This  parameter  may  also  be  set  to  NI L.  In  this  case  the 
application  has  not  supplied  a  source  image;  your  component  should  use  the 
other  parameters  to  determine  the  characteristics  of  the  image  to  be 
compressed. 
srcRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  defines  the  portion  of  the  source 
image  to  compress. 
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depth 

The  depth  at  which  the  image  is  to  be  compressed.  Values  of  1,  2, 4,  8, 16,  24, 
and  32  indicate  the  number  of  bits  per  pixel  for  color  images.  Values  of  33, 34, 
36,  and  40  indicate  1-bit,  2-bit,  4-bit,  and  8-bit  grayscale,  respectively,  for 
grayscale  images, 
quality 

The  desired  compressed  image  quality  (see  below). 

si  ze 

A  pointer  to  a  field  to  receive  the  maximum  size,  in  bytes,  of  the  compressed 
image. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

quality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 

codecNormal Quality 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 
codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field, 
codec Los  si essQual  i  ty 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

Discussion 

The  caller  uses  this  function  to  determine  the  maximum  size  the  data  will  become 
for  a  given  parameter.  Your  component  returns  a  long  integer  indicating  the 
maximum  number  of  bytes  of  compressed  data  that  results  from  compressing  the 
specified  image. 

Special  Considerations 

Only  compressors  receive  this  request. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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ImageCodecGetMaxCompressionSizeWithSources 


Programming  Info 

C  interface  file:  ImageCodec.  h 


ImageCodecGetMaxCompressionSizeWithSources 


Notifies  your  codec  when  an  application  calls  GetCSequenceMaxCompressi  onSi  ze 
(1-405). 


ComponentResul t  ImageCodecGetMaxCompressI onSi zeWi thSources  ( 


Componentlnstance 
Pi xMapHandl e 
const  Rect 
short 
CodecQ 

CDSequenceDataSourcePtr 
1  ong 


c  i  , 
src , 

*srcRect , 
depth , 
qual i ty , 
sourceData , 
*size  ); 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

src 

A  handle  to  the  source  image.  The  source  image  is  stored  in  a  Pi  xMap  (IV-2332) 
structure.  Applications  use  the  size  information  you  return  to  allocate  buffers 
for  more  than  one  image.  Consequently,  your  compressor  should  not  consider 
the  contents  of  the  image  when  determining  the  maximum  compressed  size. 
Rather,  you  should  consider  only  the  quality  level,  pixel  depth,  and  image  size. 
This  parameter  may  also  be  set  to  NIL.  In  this  case  the  application  has  not 
supplied  a  source  image;  your  component  should  use  the  other  parameters  to 
determine  the  characteristics  of  the  image  to  be  compressed. 
srcRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  defines  the  portion  of  the  source 
image  to  compress, 
depth 

The  depth  at  which  the  image  is  to  be  compressed.  Values  of  1,  2, 4,  8, 16,  24, 
and  32  indicate  the  number  of  bits  per  pixel  for  color  images.  Values  of  33,  34, 
36,  and  40  indicate  1-bit,  2-bit,  4-bit,  and  8-bit  grayscale,  respectively,  for 
grayscale  images. 

qual i ty 

The  desired  compression  image  quality. 
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sourceData 

A  pointer  to  a  CDSequenceDataSource  (IV-2165)  structure,  which  contains  a 
linked  list  of  all  data  sources.  Because  each  data  source  contains  a  link  to  the 
next  data  source,  a  codec  can  access  all  data  sources  from  this  structure. 

si  ze 

A  pointer  to  a  field  to  receive  the  maximum  size,  in  bytes,  of  the  compressed 
image. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  caller  uses  this  function  to  determine  the  maximum  size  the  data  will  be 
compressed  to  for  a  given  image  and  set  of  data  sources. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Base  Image  Decompressor  Functions"  (V-2805) 

See  Also 

This  function  is  similar  in  purpose  to  ImageCodecGetMaxCompressi  onSi  ze  (11-714). 
However,  it  also  considers  data  sources  that  the  codec  may  compress  with  the 
image. 


ImageCodecGetParameterList 


Returns  a  parameter  description  atom  container  for  a  specified  effect  component 
instance. 

ComponentResul t  ImageCodecGetParameterList  ( 

Componentlnstance  ci  , 

QTAtomContai ner  *parameterDescriptionHandl e  ); 


ci 

An  effect  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
parameterDescri ption 

The  returned  atom  container  for  this  component  instance. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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ImageCodecGetParameterListHandle 


Discussion 

This  function  returns  the  parameter  description  for  the  effect  specified  by  the 
component  instance  ci,  as  a  handle  containing  an  '  atms '  resource  of  ID  1.  The 
handle  should  be  detached  if  it  has  been  read  in  from  a  resource.  Each  parameter  of 
the  effect  is  described  in  the  parameter  description,  with  details  of  its  name,  type, 
legal  values  and  hints  about  how  a  user  interface  to  the  parameter  should  be 
constructed. 

Special  Considerations 

The  calling  application  is  responsible  for  disposing  of  the  QT  atom  container 
returned  in  parameterDescri  pti  on.  The  application  should  do  this  by  calling 
QTDi  sposeAtomContai  ner  (11-1164)  once  it  has  finished  using  the  parameter 
description. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.  h 

Programming  summary:  "Low-Level  Effects  Functions"  (V-2898) 


ImageCodecGetParameterListHandle 


Returns  a  handle  to  a  Mac  OS  resource  of  type  '  atms ' . 

ComponentResul t  ImageCodecGetParameterLi stHandl e  ( 
Componentlnstance  ci  , 

Handle  *parameterDescriptionHandl e  ); 


ci 

An  effect  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

parameterDescri pti onHandl e 

A  pointer  to  a  handle  to  a  Mac  OS  resource  of  type  '  atms ' . 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  purpose  of  this  function  is  to  build  a  QT  atom  container  in  response  to  a  call  to 
ImageCodecGetParameterLi  st  (11-717).  The  handle  should  be  detached  if  it  has  been 
read  in  from  a  resource.  The  caller  is  responsible  for  disposing  of  the  handle. 
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Special  Considerations 

The  implementation  of  this  function  in  the  Base  Effect  component  reads  in  and 
detaches  a  Component  Public  Resource  of  type  '  atms '  and  ID  1. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 


ImageCodecGetSettings 


Returns  the  codec  settings  chosen  by  the  user. 

ComponentResul t  ImageCodecGetSettings  ( 
Componentlnstance  ci  , 

Handle  settings  ); 


ci 

An  image  compressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

setti ngs 

A  handle  that  the  codec  should  resize  and  fill  in  with  the  current  internal 
settings.  If  there  are  no  current  internal  settings,  resize  it  to  0.  Don't  dispose  of 
this  handle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

ImageCodecGetSettings  returns  the  codec's  current  internal  settings.  If  there  are  no 
current  settings  or  the  settings  are  the  same  as  the  defaults,  the  codec  can  set  the 
handle  to  NIL. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Base  Image  Decompressor  Functions"  (V-2805) 

See  Also 

For  the  corresponding  set  function,  see  ImageCodecSetSetti  ngs  (11-737). 
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ImageCodecGetSettingsAsText 


ImageCodecGetSettings  AsT  ext 


Undocumented 

ComponentResul t  ImageCodecGetSettingsAsText  ( 
Componentlnstance  ci  , 

Handle  *text  ); 


ci 

An  image  compressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

text 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.  h 


ImageCodecGetSimilarity 


Notifies  your  codec  when  an  application  calls  GetSimilarity  (1-508). 


ComponentResul t  ImageCodecGetSimilarity  ( 


Componentlnstance 
Pi xMapHandl e 
const  Rect 

ImageDescriptionHandle 

Ptr 

Fi  xed 


c  i  , 
src , 

*srcRect , 
desc , 
data , 

*si mi  1 ari ty  ) ; 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

src 

A  handle  to  the  noncompressed  image.  The  image  is  stored  in  a  PixMap 
(IV-2332)  structure. 

srcRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  defines  the  portion  of  the  image  to 
compare  to  the  compressed  image. 
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ImageCodecGetSourceDataGammaLevel 


desc 

A  handle  to  the  ImageDescri  pti  on  (IV-2285)  structure  that  defines  the 
compressed  image  for  the  operation. 

data 

A  pointer  to  the  compressed  image  data, 
si  mi  1 ari ty 

A  pointer  to  a  field  that  is  to  receive  the  similarity  value.  Your  component  sets 
this  field  to  reflect  the  relative  similarity  of  the  two  images.  Valid  values  range 
from  0  (key  frame)  to  1  (identical). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Only  decompressors  receive  this  request. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 


ImageCodecGetSourceDataGammaLevel 


Returns  the  native  gamma  of  compressed  data,  if  any. 

ComponentResul t  ImageCodecGetSourceDataGamma Level  ( 
Componentlnstance  ci  , 

Fixed  *sourceDataGamma Level  ); 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
sourceDataGamma  Level 

On  return,  the  native  gamma  level  of  the  compressed  data.  If  the  value  is  0,  it  is 
the  default  gamma  level  of  the  platform. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  ICM  uses  the  information  returned  by  this  function  to  determine  what  gamma 
correction  is  necessary.  For  example,  the  Apple  DV  Codec  returns  2.2. 

Version  Notes 

Introduced  in  QuickTime  5. 
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ImageCodecHitTestData 


Programming  Info 

C  interface  file:  ImageCodec.  h 


See  Also 

See  ImageCodecRequestGammaLevel  (11-734). 


ImageCodecHitTestData 


Notifies  your  codec  when  the  application  calls  PtlnDSequenceData  (11-1147). 
ComponentResul t  ImageCodecHitTestData  ( 


Componentlnstance  ci  , 

ImageDescri pti onHandl e  desc, 
void  *data, 

Size  dataSize, 

Point  where, 

Boolean  *hit  ): 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

desc 

An  ImageDescri  pti  onHandl  e  for  the  image  data  pointed  to  by  the  data 
parameter. 

data 

Pointer  to  compressed  data  in  the  format  specified  by  the  desc  parameter. 
dataSi ze 

Size  of  the  compressed  data  referred  to  by  the  data  parameter, 
where 

A  QuickDraw  Point  (IV-2339)  structure  (0,0)  based  at  the  top-left  comer  of  the 
image, 
hi  t 

A  pointer  toaBoolean  value.  The  value  should  be  set  to  TRUE  if  the  point 
specified  by  the  where  parameter  is  contained  within  the  compressed  image 
data  specified  by  the  data  parameter,  or  FALSE  if  the  specified  point  falls  within 
a  blank  portion  of  the  image. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

ImageCodecHi  tTestData  allows  the  calling  application  to  perform  hit  testing  on 
compressed  data. 
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ImageCodecHitTestDataWithFlags 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Base  Image  Decompressor  Functions"  (V-2805) 


ImageCodecHitT  estDataW  ithFlags 


Undocumented 

ComponentResul t  ImageCodecHitTestDataWithFlags  ( 

Componentlnstance  ci  , 

ImageDescri pti onHandl e  desc, 
void  *data. 

Size  dataSize, 

Point  where, 

long  *hit, 

long  hitFlags  ); 

ci 

An  image  codec  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

desc 

A  handle  to  an  ImageDescri  pti  on  (IV-2285)  structure  for  the  image  data  pointed 
to  by  the  data  parameter. 

data 

Pointer  to  compressed  data  in  the  format  specified  by  the  desc  parameter. 
dataSi ze 

Size  of  the  compressed  data  referred  to  by  the  data  parameter, 
where 

A  QuickDraw  Point  (IV-2339)  structure  (0,0)  based  at  the  top-left  comer  of  the 
image. 

hi  t 

A  pointer  to  a  Boolean.  The  Boolean  should  be  set  to  TRUE  if  the  point  specified 
by  the  where  parameter  is  contained  within  the  compressed  image  data 
specified  by  the  data  parameter. 

hi  t FI  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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ImageCodecInitialize 


hitFlags  Constants 

Undocumented 

Undocumented 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 


ImageCodecInitialize 


Called  before  making  any  other  all  calls  to  your  component. 

ComponentResul t  ImageCodecInitialize  ( 

Componentlnstance  ci  , 

ImageSubCodecDecompressCapabi 1 i ti es  *cap  ); 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

cap 

On  return,  an  ImageSubCodecDecompressCapabi  1  i  ti  es  (IV-2288)  structure  that 
contains  the  capabilities  of  the  image  decompressor  component.  This  structure 
contains  two  fields.  The  canAsync  field  specifies  whether  your  component  can 
support  asynchronous  decompression  operations.  The  decompressRecordSi  ze 
field  specifies  the  size  of  the  decompression  record  structure  for  your 
component. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  component  must  implement  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.  h 

Programming  summary:  "Base  Image  Decompressor  Functions"  (V-2805) 


11-724 
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ImageCodecIsImageDescriptionEquivalent 


ImageCodecIsImageDescriptionEquivalent 


Compares  image  descriptions. 

ComponentResul t  ImageCodecIs ImageDescri p t i onEqui val ent  ( 
Componentlnstance  ci  , 

ImageDescri pti onHandl e  newDesc , 

Boolean  *equivalent  ); 


ci 

An  image  compressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
newDesc 

A  handle  to  the  ImageDescri  pti  on  (IV-2285)  structure  that  describes  the 
compressed  image, 
equi val ent 

A  pointer  toaBoolean  value.  If  the  structure  provided  in  the  newDesc  parameter 
is  equivalent  to  the  ImageDescri  pti  on  (IV-2285)  structure  currently  in  use  by  the 
image  sequence,  this  value  is  set  to  TRUE.  If  they  are  not  equivalent,  and 
therefore  a  new  image  sequence  must  be  created  to  display  an  image  using  the 
new  ImageDescri  pti  on  structure,  this  value  is  set  to  FALSE. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  component  receives  this  call  whenever  an  application  calls 
CDSequenceEqui  val  entlmageDescri  pti  on  (1-78).  Implementing  this  function  can 
significantly  improve  playback  of  edited  video  sequences  using  your  codec.  For 
example,  if  two  sequences  are  compressed  at  different  quality  levels  and  are  edited 
together  they  will  have  different  image  descriptions  because  their  quality  values 
will  be  different.  This  will  force  QuickTime  to  use  two  separate  decompressor 
instances  to  display  the  images.  By  implementing  this  function  your  decompressor 
can  tell  QuickTime  that  differences  in  quality  levels  don't  require  separate 
decompressors.  This  saves  memory  and  time,  thus  improving  performance. 

Special  Considerations 

The  current  ImageDescri  pti  on  (IV-2285)  structure  is  not  passed  in  this  function 
because  the  Image  Compression  Manager  assumes  the  codec  has  already  made 
copies  of  all  relevant  data  fields  from  the  current  ImageDescri  pti  on  structure  during 
the  ImageCodecPreDecompress  (11-731)  call. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Function  l-Q 


11-725 


ImageCodecIsStandardParameterDialogEvent 


Programming  Info 

C  interface  file:  ImageCodec.  h 

Programming  summary:  "Base  Image  Decompressor  Functions"  (V-2805) 

See  Also 

See  CDSequenceEqui  val  entlmageDescri  pti  on  (1-78). 


ImageCodecIsStandardParameterDialogEvent 


Processes  events  related  to  a  standard  parameters  dialog  box  created  by 
ImageCodecCreateStandardParameterDialog  (11-692). 

ComponentResul t  ImageCodecIsStandardParameterDial ogEvent  ( 
Componentlnstance  ci  , 

EventRecord  *pEvent, 

QTParameterDial og  createdDi al og  ); 


ci 

An  effect  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131).  This  must  be  the 
instance  that  was  passed  to  ImageCodecCreateStandardParameterDi  al  og  (11-692) 
to  create  the  dialog  box. 

pEvent 

A  pointer  to  an  EventRecord  (IV-2246)  structure. 
createdDi al og 

A  reference  to  the  dialog  box  created  by  the  call  to 
ImageCodecCreateStandardParameterDi  al  og  (11-692). 

function  result  If  the  error  code  returned  is  featurellnsupported,  your  application 
should  process  the  event  in  the  normal  way.  If  it  is  noErr,  the  event 
was  processed.  If  this  function  returns  any  other  value,  an  error 
occurred.  See  "Error  Codes"  (IV-2663). 

Discussion 

This  function  returns  an  error  code  that  indicates  whether  the  event  pointed  to  by 
pEvent  was  processed  or  not.  After  you  call 

ImageCodecCreateStandardParameterDial  og  (11-692)  to  create  a  standard  parameter 
dialog  box,  you  must  pass  every  non-null  event  to  this  function.  It  processes  events 
related  to  the  standard  parameter  dialog  box,  passing  other  events  to  your 
application  for  processing. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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ImageCodecNewImageBufferMemory 


Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Low-Level  Effects  Functions"  (V-2898) 

See  Also 

The  high-level  version  of  this  function  is  QTIsStandardParameterDi  al  ogEvent 
(11-1186).  Use  the  high-level  version  to  handle  events  for  dialog  boxes  created  by 
QTCreateStandardParameterDi  al  og  (11-1161). 


ImageCodecNewImageBufferMemory 


Asks  a  codec  to  allocate  memory  for  an  offscreen  buffer  of  non-RGB  pixels. 


Component  Res  ill  t  ImageCodecNewImageBufferMemory 


Componentlnstance 
CodecDecompressParams 
1  ong 

ICMMemoryDi sposedUPP 
vol  d 


ci  , 

*params , 
fl  ags , 

memoryGoneProc , 
*refCon  ); 


( 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

params 

A  pointer  to  a  decompression  parameters  structure, 
fl  ags 

Currently,  this  parameter  is  always  set  to  0. 
memoryGoneProc 

A  pointer  to  an  ICMMemoryDi  sposedProc  (III— 2092)  callback  that  will  be  called 
before  disposing  of  the  memory  allocated  by  the  codec. 

refCon 

A  reference  constant  that  is  passed  to  your  ICMMemoryDi  sposedProc  callback.  Use 
this  parameter  to  point  to  a  data  structure  containing  any  information  your 
function  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  call  is  used  to  support  a  codec  decompressing  into  a  non-RGB  buffer.  The 
transfer  codec  is  responsible  for  defining  the  offscreen  buffer  and  transferring  the 
image  from  the  offscreen  buffer  to  the  destination.  Your  component  receives  this 
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ImageCodecNewImageGWorld 


call  whenever  another  codec  has  requested  a  non-RGB  offscreen  buffer  of  the  type 
of  your  component's  subtype. 

Special  Considerations 

The  Image  Compression  Manager  does  not  currently  track  memory  allocations. 
When  a  compressor  or  decompressor  component  instance  is  closed,  it  must  ensure 
that  all  blocks  allocated  by  that  instance  are  disposed  of  and  call  the 
ICMMemoryDi sposedProc  (III — 2092)  callback. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.  h 

Programming  summary:  "Base  Image  Decompressor  Functions"  (V-2805) 


ImageCodecNewImageGWorld 


Undocumented 

ComponentResul t  ImageCodecNewImageGWorld  ( 
Componentlnstance  ci  , 

CodecDecompressParams  *params, 
GWorldPtr  *newGW, 

1  ong  f 1 ags  ) ; 


ci 

An  image  codec  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

params 

A  pointer  to  a  CodecDecompressParams  (IV-2190)  structure. 
newGW 

A  pointer  to  a  pointer  to  a  CGraf  Port  (IV-2168)  structure, 
fl  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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ImageCodecN  ewMemory 


Programming  Info 

C  interface  file:  ImageCodec.h 


ImageCodecNewMemory 


Requests  codec-allocated  memory. 


ComponentResul t  ImageCodecNewMemory  ( 


Componentlnstance 
Ptr 
Si  ze 
1  ong 

ICMMemoryDi sposedUPP 
voi  d 


cr  , 

*data , 
dataSi ze , 
dataUse , 
memoryGoneProc , 
*refCon  ); 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef aul  tComponent  (11-1131). 

data 

Returns  a  pointer  to  the  allocated  memory. 
dataSi ze 

The  desired  size  of  the  data  buffer. 
dataUse 

A  constant  (see  below)  that  indicates  how  the  memory  is  to  be  used.  For 
example,  the  memory  may  be  used  to  store  compressed  data  before  it's 
displayed,  mask  plane  data,  or  decompressed  data.  If  there  is  no  benefit  to 
storing  a  particular  kind  of  data  in  codec  memory,  the  codec  should  refuse  the 
request  for  the  memory  allocation. 

memoryGoneProc 

A  pointer  to  an  ICMMemoryDi  sposedProc  (III— 2092)  callback  that  will  be  called 
before  disposing  of  the  memory  allocated  by  a  codec. 

refCon 

A  reference  constant  value  that  your  codec  must  pass  to  the  memoryGoneProc 
callback.  Use  this  parameter  to  point  to  a  data  structure  containing  any 
information  your  callback  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error.  If 
your  codec  does  not  currently  have  free  memory  for  compression 
frame  data,  but  will  soon,  you  can  return 
codecNoMemoryPl  easeWai  tErr  to  indicate  this  fact. 
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dataUse  Constants 

0x00000001 

Memory  will  be  used  for  holding  compressed  image  data. 

0x00000002 

Memory  will  be  used  for  an  offscreen  image  buffer. 

Discussion 

Some  hardware  codecs  may  have  on-board  memory  that  can  be  used  to  store 
compressed  and  / or  decompressed  data.  This  function  makes  this  memory 
available  for  use  by  clients  of  the  codec.  Some  software  codecs  may  be  able  to 
optimize  their  performance  by  having  more  control  over  memory  allocation.  This 
function  makes  such  control  available.  Your  component  receives  this  call  whenever 
an  application  calls  CDSequenceNewMemory  (1-84). 

Special  Considerations 

The  Image  Compression  Manager  does  not  currently  track  memory  allocations. 
When  a  compressor  or  decompressor  component  instance  is  closed,  it  must  ensure 
that  all  blocks  allocated  by  that  instance  are  disposed  and  call  the 
ICMMemoryDi sposedProc  (III — 2092)  callback. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.  h 

Programming  summary:  "Base  Image  Decompressor  Functions"  (V-2805) 


ImageCodecPreCompress 


Notifies  your  component  before  compressing  an  image  or  a  band  of  an  image. 

ComponentResul t  ImageCodecPreCompress  ( 

Componentlnstance  ci  , 

CodecCompressParams  *params  ); 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

params 

A  pointer  to  a  CodecCompressParams  (IV-2184)  structure.  The  Image 
Compression  Manager  places  the  appropriate  parameter  information  in  that 
structure. 
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ImageCodecPreDecompress 


function  result  See  "Error  Codes"  (IV-2663).  Your  component  should  return  a  result 
code  of  codecCondi  ti  onErr  if  it  cannot  field  the  compression  request. 
Return  noErr  if  there  is  no  error. 

Discussion 

Your  component  receives  this  call  before  compressing  an  image  or  a  band  of  an 
image.  The  Image  Compression  Manager  also  calls  this  function  when  processing  a 
sequence.  In  that  case,  the  Image  Compression  Manager  calls  this  function 
whenever  the  parameters  governing  the  sequence  operation  have  changed 
substantially.  Your  component  indicates  whether  it  can  perform  the  requested 
compression  operation. 

Special  Considerations 

Only  compressors  receive  this  call. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 


ImageCodecPreDecompress 


Notifies  your  component  before  decompressing  an  image  or  sequence  of  frames. 

ComponentResul t  ImageCodecPreDecompress  ( 

Componentlnstance  ci  , 

CodecDecompressParams  *params  ); 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef aul  tComponent  (11-1131). 
params 

A  pointer  to  a  CodecDecompressParams  (IV-2190)  structure.  The  Image 
Compression  Manager  places  the  appropriate  parameter  information  in  that 
structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

If  your  decompressor  component  supports  scheduled  asynchronous 
decompression  operations, be  sure  to  set  the  codecCanAsyncWhen  flag  to  1  in  the  flags 
field  of  your  component's  CodecCapabi  1  i  ti  es  (IV-2179)  structure.  If  you  set 
codecCanAsyncWhen,  you  must  also  set  codecCanAsync.  Codecs  that  support  scheduled 
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ImageCodecPreflight 


asynchronous  decompression  are  strongly  advised  to  also  set  the 
codecCanShieldCursor  flag. 

If  your  decompressor  component  uses  a  secondary  hardware  buffer  for  its  images, 
be  sure  to  set  the  codecHasVol  ati  1  eBuf  f  er  flag  to  1  in  the  fl  ags  field  of  your 
component's  CodecCapabi  1  i  ti  es  structure.  If  your  decompressor  component  is  used 
solely  as  a  transfer  codec  and  uses  the  ImageCodecNewImageBufferMemory  (11-727) 
function  to  create  an  offscreen  buffer  that  is  really  onscreen,  your  codec  will  need  to 
set  the  codecImageBufferlsOnScreen  flag  to  1. 

Special  Considerations 

Only  decompressors  receive  this  request. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.  h 


ImageCodecPreflight 


Called  before  decompressing  an  image,  in  response  to  an  ImageCodecPreDecompress 
(11-731)  call  from  the  Image  Compression  Manager. 

ComponentResul t  ImageCodecPreflight  ( 

Componentlnstance  ci  , 

CodecDecompressParams  *params  ); 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

params 

A  pointer  to  a  CodecDecompressParams  (IV-2190)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  codec  responds  to  this  call  by  returning  information  about  its  capabilities  in  a 
CodecCapabi  1  i  ti  es  (IV-2179)  structure.  The  Image  Compression  Manager  creates 
the  decompression  parameters  structure,  and  your  image  decompressor 
component  is  required  only  to  provide  values  for  the  wantedDestinationPixelSize 
and  wantedDestinationPixel  Types  fields  of  the  structure.  Your  image  decompressor 
component  can  also  modify  other  fields  if  necessary.  For  example,  if  it  can  scale 
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images,  it  must  set  the  codecCapabi  1  i  tyCanScal  e  flag  in  the  capabilities  field  of  the 
structure. 

Special  Considerations 

Your  component  must  implement  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec .  h 

Programming  summary:  "Base  Image  Decompressor  Functions"  (V-2805) 


ImageCodecQueueStarting 


Called  by  the  base  image  decompressor  before  decompressing  the  frames  in  the 
queue  if  your  image  decompressor  component  supports  asynchronous  scheduled 
decompression. 

ComponentResul t  ImageCodecQueueStarting  ( 

Componentlnstance  ci  ); 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  component  is  not  required  to  implement  this  function.  It  can  perform  any 
tasks  at  this  time,  such  as  locking  data  structures. 

Special  Considerations 

The  base  image  decompressor  never  calls  this  function  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.  h 

Programming  summary:  "Base  Image  Decompressor  Functions"  (V-2805) 


Inside  QuickTime:  Function  l-Q 


11-733 


ImageCodecQueueStopping 


ImageCodecQueueStopping 


Notifies  your  component  that  the  frames  in  the  queue  have  been  decompressed,  if 
your  image  decompressor  component  supports  asynchronous  scheduled 
decompression. 

ComponentResul t  ImageCodecQueueStopping  ( 

Componentlnstance  ci  ); 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

After  your  image  decompressor  component  handles  a  call  to  this  function,  it  can 
perform  any  tasks  that  are  required  when  decompression  of  the  frames  is  finished, 
such  as  disposing  of  data  structures  that  are  no  longer  needed. 

Special  Considerations 

Your  component  is  not  required  to  implement  this  function.  This  function  is  never 
called  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Base  Image  Decompressor  Functions"  (V-2805) 


ImageCodecRequestGammaLevel 


Asks  an  image  codec  to  convert  from  source  to  destination  gamma  levels. 

ComponentResul t  ImageCodecRequestGammaLevel  ( 

Componentlnstance  ci  , 

Fixed  srcGammaLevel , 

Fixed  dstGammaLevel  , 

long  *codecCanMatch  ); 

ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 


11-734 


Inside  QuickTime:  Function  l-Q 


ImageCodecRequestSettings 


srcGammaLevel 

The  gamma  level  to  convert  from. 
dstGammaLevel 

The  gamma  level  to  convert  to. 
codecCanMatch 

Pointer  to  a  value  that  indicates  if  the  conversion  from  s  rcGamma  Level  to 
dstGammaLevel  is  supported. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  tells  the  codec  what  the  gamma  of  the  source  buffer  and  destination 
pixel  map  are  so  that  the  codec  can  try  to  convert  between  the  two  gammas  when 
decompressing.  Proper  gamma  conversion  is  accomplished  by  normalizing  source 
data  to  black  and  white  points  to  0  to  1  and  raising  the  result  by  the  ratio  of  the 
srcGammaLevel  divided  by  dstGammaLevel.  The  most  accurate  correction  is  done  in 
RGB  space,  but  a  visual  approximation  can  be  done  by  raising  the  luma  component 
alone. 

Special  Considerations 

This  function  can  be  called  several  times  as  the  ICM  sets  up  a  gamma  conversion 
chain.  The  last  value  takes  precedent  for  future  scheduled  frames.  It  may  also  be 
called  while  frames  are  already  scheduled,  indicating  that  conditions  have  changed. 
The  new  request  is  effective  on  frames  that  are  scheduled  after  the  call  is  made. 
Frames  previously  scheduled  should  continue  to  use  the  previously  requested 
gamma  conversion  values. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  ImageCodec.h 

See  Also 

See  ImageCodecGetSourceDataGammaLevel  (11-721). 


ImageCodecRequestSettings 


Displays  a  dialog  box  containing  codec-specific  compression  settings. 

ComponentResul t  ImageCodecRequestSettings  ( 

Componentlnstance  ci  , 

Handle  settings, 

Rect  *rp. 


Inside  QuickTime:  Function  l-Q 


11-735 


ImageCodecScheduleFrame 


Modal  Fi  lterllPP  filterProc  ); 


ci 

An  image  compressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

setti ngs 

A  handle  of  data  specific  to  the  codec.  If  the  handle  is  empty,  the  codec  should 
use  its  default  settings, 
rp 

A  pointer  to  a  Rect  (IV-2399)  structure  giving  the  coordinates  of  the  standard 
compression  dialog  box  in  global  screen  coordinates.  The  codec  can  use  this  to 
position  its  dialog  box  in  the  same  area  of  the  screen, 
f  i  1 terProc 

A  pointer  to  a  Modal  Fi  1  terProc  (III— 2098)  callback  that  the  codec  must  either 
pass  to  the  Mac  OS  Modal  Dialog  function  or  call  at  the  beginning  of  the  codec 
dialog  process.  This  callback  gives  the  calling  application  and  standard 
compression  dialog  box  a  chance  to  process  update  events. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  ImageCodecRequestSetti  ngs  function  allows  the  display  of  a  dialog  box  of 
additional  compression  settings  specific  to  the  codec.  These  settings  are  stored  in  a 
settings  handle.  The  codec  can  store  any  data  in  any  format  it  wants  in  the  settings 
handle  and  resize  it  accordingly.  It  should  store  some  type  of  tag  or  version 
information  that  it  can  use  to  verify  that  the  data  belongs  to  the  codec.  The  codec 
should  not  dispose  of  the  handle. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Base  Image  Decompressor  Functions"  (V-2805) 


ImageCodecScheduleFrame 


Undocumented 

ComponentResul t  ImageCodecScheduleFrame  ( 

Componentlnstance  ci  , 

const  ImageSubCodecDecompressRecord  *drp, 
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ImageCodecSetSettings 


ImageCodecTi meT  riggerUPP  triggerProc, 

void  *tri ggerProcRefCon  ); 


ci 

An  image  codec  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

drp 

A  pointer  to  an  ImageSubCodecDecompressRecord  (IV-2289)  structure, 
tri ggerProc 

An  ImageCodecTimeTriggerProc  (III— 2096)  callback, 
tri ggerProcRefCon 

A  reference  constant  that  is  passed  to  your  ImageCodecTimeTriggerProc  callback. 
Use  this  parameter  to  point  to  a  data  structure  containing  any  information  your 
function  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCodec.h 


ImageCodecSetSettings 


Sets  the  settings  of  an  optional  image  codec  dialog  box. 

ComponentResul t  ImageCodecSetSettings  ( 
Componentlnstance  ci  , 

Handle  settings  ); 


ci 

An  image  compressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

setti ngs 

A  handle  to  internal  settings  originally  returned  by  either 
ImageCodecRequestSetti  ngs  (11-735)  or  ImageCodecGetSetti  ngs  (11-719).  The 
codec  should  set  its  internal  settings  to  match  those  of  the  settings  handle. 
Because  the  codec  does  not  own  the  handle,  it  should  not  dispose  of  it  and 
should  copy  only  its  contents,  not  the  handle  itself.  If  the  settings  handle  passed 
is  empty,  the  codec  should  sets  its  internal  settings  to  a  default  state. 


Inside  QuickTime:  Function  l-Q 


11-737 


ImageCodecSetTimeBase 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  allows  a  codec  to  return  its  private  settings.  Set  the  codec's  internal 
settings  to  the  state  specified  in  the  settings  handle.  The  codec  should  always  check 
the  validity  of  the  contents  of  the  handle  so  that  invalid  settings  are  not  used. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.  h 

Programming  summary:  "Base  Image  Decompressor  Functions"  (V-2805) 

See  Also 

For  the  corresponding  get  function,  see  ImageCodecGetSetti  ngs  (11-719). 


ImageCodecSetTimeBase 


Sets  the  time  base  for  an  image  codec  component. 

ComponentResul t  ImageCodecSetTimeBase  ( 
Componentlnstance  ci  , 

voi d  *base  ) ; 


ci 

An  image  codec  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

base 

A  pointer  to  the  time  base  for  this  operation.  Your  application  obtains  this  time 
base  identifier  from  NewTimeBase  (11-1119). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec. h 


ImageCodecSetTimeCode 


Sets  the  timecode  for  the  next  frame  that  is  to  be  decompressed. 
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Inside  QuickTime:  Function  l-Q 


ImageCodecSourceChanged 


ComponentResul t  ImageCodecSetTimeCode  ( 
Componentlnstance  ci  , 

void  *timeCodeFormat , 

void  *timeCodeTime  ); 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

ti meCodeFormat 

A  pointer  to  a  Ti  meCodeDef  (IV-2482)  structure.  This  structure  contains  the 
timecode  definition  information  for  the  next  frame  to  be  decompressed. 
timeCodeTime 

A  pointer  to  a  Ti  meCodeRecord  (IV-2484)  structure.  This  structure  contains  the 
time  value  for  the  next  frame  in  the  current  sequence. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  component  receives  this  call  whenever  an  application  calls 
SetDSequenceTi  meCode  (III— 1590).  That  function  allows  an  application  to  set  the 
timecode  for  a  frame  that  is  to  be  decompressed.  The  timecode  information  you 
receive  applies  to  the  next  frame  to  be  decompressed  and  is  provided  to  the 
decompressor  by  ImageCodecBandDecompress  (11-689). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Base  Image  Decompressor  Functions"  (V-2805) 


ImageCodecSourceChanged 


Notifies  your  codec  that  one  of  the  data  sources  has  changed  when  an  application 
calls  CDSequenceSetSourceData  (1-86)  or  CDSequenceChangedSourceData  (1-76). 


ComponentResul t  ImageCodecSourceChanged  ( 


Componentlnstance 

UInt32 

UInt32 

CDSequenceDataSourcePtr 
1  ong 


ma  jorSourceChangeSeed , 
mi  norSourceChangeSeed , 
sourceData , 

*flags0ut  ); 


Inside  QuickTime:  Function  l-Q 
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ImageCodecStandardParameterDialogDoAction 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 
majorSourceChangeSeed 

An  integer  value  that  is  incremented  each  time  a  data  source  is  added  or 
removed.  This  provides  an  easy  way  for  a  codec  to  know  when  it  needs  to 
redetermine  which  data  source  inputs  are  available. 

minorSourceChangeSeed 

An  integer  value  that  is  incremented  each  time  a  data  source  is  added  or 
removed,  or  the  data  contained  in  any  of  the  data  sources  changes.  This 
provides  a  way  for  a  codec  to  know  if  the  data  available  to  it  has  changed. 
sourceData 

A  pointer  to  a  CDSequenceDataSource  (IV-2165)  structure.  This  structure 
contains  a  linked  list  of  all  data  sources.  Because  each  data  source  contains  a 
link  to  the  next  data  source,  a  codec  can  access  all  data  sources  from  this 
structure, 
f 1 agsOut 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flagsOut  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Base  Image  Decompressor  Functions"  (V-2805) 


ImageCodecStandardParameterDialogDoAction 

Allows  you  to  control  the  behavior  of  a  standard  parameter  dialog  box  created  by 

ImageCodecCreateStandardParameterDialog  (11-692). 

ComponentResul t  ImageCodecStandardParameterDial ogDoActi on  ( 
Componentlnstance  ci  , 

QTParameterDialog  createdDialog, 

long  action, 

voi d  *params  ) ; 
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Inside  QuickTime:  Function  l-Q 


ImageCodecStandardParameterDialogDoAction 


ci 

An  effect  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131).  This  must  be  the 
same  instance  as  was  passed  to  ImageCodecCreateStandardParameterDi  al  og 
(11-692)  to  create  the  dialog  box. 
createdDi al og 

A  reference  to  the  dialog  box  created  by  the  call  to 
ImageCodecCreateStandardParameterDi al  og. 

acti on 

The  action  selector  (see  below),  which  determines  which  of  the  available  actions 
you  want  the  function  to  perform, 
params 

The  (optional)  parameter  to  the  action.  The  type  passed  in  this  parameter 
depends  on  the  value  of  the  action  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

action  Constants 

pdActi onConf i rmDi al og 

Retrieves  the  current  parameter  values  from  the  standard  parameters  dialog 
box.  The  parameter  values  are  placed  in  the  parameters  parameter  that  was 
passed  to  the  appropriate  call  to  ImageCodecCreateStandardParameterDi  al  og 
(11-692).  Use  this  action  when  the  user  clicks  the  OK  button  in  a  dialog  box  your 
application  has  created  that  incorporates  controls  from  the  standard  parameter 
dialog.  If  you  created  a  stand-alone  standard  parameters  dialog  box,  this  action 
is  automatically  called  for  you  when  the  user  clicks  the  OK  button. 

pdActi onSetAppl eMenu 

Use  this  selector  to  make  the  Apple  menu  available  while  the  standard 
parameter  dialog  box  is  active.  Pass  the  MenuHandl  e  of  the  Apple  menu  in  the 
params  parameter. 
pdActi onSetEdi tMenu 

Use  this  action  to  make  your  application's  Edit  menu  available  while  the 
standard  parameters  dialog  box  is  active.  Pass  the  MenuHandleof  the  Edit  menu 
in  the  params  parameter. 
pdActi onGetDi al ogVal ues 

Retrieves  the  current  parameter  values  from  the  standard  parameters  dialog 
box.  The  parameter  values  are  placed  in  the  QT  atom  container  you  pass  in  the 
params  parameter  to  this  function. 


Inside  QuickTime:  Function  l-Q 
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ImageCodecStandardParameterDialogDoAction 


pdActi onSetPrevi ewUserltem 

Passes  the  number  of  the  user  item  that  should  be  replaced  by  the  effect 
preview  movie  clip.  The  pa  rams  parameter  contains  a  long  integer  holding  the 
user  item  number. 
pdActi onSetPrevi ewPicture 

Use  this  action  to  change  the  images  that  are  used  in  the  preview  window  of 
the  standard  parameters  dialog  box.  QuickTime  provides  default  images  but 
you  may  wish,  for  example,  to  use  thumbnail  images  taken  from  your 
application  instead.  The  params  parameter  contains  a  QTParamPrevi  ewPtr  that 
references  the  image  to  use. 

pdActi onSetColorPickerEventProc 

Set  the  function  that  will  be  used  when  the  standard  parameters  dialog  box 
needs  to  display  a  color  picker.  The  params  parameter  should  contain  a  pointer 
to  the  replacement  color  picker  function. 
pdActi onSetDi al ogTi tl e 

Sets  the  title  of  the  standard  parameters  dialog  box.  The  params  parameters 
should  contain  a  Pascal  Str255  string. 
pdActi onGetSubPanelMenu 

Returns  a  list  of  the  sub-panels  used  by  the  standard  parameters  dialog  box.  If 
there  are  more  parameter  controls  than  can  fit  into  the  available  area  of  the 
dialog  box,  the  parameters  are  automatically  split  into  sub-panels  (usually  by 
segmenting  the  set  of  parameters  by  group).  The  pop-up  menu  used  to  switch 
between  the  panels  is  returned  as  a  MenuHandl  e  in  the  params  parameter. 

pdActi onActivateSubPanel 

Sets  the  current  sub-panel.  The  params  parameter  contains  a  long  integer  that  is 
the  number  of  the  panel  to  be  displayed. 
pdActi onConductStopAlert 

Displays  a  Stop  alert.  The  params  parameter  contains  a  Stri ngPtr  that  is 
displayed  in  the  alert.  This  feature  can  be  used  in  conjunction  with  the 
ImageCodecVal  i  dateParameters  (11-745)  function  to  inform  the  user  that  invalid 
parameter  values  have  been  entered. 

Discussion 

This  function  allows  you  to  change  the  default  behavior  of  the  standard  parameter 
dialog  box,  and  provides  a  mechanism  for  your  application  to  communicate  with 
controls  that  were  incorporated  into  an  application  dialog  box.  It  also  allows  you  to 
retrieve  parameter  values  from  the  dialog  box  at  any  time.  You  specify  which 
function  will  be  performed  by  passing  an  action  selector  in  the  action  parameter 
and,  optionally,  a  single  parameter  in  the  params  parameter.  Some  of  the  actions  you 
can  specify  through  this  function  are  only  appropriate  if  you  have  incorporated 
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Inside  QuickTime:  Function  l-Q 


ImageCodecTrimlmage 


standard  parameter  dialog  box  controls  within  a  dialog  box  created  by  your 
application. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 

Programming  summary:  "Low-Level  Effects  Functions"  (V-2898) 

See  Also 

This  function  is  only  used  with  dialog  boxes  created  by  the  low-level 
ImageCodecCreateStandardParameterDi  al  og  (11-692)  function.  For  dialog  boxes 
created  by  the  high-level  QTCreateStandardParameterDi  al  og  (11-1161)  function,  use 
QTStandardParameterDi  al  ogDoActi  on  (11-1313). 


ImageCodecT  rimlmage 


Notifies  your  component  whenever  an  application  calls  Tri  mlmage  (III— 1956). 


ComponentResul t  ImageCodecTrimlmage  ( 


Componentlnstance 
ImageDescri pti onHandl e 
Ptr 
1  ong 

ICMDataProc Record Ptr 
Ptr 
1  ong 

ICMFlushProc Record Ptr 
Rect 

ICMProgressProc Record Ptr 


ci  , 

Desc , 
i nData , 
i nBuf ferSi ze , 
dataProc, 
outData , 
outBuf ferSi ze , 
f 1 ushProc , 

*tri  mRect , 
progressProc  ); 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

Desc 

A  handle  to  the  ImageDescri  pti  on  (IV-2285)  structure  that  describes  the 
compressed  image.  Your  component  updates  this  structure  to  refer  to  the 
resized  image. 

i nData 

A  pointer  to  the  compressed  image  data.  If  the  entire  compressed  image  cannot 
be  stored  at  this  location,  the  application  may  provide  a  data-loading  function; 


Inside  QuickTime:  Function  l-Q 
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ImageCodecTrimlmage 


see  the  description  of  the  dataProc  parameter  to  this  function  for  details.  This  is 
a  32-bit  clean  address. 

i nBufferSi ze 

The  size  of  the  buffer  to  be  used  by  the  data-loading  function  specified  by  the 
dataProc  parameter.  If  the  application  did  not  specify  a  data-loading  function, 
this  parameter  is  NIL. 

dataProc 

A  pointer  to  an  ICMDataProcRecord  (IV-2279)  structure.  If  the  application  did 
not  provide  a  data-loading  function,  this  parameter  is  NIL.  In  this  case,  the 
entire  image  must  be  in  memory  at  the  location  specified  by  the  1  n Data 
parameter.  If  the  data  stream  is  not  all  in  memory  when  the  application  calls 
GetCompressedlmageSi  ze  (1-396),  your  component  may  call  an  application 
function  that  loads  more  compressed  data. 
outData 

A  pointer  to  a  buffer  to  receive  the  trimmed  image.  If  there  is  not  sufficient 
memory  to  store  the  compressed  image,  the  application  may  choose  to  write  the 
compressed  data  to  mass  storage  during  the  compression  operation.  The 
flushProc  parameter  identifies  the  data-unloading  function.  This  is  a  32-bit 
clean  address. 

outBufferSi ze 

The  size  of  the  buffer  to  be  used  by  the  data-unloading  function  specified  by  the 
f  1  ushProc  parameter.  If  the  application  did  not  specify  a  data-unloading 
function,  this  parameter  is  NIL. 

f 1 ushProc 

A  pointer  to  an  I  CM  FI  ushProcRecord  (IV-2280)  structure.  If  the  application  did 
not  provide  a  data-unloading  function,  this  parameter  is  NIL.  In  this  case,  your 
component  writes  the  entire  compressed  image  into  the  memory  location 
specified  by  the  outData  parameter.  If  there  is  not  enough  memory  to  store  the 
compressed  image,  your  component  may  call  an  application  function  that 
unloads  some  of  the  compressed  data, 
tri  mRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  defines  the  desired  image 
dimensions.  Your  component  adjusts  the  structure's  values  so  that  they  refer  to 
the  same  rectangle  in  the  resulting  image.  This  is  necessary  whenever  data  is 
removed  from  the  beginning  of  the  image. 

progressProc 

A  pointer  to  an  ICMProgressProcRecord  (IV-2284)  structure.  During  the 
operation,  your  component  should  occasionally  call  an  application  function  to 
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ImageCodecValidateParameters 


report  its  progress.  If  the  application  did  not  provide  a  progress  function,  this 
parameter  is  NIL. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec .  h 


ImageCodec  V  alidateParameters 


Validates  effect  parameters. 

i dateParameters  ( 
cl  , 

parameters , 

ons  val idati onFl ags  , 
errorstring  ); 


ComponentResul t  ImageCodecVal 
Componentlnstance 
QTAtomContai ner 
QTParameterVal i dati onOpti 
Stri ngPtr 


ci 

An  image  decompressor  component  instance.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef aul  tComponent  (11-1131). 
parameters 

The  atom  container  containing  the  effect  parameters  to  be  validated, 
val i dati onFl ags 

Constants  (see  below)  that  control  validation. 
errorStri ng 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

validationFlags  Constants 

kParameterVal i dati onNoFl  ags 

This  value  indicates  that  a  standard  validation  should  take  place.  This  function 
is  being  called  because  the  user  has  changed  the  value  of  a  parameter  in  the 
standard  parameters  dialog  box. 
kParameterVal i dati on Fi nal Val  idati  on 

This  value  indicates  that  this  validation  is  the  final  validation  before  the 
standard  parameters  dialog  box  is  dismissed.  This  is  useful  if  you  want  to 
perform  a  single  validation  of  the  parameters  just  after  the  user  clicks  the  OK 
button  to  dismiss  the  dialog  box. 
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11-745 


ImageFieldSequenceBegin 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 


ImageFieldSequenceBegin 


Initiates  an  image  field  sequence  operation  and  specifies  the  input  and  output  data 
format. 


OSErr  ImageFieldSequenceBegin  ( 

ImageFi el dSequence  *ifs, 

ImageDescri pti onHandl e  descl, 

ImageDescri pti onHandl e  desc2, 

ImageDescri pti onHandl e  descOut 


) : 


i  fs 

On  return,  contains  the  unique  sequence  identifier  assigned  to  the  sequence, 
descl 

An  ImageDescri  pti  on  (IV-2285)  structure  describing  the  format  and 
characteristics  of  the  data  to  be  passed  to  ImageFi  el  dSequenceExtractCombi  ne 
(11-747)  through  the  datal  parameter. 

desc2 

An  ImageDescri  pti  on  (IV-2285)  structure  describing  the  format  and 
characteristics  of  the  data  to  be  passed  to  the 

ImageFi  el  dSequenceExtractCombi  ne  function  through  the  data2  parameter.  Set 
to  N I L  if  the  requested  operation  uses  only  one  input  frame. 

descOut 

The  desired  format  of  the  resulting  frames.  Typically  this  is  the  same  format 
specified  by  the  descl  and  desc2  parameters. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Use  this  function  to  set  up  an  image  field  sequence  operation  and  specify  the  input 
and  output  data  format. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


11-746 
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ImageFieldSequenceEnd 


Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Video  Fields"  (V-2821) 


ImageFieldSequenceEnd 


Ends  an  image  field  sequence  operation. 

OSErr  ImageFieldSequenceEnd  ( 

ImageFi el dSequence  its  ); 


i  f  s 

The  unique  sequence  identifier  that  was  returned  by  the 
ImageFi  el  dSequenceBegi  n  (11-746)  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  must  call  this  function  to  terminate  an  image  field  sequence  operation. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Video  Fields"  (V-2821) 


ImageFieldSequenceExtractCombine 


Performs  field  operations  on  video  data. 


OSErr  ImageFi el dSequenceExtractCombi  ne  ( 


ImageFi el dSequence 

1  ong 

voi  d 

1  ong 

voi  d 

1  ong 

voi  d 

1  ong 


i  f  s , 

fi  el  d FI  ags  , 
*datal , 
dataSi zel , 
*data2 , 
dataSi ze2 , 
*outputData , 
*outDataSi ze 


): 


The  unique  sequence  identifier  that  was  returned  by  ImageFieldSequenceBegin 
(11-746). 
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11-747 


ImageFieldSequenceExtractCombine 


f  i  el d FI ags 

Flags  (see  below)  that  specify  the  operation  to  be  performed.  A  correctly 
formed  request  will  specify  two  input  fields,  mapping  one  to  the  odd  output 
field  and  the  other  to  the  even  output  field, 
datal 

A  pointer  to  a  buffer  containing  the  data  of  input  field  one. 
dataSi zel 

The  size  of  the  datal  buffer. 
data2 

A  pointer  to  a  buffer  containing  the  data  of  input  field  two.  Set  to  N I L  if  the 
requested  operation  uses  only  one  input  frame. 
dataSi ze2 

The  size  of  the  data2  buffer.  Set  to  0  if  the  requested  operation  uses  only  one 
input  frame. 

outputData 

A  pointer  to  a  buffer  to  receive  the  resulting  frame.  Use  GetMaxCompressi  onSi  ze 
(1-420)  to  determine  the  amount  of  memory  to  allocate  for  this  buffer. 
outDataSi ze 

On  output  this  parameter  returns  the  actual  size  of  the  data. 

function  result  Returns  the  codecUni mpErr  result  code  if  there  is  no  codec  present  in 
the  system  that  can  perform  the  requested  operation.  See  "Error 
Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

fieldFlags  Constants 

evenFieldlToEvenFieldOut 

Maps  the  even  field  specified  by  the  datal  parameter  to  the  even  output  field. 
evenFieldlToOddFieldOut 

Maps  the  even  field  specified  by  the  datal  parameter  to  the  odd  output  field. 
oddFieldlToEvenFieldOut 

Maps  the  odd  field  specified  by  the  datal  parameter  to  the  even  output  field. 
oddFieldlToOddFieldOut 

Maps  the  odd  field  specified  by  the  datal  parameter  to  the  odd  output  field. 
evenField2ToEvenField0ut 

Maps  the  even  field  specified  by  the  data 2  parameter  to  the  even  output  field. 
evenField2To0ddField0ut 

Maps  the  even  field  specified  by  the  data2  parameter  to  the  odd  output  field. 


11-748 
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ImageTranscodeDisposeFrameData 


oddFi  el  d2ToEvenFi  el  dOut 

Maps  the  odd  field  specified  by  the  data2  parameter  to  the  even  output  field. 
oddFi el d2To0ddFi el dOut 

Maps  the  odd  field  specified  by  the  data2  parameter  to  the  odd  output  field. 

Discussion 

This  function  provides  a  method  for  working  directly  with  fields  of  interlaced 
video.  You  can  use  it  to  change  the  field  dominance  of  an  image  by  reversing  the 
two  fields,  or  to  create  or  remove  the  effects  of  the  3:2  pulldown  commonly 
performed  when  transferring  film  to  NTSC  videotape.  Because  this  function 
operates  directly  on  the  compressed  video  data,  it  is  faster  than  working  with 
decompressed  images.  It  also  has  the  added  benefit  of  eliminating  any  image 
quality  degradation  that  might  result  from  lossy  codecs. 

This  function  accepts  one  or  two  compressed  images  as  input  and  creates  a  single 
compressed  image  on  output.  You  specify  the  operation  to  be  performed  using  the 
fi  el  d FI  ags  parameter. 

Special  Considerations 

The  Apple  Component  Video  (YUV)  and  Motion  JPEG  codecs  currently  support 
this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Video  Fields"  (V-2821) 


ImageT  ranscodeDisposeFrameData 


Disposes  transcoded  image  data. 

OSErr  ImageTranscodeDisposeFrameData  ( 
ImageTranscodeSequence  its, 

void  *dstData  ); 


i  ts 

The  image  transcoder  sequence  that  was  used  to  generate  the  transcoded  data. 
dstData 

A  pointer  to  the  transcoded  image  data  generated  by  the  ImageT ranscodeFrame 
(11-750)  function. 
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ImageTranscodeFrame 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

When  the  transcoded  image  data  returned  by  ImageT ranscodeFrame  (11-750)  is  no 
longer  needed,  use  this  function  to  dispose  of  the  data.  Only  the  image  transcoder 
that  generated  the  data  can  properly  dispose  of  it. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Image  Transcoder  Support"  (V-2873) 


ImageT  ranscodeFrame 


Transcodes  a  frame  of  image  data. 

OSErr  ImageTranscodeFrame  ( 

ImageTranscodeSequence 
voi  d 
1  ong 
voi  d 
1  ong 

i  ts 

The  image  transcoder  sequence  to  use  to  perform  the  transcoding  operation. 
srcData 

A  pointer  to  the  source  data  to  transcode. 
srcDataSi ze 

The  size  of  the  compressed  source  image  data  in  bytes. 
dstData 

On  return,  a  pointer  to  the  transcoded  image  data. 
dstDataSi ze 

On  return,  the  size  of  the  transcoded  image  data. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

After  creating  the  image  transcoder  sequence,  using  ImageT ranscodeSequenceBegi  n 
(11-754),  use  this  function  to  transcode  a  frame  of  image  data.  The  caller  is 
responsible  for  disposing  of  the  transcoded  data  using 
ImageT ranscodeDi sposeFrameData  (11-749). 


i  ts , 

*srcData , 
srcDataSi ze , 
**dstData , 
*dstDataSize  ); 
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ImageTranscoderBeginSequence 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Image  Transcoder  Support"  (V-2873) 


ImageT  ranscoderBeginSequence 


Initiates  an  image  transcoding  sequence  and  specifies  the  input  data  format. 


Component  Res  ill  t  ImageTranscoderBegi  nSequence 
ImageTranscoderComponent  itc, 

ImageDescri pt ion Handle  srcDesc, 

ImageDescript ion Handle  *dstDesc, 

void  *data, 

long  dataSize  ); 


i  tc 

The  image  transcoder  component. 
srcDesc 

The  ImageDescri  pti  on  (IV-2285)  structure  for  the  source  compressed  image 
data. 

dstDesc 

On  return,  a  new  ImageDescri  pti  on  structure. 

data 

First  frame  of  data  to  be  transcoded  (may  be  N I L). 
dataSi ze 

Size  of  compressed  image  data  pointed  to  by  the  data. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  specifies  the  format  of  source  compressed  image  data  in  the  srcDesc 
parameter.  The  image  transcoder  should  allocate  anew  ImageDescri  pti  on  (IV-2285) 
structure  and  return  it  in  the  dstDesc  parameter.  The  new  ImageDescri  pti  on 
structure  should  be  a  completely  filled  out  image  description  which  is  sufficient  for 
correctly  decompressing  the  data  generated  by  subsequent  calls  to 
ImageTranscoderConvert  (11-752). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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ImageTranscoderConvert 


Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Image  Transcoder  Support"  (V-2873) 


ImageT  ranscoderConvert 


Performs  image  transcoding  operations. 

ComponentResul t  ImageTranscoderConvert  ( 

ImageTranscoderComponent  itc, 
void  *srcData, 

long  srcDataSize, 

void  **dstData, 

long  *dstDataSize  ); 

i  tc 

The  image  transcoder  component. 
srcData 

A  pointer  to  the  source  compressed  image  data  to  transcode. 
srcDataSi ze 

The  size  of  the  source  image  data,  in  bytes. 
dstData 

On  return,  a  pointer  to  the  transcoded  data. 
dstDataSi ze 

On  return,  the  size  of  the  transcoded  data  in  bytes. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  image  transcoder  component  is  responsible  for  allocating  storage  for  the 
transcoded  data,  transcoding  the  data,  and  returning  a  pointer  to  the  transcoded 
data  in  the  dstData  parameter.  The  size  of  the  transcoded  data  in  bytes  should  be 
returned  in  the  dstDataSi  ze  parameter.  The  caller  is  responsible  for  disposing  of  the 
transcoded  data  using  ImageTranscoderDi  sposeData  (11-753). 

The  memory  allocated  to  store  the  transcoded  image  data  must  not  be  in  an 
unlocked  handle.  Even  if  the  image  transcoding  operation  can  be  performed  in 
place,  the  transcoded  data  must  be  placed  in  a  separate  block  of  memory  from  the 
source  data.  The  image  transcoder  component  must  not  write  back  into  the  source 
image  data. 


11-752 
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ImageTranscoderDisposeData 


The  responsibility  for  allocating  the  buffer  for  the  transcoded  data  has  been  placed 
in  the  transcoder  with  the  intent  that  some  hardware  manufacturers  may  find  it 
useful  to  place  the  transcoded  data  directly  into  on-board  memory  on  their  video 
board.  If  the  transcoding  operation  is  being  performed  on  a  QuickTime  movie,  the 
transcoded  data  pointer  will  be  almost  immediately  passed  on  to  a  decompressor. 
If  the  decompressor  is  implemented  in  hardware,  performance  may  be  increased 
because  the  transcoded  data  is  already  loaded  onto  the  decompression  hardware. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Image  Transcoder  Support"  (V-2873) 


ImageTranscoderDisposeData 


Disposes  of  transcoded  data. 

ComponentResul t  ImageTranscoderDisposeData  ( 
ImageTranscoderComponent  itc, 

void  *dstData  ); 


i  tc 

The  image  transcoder  component. 
dstData 

A  pointer  to  the  transcoded  data. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

When  the  client  of  the  image  transcoder  component  is  done  with  a  piece  of 
transcoded  data,  this  function  must  be  called  with  a  pointer  to  the  transcoded  data. 
The  image  transcoder  component  should  not  make  any  assumptions  about  the 
maximum  number  of  outstanding  pieces  of  transcoded  data  or  the  order  in  which 
the  transcoding  data  will  be  disposed. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Image  Transcoder  Support"  (V-2873) 
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11-753 


ImageTranscoderEndSequence 


ImageT  ranscoderEndSequence 


Ends  an  image  transcoding  sequence. 

ComponentResul t  ImageTranscoderEndSequence  ( 
ImageTranscoderComponent  itc  ); 


i  tc 

The  image  transcoder  component  whose  transcoder  sequence  is  ending. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

ImageT  ranscoderEndSequence  is  called  when  there  are  no  more  frames  of  data  to  be 
transcoded  using  the  parameters  specified  in  the  previous  call  to 
ImageT ranscoderBegi  nSequence  (11-751).  After  calling  this  function,  the  component 
will  either  be  closed  or  receive  another  call  to  ImageTranscoderBegi  nSequence  with  a 
different  ImageDescri  pti  on  (IV-2285)  structure.  For  example,  the  dimensions  of  the 
source  image  may  be  different. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Image  Transcoder  Support"  (V-2873) 


ImageT  ranscodeSequenceBegin 


Initiates  an  image  transcoder  sequence  operation. 


OSErr  ImageTranscodeSequenceBegi n  ( 


ImageTranscodeSequence 

*i  ts , 

ImageDescri pti onHandle 

srcDesc , 

OSType 

destType 

ImageDescri pti onHandle 

*dstDesc 

voi  d 

*data , 

1  ong 

dataSi ze 

) : 


The  image  transcoder  sequence  identifier.  If  the  operation  fails,  the  value 
pointed  to  is  set  to  N I L. 


11-754 
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ImageTranscodeSequenceEnd 


srcDesc 

The  ImageDescri  pti  on  (IV-2285)  structure  for  the  source  compressed  image 
data. 
destType 

The  desired  compression  format  into  which  to  transcode  the  source  data. 
dstDesc 

On  return,  an  ImageDescri  pti  on  (IV-2285)  structure  for  the  data  which  will  be 
generated  by  the  image  transcoding  sequence. 

data 

A  pointer  to  first  frame  of  compressed  data  to  transcode.  Set  to  N I L  of  not 
available. 
dataSi ze 

The  size  of  the  compressed  data,  in  bytes.  Set  to  0  if  no  data  is  provided. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error.  If  no 
transcoder  is  available  to  perform  the  requested  transcoding 
operation,  a  cantFindHandler  error  is  returned. 

Discussion 

This  function  begins  an  image  transcoder  sequence  operation  and  returns  the 
sequence  identifier  in  the  i  ts  parameter.  The  caller  is  responsible  for  disposing  of 
the  ImageDescri  pti  on  structure  that  is  returned  in  the  dstDesc  parameter. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Image  Transcoder  Support"  (V-2873) 


ImageT  ranscodeSequenceEnd 


Ends  an  image  transcoder  sequence  operation. 

OSErr  ImageTranscodeSequenceEnd  ( 
ImageTranscodeSequence  its  ); 


i  ts 

The  identifier  of  the  image  transcoder  sequence  to  dispose.  It  is  safe  to  pass  a 
value  of  0  in  this  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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InitializeQHdr 


Discussion 

You  must  call  this  function  to  terminate  an  image  transcoder  sequence  operation 
and  dispose  of  the  sequence. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Image  Transcoder  Support"  (V-2873) 


InitializeQHdr 

Initializes  a  Windows  QHdr  (IV-2345)  structure  for  use  by  QuickTime. 

void  InitializeQHdr  ( 

QHdr  *qhdr  ); 


qhdr 

A  pointer  to  a  QHdr  (IV-2345)  structure. 

Discussion 

The  Ini  ti  al  i  zeQHdr  function  initializes  the  various  fields  of  the  Windows  queue 
header  to  startup  values  and  associates  a  mutex  with  the  queue  to  provide  safe 
access  via  Enqueue  (1-336)  and  Dequeue  (1-253).  The  mutex  identifier  is  stored  in  the 
MutexID  field  of  the  QHdr  (IV-2345)  structure.  Your  application  or  component  is  not 
required  to  manage  this  mutex;  Enqueue  and  Dequeue  will  handle  this  for  you.  A  QHdr 
structure  is  typically  used  by  QuickTime  image  decompressor  components  to 
manage  frame  queues.  Once  you  are  done  with  the  queue,  call  Termi  nateQHdr 
(III— 1926)  to  free  the  mutex. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML.  h 


InitializeQTML 


Initializes  the  QuickTime  Media  Layer. 

OSErr  InitializeQTML  ( 

1 ong  flag  ) ; 


11-756 
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InitializeQTML 


flag 

Flags  (see  below)  that  specify  several  options. 

function  result  Returns  an  error  if  QuickTime  is  not  installed  or  cannot  be 

initialized.  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no 
error. 

flag  Constants 

klnitiali  zeQTMLNoSoundFl  ag 

If  this  flag  is  set,  the  Sound  Manager  is  not  initialized  and  therefore  no  sound 
APIs  will  be  supported  during  the  session.  Use  this  flag  only  if  no  sound 
support  is  needed. 

klnitiali  zeQTMLUseGDI  FI  ag 

If  this  flag  is  set,  all  drawing  will  be  done  using  graphics  device  interface  (GDI) 
calls;  neither  DirectDraw  nor  DCI  services  will  be  used  for  onscreen  graphics 
support.  If  this  flag  is  not  set,  QuickTime  will  try  to  use  DirectDraw,  and  then 
DCI,  to  support  direct-to-surface  graphics  support  and  take  advantage  of  any 
hardware  acceleration  provided  by  these  services,  falling  back  to  GDI  only  if 
DirectDraw  and  DCI  are  unavailable.  You  should  normally  not  set  this  flag, 
klni ti al i zeQTMLDi sabl eDi rectSound 

Disable  QTML's  use  of  DirectSound. 
klnitiali zeQTMLUseExcl usi veFul 1 ScreenModeFl  ag 

Operate  exclusively  in  full  screen  mode,  in  versions  of  QuickTime  later  than  3.0. 

Discussion 

Use  this  function  to  initialize  a  QTML  session  before  calling  EnterMovi  es  (1-337).  If 
you  are  writing  a  routine  that  does  not  know  from  context  whether  this  function  has 
already  been  called,  add  a  call  to  it  at  the  beginning  of  the  routine  and  a  call  to 
Termi  nateQTML  (III— 1926)  at  the  end.  It  does  no  harm  to  call  this  function  more  than 
once,  as  long  as  each  call  is  nested  with  a  matching  call  to  Termi  nateQTML.  If  this 
function  has  already  been  called,  subsequent  calls  do  nothing  except  increment  a 
counter.  Calls  to  Termi  nateQTML  just  decrement  the  counter  (if  it  is  nonzero).  Only 
the  first  nested  call  to  this  function  and  the  last  nested  call  to  Termi  nateQTML  do  any 
actual  work,  so  there  is  no  penalty  for  having  nested  calls. 

Special  Considerations 

You  should  not  make  this  call  from  a  QuickTime  component  such  as  an  image 
decompressor;  it  is  provided  only  for  host  applications. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML .  h 
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Related  Java  Methods 

qui ckti me . QTSessi on . i ni ti al i ze( ) ,  qui ckti me . QTSessi on . open ( ) 


InitializeQTS 

Initializes  QuickTime  streaming. 

OSErr  InitializeQTS  (  void  ); 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


InitializeQTVR 


Initializes  QuickTime  virtual  reality. 

OSErr  InitializeQTVR  (  void  ); 

function  result  See  "Error  Codes"  (IV-2663).  If  this  function  is  unable  to  load  the 

Qui  ckTimeVR.  qtx  file,  it  returns  error  code  qtvrLibraryLoadErr.  If  you 
call  any  other  function  of  QuickTime  VR  before  calling  this  function 
or  after  this  function  has  failed  to  load  the  Qui  ckTimeVR.  qtx  file,  it 
returns  error  code  qtvrllni  ni  ti  al  i  zed.  It  returns  noErr  if  there  is  no 
error. 

Discussion 

This  function  and  Termi  nateQTVR  (III— 1927)  are  required  for  QuickTime  VR  to  run  in 
a  Windows  environment.  They  do  nothing  in  the  Mac  OS  environment,  but  must  be 
included  for  cross-platform  compatibility.  When  your  application  calls  this  function 
in  the  Windows  environment,  the  code  attempts  to  find  the  Qui  ckTi  meVR.  qtx  file 
through  the  normal  search  paths. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTimeVR.  h 

Programming  summary:  "Initializing  and  Terminating  QuickTime  VR"  (V-2904) 
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Related  Java  Methods 

qui ckti me . QTSessi on . i ni ti al i zeV R( ) 


InsertEmptyMovieSegment 

Adds  an  empty  segment  to  a  movie. 

OSErr  InsertEmptyMovieSegment  ( 

Movie  dstMovie, 

TimeValue  dstln, 

TimeValue  dstDuration  ); 

dstMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  or 
NewMovi  eFromHandl  e  (11-1084). 

dstln 

A  time  value  that  specifies  where  the  segment  is  to  be  inserted.  This  time  value 
must  be  expressed  in  the  movie's  time  scale. 

dstDurati on 

A  time  value  that  specifies  the  duration  of  the  segment  to  be  added.  This  time 
value  must  be  expressed  in  the  movie's  time  scale. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

You  specify  the  starting  time  and  duration  of  the  empty  segment  to  be  added.  These 
times  must  be  expressed  in  the  movie's  time  scale.  You  cannot  add  empty  space  to 
the  end  of  a  movie.  If  you  want  to  insert  a  segment  beyond  the  end  of  a  movie,  use 
InsertMovieSegment  (11-762). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Low-Level  Movie  Editing  Functions"  (V-2749) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . i nsert Empty Segment! ) 
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InsertEmptyT  rackSegment 

Adds  an  empty  segment  to  a  track. 

OSErr  InsertEmptyTrackSegment  ( 

Track  dstTrack, 

TimeValue  dstln, 

TimeValue  dstDuration  ); 

dstT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 
dstln 

A  time  value  specifying  where  the  segment  is  to  be  inserted.  This  time  value 
must  be  expressed  in  the  time  scale  of  the  movie  that  contains  the  destination 
track. 

dstDurati on 

A  time  value  that  specifies  the  duration  of  the  segment  to  be  added.  This  time 
value  must  be  expressed  in  the  time  scale  of  the  movie  that  contains  the 
destination  track. 

function  result  See  "Error  Codes"  (IV-2663).  If  you  try  to  add  an  empty  segment 
beyond  the  end  of  a  track,  this  function  does  not  add  the  empty 
segment  and  returns  a  result  code  of  i  nval  i  dTime.  Returns  noErr  if 
there  is  no  error. 

Discussion 

You  specify  the  starting  time  and  duration  of  the  empty  segment  to  be  added.  These 
times  must  be  expressed  in  the  movie's  time  scale.  This  function  then  inserts  the 
appropriate  amount  of  empty  time  into  the  track.  The  exact  meaning  of  the  term 
empty  time  depends  upon  the  type  of  track.  For  example,  empty  time  in  a  sound 
track  is  silence.  Note  that  you  cannot  add  empty  space  to  the  end  of  a  movie  or  to 
the  end  of  a  track. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Editing  Tracks"  (V-2750) 

Related  Java  Methods 

qui ckti me . std .movi es .Track. i nse rt Empty Segment ( ) 
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InsertMedialntoTrack 


InsertMedialntoT  rack 


Inserts  a  reference  to  a  media  segment  into  a  track. 


OSErr  InsertMed 
T  rack 
T i meVal ue 
T i meVal ue 
T i meVal ue 
Fi  xed 


alntoTrack  ( 
theTrack, 
trackStart, 
medi a Time, 
medi aDurati on , 
mediaRate  ); 


theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  or  GetMovi  eT rack  (1-497). 

trackStart 

A  time  value  specifying  where  the  segment  is  to  be  inserted.  This  time  value 
must  be  expressed  in  the  movie's  time  scale.  If  you  set  this  parameter  to  -1,  the 
media  data  is  added  to  the  end  of  the  track, 
medi a Time 

A  time  value  specifying  the  starting  point  of  the  segment  in  the  media.  This 
time  value  must  be  expressed  in  the  media's  time  scale, 
medi aDurati on 

A  time  value  specifying  the  duration  of  the  media's  segment.  This  time  value 
must  be  expressed  in  the  media's  time  scale. 

medi aRate 

The  media's  rate.  A  value  of  1.0  indicates  the  media's  natural  playback  rate. 
This  value  should  be  positive  and  not  0. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 


Discussion 

You  specify  the  segment  in  the  media  by  providing  a  starting  time  and  duration. 
You  specify  the  point  in  the  destination  track  by  providing  a  time  in  the  track. 
InsertMedialntoTrack  then  inserts  the  media  segment  into  the  track  at  the  specified 
location.  The  Movie  Toolbox  determines  the  duration  of  the  segment  in  the  track 
based  on  the  media  rate  and  duration  information  you  provide. 

Use  this  function  after  you  have  added  samples  to  a  media.  If  you  play  the  track 
before  you  call  this  function,  the  track  does  not  contain  the  new  media  data. 
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Here's  an  example  of  using  this  function  to  add  atom  containers  to  a  track: 

//InsertMedialntoTrack  coding  example 
long  descSize; 

QTVRSampl eDescriptionHandle  qtvrSampleDesc; 

//  Create  a  QTVR  sample  description  handle 

descSize  =  si zeoft QTVRSampl eDescri pti on )  +  GetHandleSizet (Handle)  vrWorld) 

-  sizeof(UInt32) ; 

qtvrSampleDesc  =  ( QTVRSampl eDescri pti onHandl e )  NewHandl eCl ear  (descSize); 
(*qtvrSampleDesc)->size  =  descSize; 

(*qtvrSampleDesc)->type  =  kQTVRQTVRType ; 

//  Copy  the  VR  world  atom  container  data  into  the  QTVR  sample  description 
BlockMove  (*( (Handle)  vrWorld),  &( (*qtvrSampleDesc)->data) , 

GetHandleSizet (Handle)  vrWorld)); 

//  Now  add  it  to  the  QTVR  track's  media 
err  =  BeginMediaEdi ts  (qtvrMedia); 

err  =  AddMedi aSampl e  (qtvrMedia,  (Handle)  nodeinfo,  0, 

GetHandleSizet (Handle)  nodeinfo),  duration, 

(SampleDescriptionHandle)  qtvrSampleDesc,  1,  0,  &sampl eTi me ) ; 
err  =  EndMediaEdi ts  (qtvrMedia); 

InsertMedialntoTrack  (qtvrTrack,  trackTime,  sampleTime,  duration,  1 L<< 1 6 ) ; 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Editing  Tracks"  (V-2750) 

Related  Java  Methods 

qu i ckti me. std. mo vies. Track. insert Med i a ( ) 


InsertMovieSegment 

Copies  part  of  one  movie  to  another. 

OSErr  InsertMovieSegment  ( 

Movie  srcMovie, 

Movie  dstMovie, 

TimeValue  srcln, 
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TimeValue  srcDuration, 

TimeValue  dstln  ); 

srcMovi e 

The  source  movie  for  this  operation.  Your  application  obtains  this  movie 
identifier  from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080), 
and  NewMovi  eFromHandl  e  (11-1084).  This  function  obtains  the  movie  segment 
from  the  source  movie  specified  in  this  parameter. 
dstMovi e 

The  destination  movie  for  this  operation.  The  function  places  a  copy  of  the 
segment,  which  it  obtained  from  the  source  movie,  into  this  destination  movie, 
srcln 

The  start  of  the  segment  in  the  source  movie.  This  time  value  must  be  expressed 
in  the  source  movie's  time  scale. 

srcDurati on 

The  duration  of  the  segment  in  the  source  movie.  This  time  value  must  be 
expressed  in  the  source  movie's  time  scale, 
dstln 

A  time  value  specifying  where  the  segment  is  to  be  inserted.  This  time  value 
must  be  expressed  in  the  destination  movie's  time  scale. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

If  you  are  not  copying  data  from  one  location  in  a  movie  to  a  different  point  in  the 
same  movie,  this  function  may  create  new  tracks,  as  appropriate.  Before  adding  a 
track  to  the  destination  movie,  the  Movie  Toolbox  looks  in  the  destination  movie  for 
tracks  that  have  the  same  characteristics  as  the  tracks  in  the  source  movie.  The 
toolbox  considers  several  characteristics  when  searching  for  an  appropriate  track, 
including  track  spatial  dimensions,  track  matrix,  track  clipping  region,  track  matte, 
alternate  group  affiliation,  media  time  scale,  media  type,  media  language,  and  data 
reference  (that  is,  referring  to  the  same  file).  If  the  Movie  Toolbox  cannot  find  an 
appropriate  track  in  the  destination  movie,  it  creates  a  new  track  with  the  proper 
characteristics. 

Special  Considerations 

If  you  have  assigned  a  progress  function  to  the  destination  movie,  the  Movie 
Toolbox  calls  that  progress  function  during  long  copy  operations.  Some  Movie 
Toolbox  functions  can  take  a  long  time  to  execute.  For  example,  if  you  call 
FI  attenMovi  e  (1-372)  and  specify  a  large  movie,  the  Movie  Toolbox  must  read  and 
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write  all  the  sample  data  for  the  movie.  During  such  operations  you  may  wish  to 
display  some  kind  of  progress  indicator  to  the  user. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Low-Level  Movie  Editing  Functions"  (V-2749) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . i nsertSegment ( ) 


InsertT  rackSegment 


Copies  data  into  a  track. 


OSErr  InsertT 
T  rack 
T  rack 
TimeVal ue 
TimeVal ue 
TimeVal ue 


ckSegment  ( 
srcTrack, 
dstT  rack , 
srcln , 

srcDurati on , 
dstln  ) ; 


ra 


srcTrack 

The  source  track  for  this  operation.  Your  application  obtains  this  track  identifier 
from  such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi eT rack  (1-497). 

dstT  rack 

The  destination  track  for  this  operation.  This  function  places  a  copy  of  the 
segment,  which  is  obtained  from  the  source  track,  into  this  destination  track. 
The  media  for  the  destination  track  must  be  opened  for  writing  by  calling 
Begi  nMedi  a  Ed  1  ts  (1-56)  in  order  for  the  data  to  be  copied.  If  the  media  is  not 
opened  for  writing,  the  segment  will  be  copied  by  reference.  At  the  end  of  the 
editing  session,  your  application  must  call  EndMedi  a  Edi  ts  (1-335)  if  it  has  called 
Begi nMedi a  Ed i ts. 
srcln 

The  start  of  the  segment  in  the  source  track.  This  time  value  must  be  expressed 
in  the  time  scale  of  the  movie  that  contains  the  source  track. 

srcDurati on 

The  duration  of  the  segment  in  the  source  track.  This  time  value  must  be 
expressed  in  the  time  scale  of  the  movie  that  contains  the  source  track. 
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dstln 

A  time  value  specifying  where  the  segment  is  to  be  inserted.  This  time  value 
must  be  expressed  in  the  time  scale  of  the  movie  that  contains  the  destination 
track. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

If  you  are  copying  data  between  tracks,  make  sure  that  the  two  tracks  are  of  the 
same  type.  For  example,  you  cannot  copy  a  segment  from  a  sound  track  into  a  video 
track.  If  you  have  assigned  a  progress  function  to  the  movie  that  contains  the 
destination  track,  the  Movie  Toolbox  calls  that  progress  function  during  long  copy 
operations. 

Special  Considerations 

If  you  copy  a  segment  without  calling  Begi  nMedi  a  Ed  1  ts  on  the  destination  track's 
media,  the  data  can  be  copied  later  by  flattening  the  movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Editing  Tracks"  (V-2750) 

Related  Java  Methods 

qui ckti me . std .movi es . Track. i nsertSegment( ) 


InstrumentCloseComponentResFile 


Closes  a  resource  file. 

ComponentResul t  InstrumentCl oseComponentResFi 1 e  ( 
Componentlnstance  ci  , 

short  resFile  ); 


ci 

An  instrument  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
resFi  1  e 

A  reference  to  a  resource  file,  returned  previously  by 
InstrumentOpenComponentResFi  1  e  (11-770). 
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function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c . h 

Programming  summary:  "Instrument  Component  Functions"  (V-2923) 


InstrumentGetComponentRefCon 


Obtains  the  reference  constant  for  an  instrument  component. 

ComponentResul t  InstrumentGetComponentRefCon  ( 
Componentlnstance  ci  , 

void  **refCon  ); 


ci 

An  instrument  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

refCon 

A  reference  constant. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Instrument  Component  Functions"  (V-2923) 

See  Also 

For  the  corresponding  set  function,  see  InstrumentSetComponentRefCon  (11-771). 


InstrumentGetlnfo 


Returns  information  about  all  the  atomic  instruments  supported  by  an  instrument 
component. 


ComponentResul t  InstrumentGetlnfo  ( 
Componentlnstance  ci , 

long  getlnstrumentlnfoFl ags , 

InstCompInfoHandl e  *instInfo  ); 
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ci 

An  instrument  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
get  Instrument  Info  FI  ags 

Flags  (see  below)  that  specify  whether  you  want  a  list  of  fixed  instruments, 
modifiable  instruments,  or  all  instruments. 

i nstlnfo 

On  return,  an  InstCompInfo  (IV-2291)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

getlnstrumentlnfoFlags  Constants 

kGetlnstrumentlnfoNoBui 1  tin 

Don't  return  built-in  instruments. 
kGetlnstrumentlnfoMi diUserlnst 

Do  return  user  instruments  for  a  MIDI  device. 
kGet Instrument  Inf oNoIText 

Don't  return  international  text  strings. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusIc.h 

Programming  summary:  "Instrument  Component  Functions"  (V-2923) 


InstrumentGetlnst 


Returns  an  atomic  instrument. 


ComponentResul t  InstrumentGetlnst  ( 
Componentlnstance  ci , 

1 ong  i nstID , 

Atomi clnstrument  *atomicInst, 

long  flags  ); 


ci 

An  instrument  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

i  n  s  1 1 D 

The  instrument  component  instrument  ID  from  the  InstCompInfo  (IV-2291) 
structure  returned  by  InstrumentGetlnfo  (11-766). 
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atomi clnst 

On  return,  the  atomic  instrument, 
fl  ags 

Constants  (see  below)  that  specify  what  pieces  of  information  about  an  atomic 
instrument  the  caller  is  interested  in. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

kGet Atomi clnstNoExpandedSampl  es 
Eliminate  the  expanded  samples. 
kGet Atomi clnstNoOriginal Samples 
Eliminate  the  original  samples. 
kGet Atomi clnstNoSamples 

Eliminate  both  the  original  and  expanded  samples. 
kGet Atomi clnstNoKnobList 
Eliminate  the  knob  list. 
kGet Atomi clnst No  Instrument  Info 

Eliminate  the  About  box  information. 
kGet  Atomi  clnstOriginalKnobList 
Include  the  original  knob  list. 
kGet Atomi clnstAl  1  Knobs 

Include  the  current  knob  list. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Instrument  Component  Functions"  (V-2923) 

InstrumentGetSynthesizerType 

Obtains  the  synthesizer  type  for  an  instrument. 

ComponentResul t  InstrumentGetSynthesizerType  ( 

Componentlnstance  ci , 

OSType  *synthesi zerType  ); 
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ci 

An  instrument  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
synthesi zerType 

Pointer  to  the  returned  type  (see  below). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

synthesizerType  Constants 

kSoftSynthComponentSubType 

The  QuickTime  music  synthesizer.  This  is  the  built-in  synthesizer.  Value  is 
’  ss  '  (3rd  and  4th  characters  are  spaces). 
kGMSynthComponentSubType 

The  General  MIDI  synthesizer.  Value  is  '  gm  '  (3rd  and  4th  characters  are 
spaces). 

Discussion 

This  function  returns  the  synthesizer  type  (the  subtype  of  the  synthesizer 
component)  associated  with  a  given  instrument  component. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier.  Older  instrument  components  (developed 
before  QuickTime  2)  may  not  support  this  call. 

Programming  Info 

C  interface  file:  QuickTimeMusIc.h 


Instrumentlnitialize 


Tells  the  base  class  instrument  component  how  to  interpret  the  instrument 
component  resources. 

ComponentResul t  Instrumentlnitialize  ( 

Componentlnstance  ci  , 

long  initFormat, 

void  *initParams  ); 


ci 

An  instrument  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
i ni t Format 
Set  to  0. 


Inside  QuickTime:  Function  l-Q 


11-769 


InstrumentOpenComponentResFile 


i ni tParams 
Set  to  N I L. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Used  by  developers  of  instrument  components,  this  is  a  call  the  instrument 
component  makes  to  the  base  class  instrument  component  to  tell  it  how  to  interpret 
the  instrument  component  resources. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Instrument  Component  Functions"  (V-2923) 


InstrumentOpenComponentResFile 


Opens  a  resource  file  containing  instruments  in  the  instrument  component  and 
makes  it  the  current  resource  file. 

ComponentResul t  InstrumentOpenComponentResFile  ( 

Componentlnstance  ci  , 

short  *resFi 1 e  ) ; 


ci 

An  instrument  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

resFi  1  e 

On  return,  a  resource  reference. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Instrument  Component  Functions"  (V-2923) 
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InstrumentSetComponentRefCon 


InstrumentSetComponentRefCon 


Overrides  SetComponentRefcon  (III— 1573)  and  sets  an  instrument  component's 
reference  constant  to  a  specified  value. 

ComponentResul t  InstrumentSetComponentRefCon  ( 

Componentlnstance  ci  , 

void  *refCon  ); 


ci 

An  instrument  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

refCon 

A  reference  constant. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

See  Also 

For  the  corresponding  get  function,  see  InstrumentGetComponentRefCon  (11-766). 


InvalidateMovieRegion 


Invalidates  a  small  area  of  a  movie. 

OSErr  InvalidateMovieRegion  ( 
Movie  theMovie, 

RgnHandle  invalidRgn  ); 


theMovi e 

The  movie  whose  area  you  wish  to  invalidate.  Your  application  obtains  this 
movie  identifier  from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e 
(11-1080),  and  NewMovi eFromHandl  e  (11-1084). 
invalidRgn 

A  region  indicating  the  area  of  the  movie  to  invalidate.  If  necessary,  QuickTime 
will  make  a  copy  of  this  region.  To  invalidate  the  entire  movie  area,  pass  N I L  for 
this  parameter. 


Inside  QuickTime:  Function  l-Q 
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InvalidateSprite 


function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

Use  this  function  instead  of  UpdateMovi  e  (III— 1981)  to  invalidate  a  small  area  of  a 
movie.  It  marks  all  areas  of  the  movie  that  intersect  the  i  nval  i  dRgn  parameter.  The 
next  time  you  call  Movi  esTask  (11-973),  the  Movie  Toolbox  redraws  the  marked 
areas.  This  provides  a  way  to  invalidate  a  portion  of  the  movie's  area  instead  of  its 
entire  area,  as  does  UpdateMovi  e.  This  allows  for  higher  performance  update 
handling  when  a  movie  has  many  tracks  or  covers  a  large  area.  For  handling  of 
update  events,  applications  should  continue  to  use  UpdateMovi  e. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Movies  and  Your  Event  Loop"  (V-2720) 

Related  Java  Methods 

qu ickti me. std. mo vies. Mo vie. invalidate RegionO 


InvalidateSprite 

Invalidates  the  portion  of  a  sprite's  sprite  world  that  is  occupied  by  a  sprite. 

void  InvalidateSprite  ( 

Spri te  theSpri te  ) ; 

theSpri te 

The  sprite  for  this  operation. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

In  most  cases,  you  do  not  need  to  call  this  function.  When  you  call 
SetSpri  teProperty  (III— 1641)  to  modify  a  sprite's  properties,  it  takes  care  of 
invalidating  the  appropriate  regions  of  the  sprite  world.  However,  you  might  call 
this  function  if  you  change  a  sprite's  image  data  but  retain  the  same  image  data 
pointer. 


11-772 


Inside  QuickTime:  Function  l-Q 


InvalidateSprite  World 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Creating  and  Manipulating  Sprites"  (V-2901) 

Related  Java  Methods 

qui cktime . std . anim. Spri te . i nval i date( ) 


InvalidateSpriteW  orld 

Invalidates  a  rectangular  area  of  a  sprite  world. 

OSErr  Inval idateSpri teWorl d  ( 

SpriteWorld  theSpri  teWorl  d  , 

Rect  *i nval  i dArea  ); 

theSpri teWorl d 

The  sprite  world  for  this  operation, 
i nval i dArea 

A  pointer  to  the  Rect  (IV-2399)  structure  that  defines  the  area  that  should  be 
invalidated.  This  rectangle  should  be  specified  in  the  sprite  world's  source 
space,  which  is  the  coordinate  system  of  the  sprite  layer's  graphics  world  before 
the  sprite  world's  matrix  is  applied  to  it.  To  invalidate  the  entire  sprite  world, 
pass  N I L  for  this  parameter. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

Typically,  your  application  calls  this  function  when  the  sprite  world's  destination 
window  receives  an  update  event.  Invalidating  an  area  of  the  sprite  world  will 
cause  the  area  to  be  redrawn  the  next  time  that  Spri  teWorl  dldl  e  (III— 1908)  is  called. 

Special  Considerations 

When  you  modify  sprite  properties,  invalidation  takes  place  automatically;  you  do 
not  need  to  call  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Function  l-Q 
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InverseMatrix 


Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  with  Sprite  Worlds"  (V-2900) 

Related  Java  Methods 

qui cktime. std . anim. Spri teWorl d ,i nval idate( ) 


InverseMatrix 


Creates  a  new  matrix  that  is  the  inverse  of  a  specified  matrix. 

Boolean  InverseMatrix  ( 

const  MatrixRecord  *m, 

Matri xRecord  *i m  ) ; 


m 

A  pointer  to  the  source  MatrixRecord  (IV-2304)  structure  for  the  operation, 
i  no 

A  pointer  to  aMatri  xRecord  (IV-2304)  structure  that  is  to  receive  the  new 
matrix.  The  function  updates  this  structure  so  that  it  contains  a  matrix  that  is 
the  inverse  of  that  specified  by  the  m  parameter. 

function  result  A  Bool  ean  value  of  TRUE  if  InverseMatrix  was  able  to  create  an  inverse 
matrix,  FALSE  otherwise. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Matrices"  (V-2764) 

Related  Java  Methods 

qui cktime. std . image .Matrix. i nverseC ) 


IsMovieDone 


Determines  if  a  particular  movie  has  completely  finished  playing. 

Boolean  IsMovieDone  ( 

Movi e  theMovi e  ) ; 
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Inside  QuickTime:  Function  l-Q 


IsScrapMovie 


theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  Returns  TRUE  if  the  specified  movie  has  finished  playing,  otherwise 
returns  FALSE. 

Discussion 

A  movie  with  a  positive  rate  (playing  forward)  is  considered  done  when  its  movie 
time  reaches  the  movie  end  time.  Conversely,  a  movie  with  a  negative  rate  (playing 
backward)  is  considered  done  when  its  movie  time  reaches  the  movie  start  time.  If 
your  application  has  changed  the  movie's  active  segment,  the  status  returned  by 
this  function  is  relative  to  the  active  segment,  rather  than  to  the  entire  movie.  You 
can  use  SetMovi  eActi  veSegment  (III— 1609)  to  change  a  movie's  active  segment. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movl  es  .  h 

Programming  summary:  "Movies  and  Your  Event  Loop"  (V-2720) 

Related  Java  Methods 

qui cktime . std .movi es . Movi e . i sDone( ) 


IsScrapMovie 


Checks  the  system  scrap  to  find  out  if  it  can  translate  any  of  the  data  into  a  movie. 

Component  IsScrapMovie  ( 

Track  targetTrack  ); 


targetTrack 

The  location  of  the  potential  target  movie  track  for  the  data  on  the  system  scrap. 


function  result  If  IsScrapMovi  e  finds  an  appropriate  type,  it  returns  a  movie  import 
component  that  can  translate  the  scrap.  Otherwise,  it  returns  0. 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "High-Level  Movie  Editing  Functions"  (V-2746) 


Inside  QuickTime:  Function  l-Q 
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IsTaskBar  Visible 


Related  Java  Methods 

qu ickti me. std. mo vies. Track. isScrapMoviet), 

qui ckti me . std . qt components .  Movi e Importer . f romT rack! ) 


IsTaskBarVisible 

Returns  the  current  visibility  state  of  the  task  bar. 

Boolean  IsTaskBarVisible  (  void  ); 

function  result  Returns  TRUE  if  the  task  bar  is  visible,  FALSE  otherwise. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML.h 


IT  ext  AddString 


Undocumented 


OSErr  ITextAddString  ( 

QTAtomContai ner 
QTAtom 
Regi onCode 
ConstStr255Param 

contai ner 

Undocumented 
parentAtom 

Undocumented 
theRegi onCode 

A  16-bit  signed  integer  containing  an  international  region  code;  see 
“Localization  Codes"  (IV-2673) . 
theStri ng 

The  string  to  add. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 


contai ner , 
parentAtom, 
theRegi onCode , 
theStri ng  ) ; 
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ITextGetString 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Related  Java  Methods 

qui cktime . std .movi es . AtomContai ner . i Text Add St ri ng( ) 


ITextGetString 


Undocumented 


OSErr  ITextGetString 
QTAtomContai ner 
QTAtom 
Regi onCode 
Regi onCode 
Stri ngPtr 


contai ner , 
parentAtom, 
requestedRegi on , 
*f oundRegi on , 
theString  ); 


contai ner 

Undocumented 

parentAtom 

Undocumented 
requestedRegi on 
Undocumented 
f oundRegi on 

On  return,  a  16-bit  signed  integer  containing  an  international  region  code;  see 
"Localization  Codes"  (IV-2673). 

theStri ng 

The  found  string. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Related  Java  Methods 

qui cktime . std .movi es .AtomContai ner . iTextGetStri ng( ) 


Inside  QuickTime:  Function  l-Q 
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ITextRemoveString 


IT  extRemo  veString 

Undocumented 

OSErr  ITextRemoveString  ( 

QTAtomContai ner  container, 

QTAtom  parentAtom, 

RegionCode  theRegi onCode , 

1 ong  f  1  ags  ) ; 

contai ner 

Undocumented 

parentAtom 

Undocumented 
theRegi onCode 

A  16-bit  signed  integer  containing  an  international  region  code;  see 
“Localization  Codes"  (IV-2673). 
fl  ags 

Flags  (see  below)  that  modify  the  process. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

flags  Constants 

k  I  Text Remove  Eve ryt hi  ngBut 
Undocumented 

k  I  Text Remove  Lea veSuggestedAl  ternate 
Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Related  Java  Methods 

qui ckti me . std .movi es . AtomContai ner . iTextRemoveStri ng( ) 
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LoadMedialntoRam 


L 


LoadMedialntoRam 

Loads  a  media's  data  into  memory. 

OSErr  LoadMedialntoRam  ( 

Media  theMedia, 

TimeValue  time, 

TimeValue  duration, 

long  flags  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 

ti  me 

The  starting  time  of  the  media  segment  to  load.  This  time  value  must  be 
expressed  in  the  media's  time  coordinate  system. 

durati on 

The  length  of  the  segment  to  load.  Use  GetMedi  aDurati  on  (1-430)  to  determine 
the  length  of  the  entire  media.  Note  that  the  media  handler  may  load  more  data 
than  you  specify  if  the  media  data  was  added  in  larger  pieces, 
fl  ags 

Flags  (see  below)  that  give  you  explicit  control  over  what  is  loaded  into 
memory  and  how  long  to  keep  it  around.  You  can  set  these  flags  in  any 
combination. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Flags  Constants 

keepInRam 

Renders  all  data  loaded  with  this  flag  set  as  nonpurgeable.  Nonpurgeable  data 
is  not  released  from  memory  until  you  request  it  explicitly.  This  practice  can  fill 
up  the  user's  heap  very  quickly;  exercise  caution. 

unkeepInRam 

Renders  all  indicated  data  purgeable.  The  data  is  not  necessarily  released  from 
memory  immediately,  however.  Information  about  whether  a  chunk  can  be 
purged  is  maintained  internally  by  a  single  bit.  This  means  there  is  no  counter. 


Inside  QuickTime:  Function  l-Q 


11-779 


LoadMedialntoRam 


Therefore,  if  you  care  very  much  about  the  data,  you  have  to  work  very  hard 
and  use  the  edit  list  meticulously. 

fl ushFromRam 

Purges  all  indicated  data  from  memory,  unless  it  is  currently  in  use  by  a  media 
handler  (for  example,  if  it  is  still  drawing  frames  from  the  requested  times). 
This  flag  makes  the  memory  available  for  purging,  and  then  performs  the 
purge.  You  may  want  to  use  this  option  if  you  are  particularly  low  on  memory. 

1 oadForwardT  rackEdi ts 

In  some  cases,  an  edited  movie  plays  back  much  more  smoothly  if  the  data 
around  edits  is  already  in  RAM.  By  setting  either  this  flag  or  the 
1  oadBackwardT rackEdi  ts  flag,  you  can  load  only  the  data  around  edits.  The 
Movie  Toolbox  walks  through  the  edits  and  decides  the  right  amount  of  data  to 
load  for  you.  If  you  are  going  to  play  the  movie  forward,  set  only  the 
1  oadForwardTrackEdi  ts  flag.  If  you  are  going  to  play  in  both  directions,  or  you 
don't  know  which  direction,  set  both  flags. 

1 oadBackwardTrackEdi ts 

In  some  cases,  an  edited  movie  plays  back  much  more  smoothly  if  the  data 
around  edits  is  already  in  RAM.  By  setting  either  this  flag  or 
1  oadForwardTrackEdi  ts,  you  can  load  only  the  data  around  edits.  The  Movie 
Toolbox  walks  through  the  edits  and  decides  the  right  amount  of  data  to  load 
for  you.  If  you  are  going  to  play  the  movie  only  backward,  set  the 
1  oadBackwardTrackEdi  ts  flag.  If  you  are  going  to  play  in  both  directions,  or  you 
don't  know  which  direction,  set  both  flags. 

Discussion 

The  exact  behavior  of  LoadMedialntoRam  is  dependent  on  the  media  handler. 


Special  Considerations 

If  LoadMedi  a  IntoRam  fails  because  it  is  out  of  memory,  no  data  is  purged. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Enhancing  Movie  Playback  Performance"  (V-2722) 

Related  Java  Methods 

quicktime.std.movies.media.Media.loadlntoRamO 
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LoadMovielntoRam 


LoadMovielntoRam 

Loads  a  movie's  data  into  memory. 

OSErr  LoadMovielntoRam  ( 

Movie  theMovie, 

TimeValue  time, 

TimeValue  duration, 

long  flags  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

ti  me 

The  starting  time  of  the  movie  segment  to  load, 
durati on 

The  length  of  the  segment  to  load.  Use  GetMovi eDurati  on  (1-470)  to  determine 
the  length  of  the  entire  movie.  Note  that  the  Movie  Toolbox  may  load  more  data 
than  you  specify  due  to  the  way  the  data  is  loaded. 

fl  ags 

Flags  (see  below)  that  give  you  explicit  control  over  what  is  loaded  into 
memory  and  how  long  to  keep  it  around.  You  can  set  these  flags  in  any 
combination. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Flags  Constants 

keepInRam 

Renders  all  data  loaded  with  this  flag  set  as  nonpurgeable.  Nonpurgeable  data 
is  not  released  from  memory  until  you  request  it  explicitly.  This  practice  can  fill 
up  the  user's  heap  very  quickly;  exercise  caution. 

unkeepInRam 

Renders  all  indicated  data  purgeable.  The  data  is  not  necessarily  released  from 
memory  immediately,  however.  Information  about  whether  a  chunk  can  be 
purged  is  maintained  internally  by  a  single  bit.  This  means  there  is  no  counter. 
Therefore,  if  you  care  very  much  about  the  data,  you  have  to  work  very  hard 
and  use  the  edit  list  meticulously. 
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11-781 


LoadTracklntoRam 


fl ushFromRam 

Purges  all  indicated  data  from  memory,  unless  it  is  currently  in  use  by  a  media 
handler  (for  example,  if  it  is  still  drawing  frames  from  the  requested  times). 
This  flag  makes  the  memory  available  for  purging,  and  then  performs  the 
purge.  You  may  want  to  use  this  option  if  you  are  particularly  low  on  memory. 
1 oadForwardT  rackEdits 

In  some  cases,  an  edited  movie  plays  back  much  more  smoothly  if  the  data 
around  edits  is  already  in  RAM.  By  setting  either  this  flag  or  the 
1  oadBackwardTrackEdi  ts  flag,  you  can  load  only  the  data  around  edits.  The 
Movie  Toolbox  walks  through  the  edits  and  decides  the  right  amount  of  data  to 
load  for  you.  If  you  are  going  to  play  the  movie  forward,  set  only  the 
1  oadForwardT rackEdi  ts  flag.  If  you  are  going  to  play  in  both  directions,  or  you 
don't  know  which  direction,  set  both  flags. 

1 oadBackwardT  rackEdits 

In  some  cases,  an  edited  movie  plays  back  much  more  smoothly  if  the  data 
around  edits  is  already  in  RAM.  By  setting  either  this  flag  or 
1  oadForwardT  rackEdi  ts,  you  can  load  only  the  data  around  edits.  The  Movie 
Toolbox  walks  through  the  edits  and  decides  the  right  amount  of  data  to  load 
for  you.  If  you  are  going  to  play  the  movie  only  backward,  set  the 
loadBackwardTrackEdits  flag.  If  you  are  going  to  play  in  both  directions,  or  you 
don't  know  which  direction,  set  both  flags. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Enhancing  Movie  Playback  Performance"  (V-2722) 

Related  Java  Methods 

qui cktime. std .movi es .Movi e . 1 oadlntoRamt ) 


LoadT  racklntoRam 


Loads  a  track's  data  into  memory. 


OSErr  LoadTracklntoRam  ( 
Track  theTrack, 

TimeValue  time, 

TimeValue  duration, 

1 ong  f 1 ags  ) ; 
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LoadTracklntoRam 


theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

ti  me 

The  starting  time  of  the  track  segment  to  load.  You  must  specify  this  time  value 
in  the  movie's  time  coordinate  system. 

durati on 

The  length  of  the  segment  to  load.  Use  GetT rackDurati  on  (1-529)  to  determine 
the  length  of  the  entire  movie.  Note  that  the  media  handler  may  load  more  data 
than  you  specify. 

fl  ags 

Flags  (see  below)  that  give  you  explicit  control  over  what  is  loaded  into 
memory  and  how  long  to  keep  it  around.  You  can  set  these  flags  in  any 
combination. 


function  result  If  the  track  does  not  fit,  the  function  returns  an  error.  See  "Error 
Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Flags  Constants 

keepInRam 

Renders  all  data  loaded  with  this  flag  set  as  nonpurgeable.  Nonpurgeable  data 
is  not  released  from  memory  until  you  request  it  explicitly.  This  practice  can  fill 
up  the  user's  heap  very  quickly;  exercise  caution. 

unkeepInRam 

Renders  all  indicated  data  purgeable.  The  data  is  not  necessarily  released  from 
memory  immediately,  however.  Information  about  whether  a  chunk  can  be 
purged  is  maintained  internally  by  a  single  bit.  This  means  there  is  no  counter. 
Therefore,  if  you  care  very  much  about  the  data,  you  have  to  work  very  hard 
and  use  the  edit  list  meticulously, 
fl ushFromRam 

Purges  all  indicated  data  from  memory,  unless  it  is  currently  in  use  by  a  media 
handler  (for  example,  if  it  is  still  drawing  frames  from  the  requested  times). 
This  flag  makes  the  memory  available  for  purging,  and  then  performs  the 
purge.  You  may  want  to  use  this  option  if  you  are  particularly  low  on  memory. 
1 oadForwardT  rackEdi ts 

In  some  cases,  an  edited  movie  plays  back  much  more  smoothly  if  the  data 
around  edits  is  already  in  RAM.  By  setting  either  this  flag  or  the 
loadBackwardTrackEdits  flag,  you  can  load  only  the  data  around  edits .  The 
Movie  Toolbox  walks  through  the  edits  and  decides  the  right  amount  of  data  to 
load  for  you.  If  you  are  going  to  play  the  movie  forward,  set  only  the 
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1  oadForwardT rackEdi  ts  flag.  If  you  are  going  to  play  in  both  directions,  or  you 
don't  know  which  direction,  set  both  flags. 

1 oadBackwardT rackEdi  ts 

In  some  cases,  an  edited  movie  plays  back  much  more  smoothly  if  the  data 
around  edits  is  already  in  RAM.  By  setting  either  this  flag  or 
1  oadForwardT  rackEdi  ts,  you  can  load  only  the  data  around  edits.  The  Movie 
Toolbox  walks  through  the  edits  and  decides  the  right  amount  of  data  to  load 
for  you.  If  you  are  going  to  play  the  movie  only  backward,  set  the 
loadBackwardTrackEdits  flag.  If  you  are  going  to  play  in  both  directions,  or  you 
don't  know  which  direction,  set  both  flags. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Enhancing  Movie  Playback  Performance"  (V-2722) 

Related  Java  Methods 

qu ickti me. std. mo vies. Track. loadlntoRamt) 


MACEVersion 

Obsolete. 

NumVersion  MACEVersion  (  void  ); 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier.  Macintosh  Note:  Not  supported  by 

CarbonLib. 

Programming  Info 

C  interface  file:  Sound .  h 


MakeFilePreview 


Creates  a  preview  for  a  file. 
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OSErr  MakeFi 1 ePreview  ( 

short  resRefNum, 

ICMProgressProcRecordPtr  progress  ); 

resRefNum 

The  resource  file  for  this  operation.  You  must  have  opened  this  resource  file 
with  write  permission.  If  there  is  a  preview  in  the  specified  file,  the  Movie 
Toolbox  replaces  that  preview  with  a  new  one. 
progress 

A  pointer  to  an  ICMProgressProcRecord  (IV-2284)  structure.  During  the  process 
of  creating  the  preview,  the  Movie  Toolbox  may  occasionally  call  a  function 
you  provide  in  order  to  report  its  progress.  You  can  then  use  this  information 
to  keep  the  user  informed. 

Set  this  parameter  to  -1  to  use  the  default  progress  function.  If  you  specify  a 
progress  function,  it  must  comply  with  the  interface  defined  for  Image 
Compression  Manager  progress  functions;  see  "Image  Compression  Manager" 
in  Inside  Macintosh:  QuickTime  (listed  in  the  bibliography)  for  more 
information.  Set  this  parameter  to  N I L  to  prevent  the  Movie  Toolbox  from 
calling  a  progress  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  should  create  a  preview  whenever  you  save  a  movie.  You  specify  the  file  by 
supplying  a  reference  to  its  resource  file.  You  must  have  opened  this  resource  file 
with  write  permission.  If  there  is  a  preview  in  the  specified  file,  the  Movie  Toolbox 
replaces  that  preview  with  a  new  one. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Creating  File  Previews"  (V-2757) 


MakelmageDescriptionForEffect 


Returns  an  ImageDescri  pti  on  (IV-2285)  structure  you  can  use  to  help  create  a 
sample  description  for  an  effect. 

OSErr  MakelmageDescriptionForEffect  ( 

OSType  effectType, 
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ImageDescri pti onHandl e  *idh  ); 
effectType 

The  four-character  code  identifying  the  type  of  effect  to  make  an  image 
description  for.  See  "Effects  Codes"  (IV-2662). 

i  dh 

The  handle  of  an  ImageDescri  pti  on  (IV-2285)  structure.  On  entry,  this 
parameter  normally  points  to  an  ImageDescri  pti  on  structure  whose  contents 
are  NIL.  On  return,  the  structure  is  correctly  filled  out  for  the  selected  effect 
type. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

To  create  a  sample  description,  you  create  and  fill  out  a  data  structure  of  type 
ImageDescri  pti  on  (IV-2285).  This  function  simplifies  this  process.  Only  sample 
descriptions  made  with  this  function  can  be  used  in  stacked  effects,  where  one  effect 
track  acts  as  a  source  for  another. 


The  following  sample  code  creates  a  sample  description:. 

//  MakelmageDescriptionForEffect  coding  example 

//  Return  a  new  image  description  with  default  and  specified  values. 


ImageDescri pti onHandl e  QTEffSeg_MakeSampl eDescri pti on  ( 
OSType  theEffectType ,  short  theWidth, 


{ 


ImageDescri pti onHandl e  mySampleDesc  =  NIL; 

#if  USES_MAKE_IMAGE_DESC_FOR_EFFECT 

OSErr  myErr  =  noErr; 


short  theHeight) 


//  create  a  new  sample  description 

myErr  =  MakelmageDescriptionForEffectttheEffectType,  &mySampl eDesc) ; 
if  (myErr  !=  noErr) 
return(NIL) ; 

#el  se 

//  create  a  new  sample  description 
mySampleDesc  =  ( ImageDescri pti onHandl e ) 

NewHandl eCl ear( si zeof( ImageDescri pti on) ) ; 

if  (mySampleDesc  ==  NIL) 
return(NIL) ; 
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//  fill  in  the  fields  of  the  sample  description 
(**mySampl eDesc) . cType  =  theEf fectType ; 

(**mySampl eDesc) . idSi ze  =  si zeof ( ImageDescri pti on ) ; 

(**mySampl eDesc) . hRes  =  72L  <<  16; 

(**mySampl eDesc) . vRes  =  72L  <<  16; 

(**mySampl eDesc) . frameCount  =  1; 

(**mySampl eDesc) .depth  =  0; 

(**mySampl eDesc) . cl utID  =  -1; 

#endi f 

(**mySampl eDesc) . vendor  =  kAppl eManuf acturer ; 

(**mySampl eDesc) . temporal Qual i ty  =  codecNormal Qual i ty ; 

(**mySampl eDesc) . spati al Qual i ty  =  codecNormal Qual i ty ; 

(**mySampl eDesc) .width  =  theWidth; 

(**mySampl eDesc) . height  =  theHeight; 

return! my Sampl eDesc) ; 

} 

Version  Notes 

Introduced  in  QuickTime  4.  Image  descriptions  built  using  sample  code  from  earlier 
versions  of  QuickTime  cannot  be  used  when  stacking  effects. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Creating  an  Effect  Sample  Description"  (V-2898) 

MakelmageDescriptionForPixMap 

Fills  out  an  ImageDescri  pti  on  (IV-2285)  structure  corresponding  to  a  Pi  xMap 
(IV-2332)  structure. 

OSErr  MakelmageDescriptionForPixMap  ( 

PixMapHandle  pixmap, 

ImageDescri pti onHandl e  *idh  ); 

pi xmap 

A  handle  to  a  Pi  xMap  (IV-2332)  structure. 
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i  dh 

The  handle  of  an  ImageDescri  pti  on  (IV-2285)  structure.  On  entry,  this 
parameter  normally  points  to  an  ImageDescri  pti  on  structure  whose  contents 
are  NIL.  On  return,  the  structure  is  correctly  filled  out  for  the  selected  Pi xMap. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Related  Java  Methods 

quicktime.std.image.ImageDescription.ImageDescriptiont) 


MakeMediaT  imeT  able 


Returns  a  time  table  for  the  specified  media. 


OSErr  MakeMediaTimeTable  ( 


Medi  a 
1  ong 

TimeVal ue 
TimeVal ue 
TimeVal ue 
short 
short 
1  ong 


theMedi a , 

**offsets , 

startTime, 

endT i me , 

ti melncrement , 

f i rst Data  Ref Index , 

1 astDataRef Index , 

*retdataRefSkew  ) ; 


theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  identifier  from  such 
functions  as  NewTrackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 

offsets 

A  handle  to  an  unlocked  relocatable  memory  block  allocated  by  your 
application.  The  function  returns  the  time  table  for  the  media  in  this  block. 

startTime 

The  first  point  of  the  media  to  be  included  in  the  time  table.  This  time  value  is 
expressed  in  the  media's  time  coordinate  system. 
endT i me 

The  last  point  of  the  media  to  be  included  in  the  time  table.  This  time  value  is 
expressed  in  the  media's  time  coordinate  system. 
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timelncrement 

The  resolution  of  the  time  table.  The  values  in  a  time  table  are  for  a  points  in  the 
media,  and  these  points  are  separated  by  the  amount  of  time  specified  by  this 
parameter.  The  time  value  is  expressed  in  the  media's  time  coordinate  system, 
fi rstDataRef Index 

An  index  to  the  first  data  reference  for  the  media  to  be  included  in  the  time 
table.  Set  this  parameter  to  -1  to  include  all  data  references  for  the  media.  Set 
this  parameter  to  1  to  specify  the  first  data  reference  for  the  media. 

1 astDataRef Index 

An  index  to  the  last  data  reference  for  the  media  to  be  included  in  the  time  table. 
The  value  1  specifies  the  first  data  reference  for  the  media.  If  the  value  of  the 
fi  rstDataRef  Index  parameter  is  -1,  set  this  parameter  to  0. 
retdataRefSkew 

The  offset  to  the  next  row  of  the  time  table,  in  long  integers.  The  next  row 
contains  values  for  the  next  data  reference,  as  explained  below.  By  adding  the 
value  of  this  parameter  to  an  offset  into  the  table,  you  get  the  offset  to  the 
corresponding  point  for  the  next  data  reference. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

Your  application  must  allocate  an  unlocked  relocatable  memory  block  for  the  time 
table  to  be  returned  and  pass  a  handle  to  it  in  the  offsets  parameter.  The 
Ma  keMed  i  a  T  i  meT  able  (11-788)  function  resizes  the  block  to  accommodate  the  time 
table  it  returns. 

This  time  table  is  a  two-dimensional  array  of  long  integers,  organized  so  that  each 
row  in  the  table  contains  values  for  one  data  reference.  The  first  column  in  the  table 
contains  values  for  the  time  in  the  media  specified  by  the  sta  rtT i  me  parameter,  and 
each  subsequent  column  contains  values  for  the  point  in  the  media  that  is  later  by 
the  value  specified  by  the  ti  me  Increment  parameter.  Each  long  integer  value  in  the 
table  specifies  the  offset,  in  bytes,  from  the  beginning  of  the  data  reference  for  that 
point  in  the  media.  The  number  of  columns  in  the  table  is  equal  to  ( endTi  me  - 
startTime)  /  timelncrement,  rounded  up.  Because  of  alignment  issues,  this  value  is 
not  always  the  same  as  the  value  of  the  retdataRefSkew  parameter. 

Special  Considerations 

When  all  the  data  for  a  movie  has  been  transferred,  your  application  must  dispose 
of  the  time  table  created  by  this  function. 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Low-Level  Download  Control"  (V-2772) 


MakeThumbnailFromPicture 


Creates  a  thumbnail  picture  from  a  specified  Pi  cture  (IV-2331)  structure. 

OSErr  MakeThumbnailFromPicture  ( 

PicHandle  picture, 

short  colorDepth, 

Pi cHandl e  thumbnai 1 , 

ICMProgressProcRecordPtr  progressProc  ); 

pi cture 

A  handle  to  the  image  from  which  the  thumbnail  is  to  be  extracted.  The  image 
must  be  stored  in  a  Pi  cture  (IV-2331)  structure, 
col orDepth 

The  depth  at  which  the  image  is  likely  to  be  viewed.  If  you  set  this  parameter 
to  0,  the  Image  Compression  Manager  determines  the  appropriate  value  for  the 
source  image.  Values  of  1, 2, 4,  8, 16, 24,  and  32  indicate  the  number  of  bits  per 
pixel  for  color  images.  Values  of  34,  36,  and  40  indicate  2-bit,  4-bit,  and  8-bit 
grayscale,  respectively,  for  grayscale  images. 

thumbnai 1 

A  handle  to  the  destination  Pi  cture  (IV-2331)  structure  for  the  thumbnail 
image.  The  compressor  resizes  this  handle  for  the  resulting  data. 

progressProc 

A  pointer  to  an  ICMProgressProcRecord  (IV-2284)  structure.  During  the 
operation,  the  Image  Compression  Manager  will  occasionally  call  a  function  to 
report  its  progress.  You  can  provide  a  function  through  this  structure.  If  you 
have  not  provided  a  progress  function,  set  this  parameter  to  NIL.  If  you  pass  a 
value  of  -1,  you  obtain  a  standard  progress  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Making  Thumbnail  Pictures"  (V-2791) 

Related  Java  Methods 

qui cktime . qd . Pi ct .makeThumbnai 1 ( ) 


MakeThumbnailFromPictureFile 


Creates  a  thumbnail  picture  from  a  specified  picture  file. 

OSErr  MakeThumbnailFromPictureFile  ( 
short  refNum, 

short  colorDepth, 

PicHandle  thumbnail, 

ICMProgressProcRecordPtr  progressProc  ); 

refNum 

A  file  reference  number  for  the  PICT  file  from  which  the  thumbnail  is  to  be 
extracted, 
col orDepth 

The  depth  at  which  the  image  is  likely  to  be  viewed.  If  you  set  this  parameter 
to  0,  the  Image  Compression  Manager  determines  the  appropriate  value  for  the 
source  image.  Values  of  1,  2, 4, 8, 16, 24,  and  32  indicate  the  number  of  bits  per 
pixel  for  color  images.  Values  of  34,  36,  and  40  indicate  2-bit,  4-bit,  and  8-bit 
grayscale,  respectively,  for  grayscale  images. 

thumbnai 1 

A  handle  to  the  destination  picture  structure  for  the  thumbnail  image.  The 
compressor  resizes  this  handle  for  the  resulting  data. 

progressProc 

A  pointer  to  an  ICMProgressProcRecord  (IV-2284)  structure.  During  the 
operation,  the  Image  Compression  Manager  will  occasionally  call  a  function  to 
report  its  progress.  You  can  provide  a  function  through  this  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Making  Thumbnail  Pictures"  (V-2791) 
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MakeThumbnailFromPixMap 


Creates  a  thumbnail  picture  from  a  specified  Pi  xMap  (IV-2332)  structure. 

OSErr  MakeThumbnailFromPixMap  ( 

PixMapHandle  src, 

const  Rect  *srcRect, 

short  colorDepth, 

Pi cHandl e  thumbnai 1  , 

ICMProgressProcRecordPtr  progressProc  ); 


src 

A  handle  to  the  image  from  which  the  thumbnail  is  to  be  extracted.  The  image 
must  be  stored  in  a  PixMap  (IV-2332)  structure. 

srcRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  defines  the  portion  of  the  image  to 
use  for  the  thumbnail, 
col orDepth 

The  depth  at  which  the  image  is  likely  to  be  viewed.  If  you  set  this  parameter 
to  0,  the  Image  Compression  Manager  determines  the  appropriate  value  for  the 
source  image.  Values  of  1, 2, 4,  8, 16, 24,  and  32  indicate  the  number  of  bits  per 
pixel  for  color  images.  Values  of  34,  36,  and  40  indicate  2-bit,  4-bit,  and  8-bit 
grayscale,  respectively,  for  grayscale  images, 
thumbnai 1 

A  handle  to  the  destination  picture  structure  for  the  thumbnail  image.  The 
compressor  resizes  this  handle  for  the  resulting  data. 

progressProc 

A  pointer  to  an  ICMProgressProcRecord  (IV-2284)  structure.  During  the 
operation,  the  Image  Compression  Manager  will  occasionally  call  a  function  to 
report  its  progress.  You  can  provide  a  function  through  this  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Making  Thumbnail  Pictures"  (V-2791) 

Related  Java  Methods 

qui ckti me . qd . Pi ct . thumbnai 1 FromQDGraphicst ) , 
quicktime.qd.QDGraphics.makeThumbnail ( ) 
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MakeT  rackTimeT  able 


Returns  a  time  table  for  a  specified  track  in  a  movie. 


OSErr  MakeTrackTimeTable  ( 


T  rack 
1  ong 

T i meVal ue 
T i meVal ue 
T i meVal ue 
short 
short 
1  ong 


trackH , 

**of f sets , 
startTime, 
endTime, 
timelncrement, 
fi rstDataRef Index, 
1 astDataRef Index, 
*retdataRefSkew  ); 


trackH 

The  track  for  the  operation.  Your  application  gets  this  identifier  from  such 
functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

offsets 

A  handle  to  an  unlocked  relocatable  memory  block  allocated  by  your 
application.  The  function  returns  the  time  table  for  the  track  in  this  block. 
startTime 

The  first  point  of  the  track  to  be  included  in  the  time  table.  This  time  value  is 
expressed  in  the  movie's  time  coordinate  system. 
endTime 

The  last  point  of  the  track  to  be  included  in  the  time  table.  This  time  value  is 
expressed  in  the  movie's  time  coordinate  system. 

timelncrement 

The  resolution  of  the  time  table.  The  values  in  a  time  table  are  for  a  points  in  the 
track,  and  these  points  are  separated  by  the  amount  of  time  specified  by  this 
parameter.  The  time  value  is  expressed  in  the  movie's  time  coordinate  system, 
f i rstDataRef Index 

An  index  to  the  first  data  reference  for  the  track  to  be  included  in  the  time  table. 
Set  this  parameter  to  -1  to  include  all  data  references  for  the  track.  Set  this 
parameter  to  1  to  specify  the  first  data  reference  for  the  track. 

1 astDataRef Index 

An  index  to  the  last  data  reference  for  the  track  to  be  included  in  the  time  table. 
The  value  1  specifies  the  first  data  reference  for  the  track.  If  the  value  of  the 
fi  rstDataRef  Index  parameter  is  -1,  set  this  parameter  to  0. 
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retdataRefSkew 

The  offset  to  the  next  row  of  the  time  table,  as  a  long  integer.  The  next  row 
contains  values  for  the  next  data  reference,  as  explained  below.  By  adding  the 
value  of  this  parameter  to  an  offset  into  the  table,  you  get  the  offset  to  the 
corresponding  point  for  the  next  data  reference. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

Your  application  must  allocate  an  unlocked  relocatable  memory  block  for  the  time 
table  to  be  returned  and  pass  a  handle  to  it  in  the  offsets  parameter.  The 
MakeT rackTi  meTabl  e  (11-793)  function  resizes  the  block  to  accommodate  the  time 
table  it  returns. 

This  time  table  is  a  two-dimensional  array  of  long  integers  that  is  organized  so  that 
each  row  in  the  table  contains  values  for  one  data  reference.  The  first  column  in  the 
table  contains  values  for  the  time  in  the  track  specified  by  the  startTime  parameter, 
and  each  subsequent  column  contains  values  for  the  point  in  the  track  that  is  later 
by  the  value  specified  by  the  timelncrement  parameter.  Each  long  integer  value  in 
the  table  specifies  the  offset,  in  bytes,  from  the  beginning  of  the  data  reference  for 
that  point  in  the  track.  The  number  of  columns  in  the  table  is  equal  to  ( endTi  me  - 
sta  rtT ime )  /  ti  me  Increment,  rounded  up.  Because  of  alignment  issues,  this  value  is 
not  always  the  same  as  the  value  of  the  retdataRefSkew  parameter.  If  there  are  track 
edits  for  a  track,  they  are  reflected  in  the  track's  time  table. 

Special  Considerations 

When  all  the  data  for  a  movie  has  been  transferred,  your  application  must  dispose 
of  the  time  table  created  by  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Low-Level  Download  Control"  (V-2772) 


MapMatrix 

Alters  an  existing  matrix  so  that  it  defines  a  transformation  from  one  rectangle  to 
another. 


11-794 


Inside  QuickTime:  Function  l-Q 


MCActivate 


void  MapMatrix  ( 

MatrixRecord  *matrix, 

const  Rect  *fromRect, 

const  Rect  *toRect  ); 

matri x 

A  pointer  to  a  matrix  structure.  The  MapMatri  x  function  modifies  this  matrix  so 
that  it  performs  a  transformation  in  the  rectangle  specified  by  the  to  Rect 
parameter  that  is  analogous  to  the  transformation  it  currently  performs  in  the 
rectangle  specified  by  the  f  romRect  parameter. 

f romRect 

A  pointer  to  the  source  Rect  (IV-2399)  structure. 
toRect 

A  pointer  to  the  destination  Rect  (IV-2399)  structure. 

Discussion 

MapMatrix  affects  only  the  scaling  and  translation  attributes  of  the  matrix. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Matrices"  (V-2764) 

Related  Java  Methods 

qui ckti me . std . image . Matri x. map ( ) 


See  Also 

This  function  is  similar  to  RectMatri  x  (III— 1451),  with  the  exception  that  it 
concatenates  the  translation  and  scaling  operations  to  the  previous  contents  of  the 
matrix,  whereas  RectMatri  x  first  sets  the  matrix  to  the  identity  state. 


MCActivate 


Lets  a  controller  respond  to  activate,  deactivate,  suspend,  and  resume  events. 

ComponentResul t  MCActivate  ( 

Movi eControl 1 er  me, 

WindowPtr  w. 

Boolean  activate  ); 


Inside  QuickTime:  Function  l-Q 


11-795 


MCAdjustCursor 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi eControl  1  er  (11-1071). 
w 

A  pointer  to  the  window  in  which  the  event  has  occurred, 
acti vate 

The  nature  of  the  event.  Set  this  parameter  to  TRUE  for  activate  and  resume 
events.  Set  it  to  FALSE  for  deactivate  and  suspend  events. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Customizing  Event  Processing"  (V-2779) 

Related  Java  Methods 

qu ickti me. std. mo vies. Mo vieController. activate!) 


MCAdjustCursor 


Undocumented 

ComponentResul t  MCAdjustCursor  ( 
Movi eControll er  me, 

WindowPtr  w. 

Point  where, 

1  ong  modi  tiers  ) ; 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 

w 

A  pointer  to  the  window  in  which  the  cursor  is  located. 


11-796 


Inside  QuickTime:  Function  l-Q 


MCAddMovieSegment 


where 

The  location  of  the  cursor.  This  value  is  expressed  in  the  local  coordinates  of  the 
window  specified  by  the  w  parameter, 
modi f i ers 

The  cursor  form  (see  below). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

modifiers  Constants 

kQTCursorOpenHand 

Open  hand  cursor. 
kQTCursorCl os ed Hand 

Closed  hand  cursor. 
kQTCursorPoi ntingHand 
Pointing  hand  cursor. 
kQTCursorRi ghtArrow 
Right  arrow  cursor. 
kQTCursorLeftArrow 
Left  arrow  cursor. 
kQTCursorDownArrow 

Down  arrow  cursor. 
kQTCursorllpArrow 
Up  arrow  cursor. 
kQTCursorlBeam 
I-beam  cursor. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


MCAddMovieSegment 


Undocumented 

ComponentResul t  MCAddMovieSegment  ( 
Movi eControl 1 er  me. 


Inside  QuickTime:  Function  l-Q 


11-797 


MCClear 


Movie  srcMovie, 

Bool ean  seal ed  ) ; 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi eControl  1  er  (11-1071). 
srcMovi e 

The  source  movie.  Your  application  obtains  this  movie  identifier  from  such 
functions  as  NewMovie  (11-1069),  NewMovieFromFi  1  e  (11-1080),  or 
NewMovi  eFromHandl  e  (11-1084). 
seal ed 

Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Movi  es .  h 


MCClear 


Removes  the  current  movie  selection  from  the  movie  associated  with  a  specified 
controller. 

ComponentResul t  MCClear  ( 

Movi eControl 1 er  me  ) ; 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


11-798 


Inside  QuickTime:  Function  l-Q 


MCClick 


Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Editing  Movies  With  a  Controller"  (V-2777) 

Related  Java  Methods 

qui cktime . std .movi es . Movi eControl 1 er . cl ear( ) 


MCClick 


Lets  a  controller  respond  when  the  user  clicks  in  a  movie  controller  window. 


ComponentResul t  MCClick  ( 

Movi eControl 1 er  me, 

WindowPtr  w. 

Point  where, 

long  when, 

long  modifiers  ); 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 

w 

A  pointer  to  the  window  in  which  the  event  has  occurred, 
where 

The  location  of  the  click.  This  value  is  expressed  in  the  local  coordinates  of  the 
window  specified  by  the  w  parameter.  Your  application  must  convert  this  value 
from  the  global  coordinates  returned  in  the  EventRecord  (IV-2246)  structure. 

when 

Indicates  when  the  user  pressed  the  mouse  button.  You  obtain  this  value  from 
the  EventRecord  (IV-2246)  structure. 

modi f i ers 

Specifies  modifier  flags  for  the  event.  You  obtain  this  value  from  the 
EventRecord  (IV-2246)  structure. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Function  l-Q 


11-799 


MCCopy 


Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Customizing  Event  Processing"  (V-2779) 

Related  Java  Methods 

qui ckti me. std .movi es .Movi eControl 1 er . cl i ck( ) 


MCCopy 


Returns  a  copy  of  the  current  movie  selection  from  the  movie  associated  with  a 
specified  controller. 

Movie  MCCopy  ( 

Movi eControl 1 er  me  ) ; 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi eControl  1  er  (11-1071). 

function  result  A  copy  of  the  movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Editing  Movies  With  a  Controller"  (V-2777) 

Related  Java  Methods 

quicktime.std.movies.MovieController.copyt) 


MCCut 


Returns  a  copy  of  the  current  movie  selection  from  the  movie  associated  with  a 
specified  controller  and  then  removes  the  current  movie  selection  from  the  source 
movie. 

Movie  MCCut  ( 

Movi eControl 1 er  me  ) ; 


11-800 


Inside  QuickTime:  Function  l-Q 


MCDoAction 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 

function  result  A  copy  of  the  current  movie  selection. 

Discussion 

Your  application  is  responsible  for  the  returned  movie.  MCCut  returns  a  movie 
containing  the  current  selection  from  the  movie  associated  with  the  specified 
controller.  If  the  user  has  not  made  a  selection,  the  returned  movie  reference  is  set 
to  NIL. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Editing  Movies  With  a  Controller"  (V-2777) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi eControl 1 er . cut ( ) 


MCDoAction 


Invokes  a  movie  controller  component  and  makes  it  perform  a  specified  action. 

ComponentResul t  MCDoAction  ( 

Movi eControl 1 er  me, 

short  action, 

void  *params  ); 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl!  er  (11-1071). 

acti on 

The  action  to  be  taken.  See  "Movie  Controller  Actions"  (V-2773). 
params 

A  pointer  to  the  parameter  data  appropriate  to  the  action.  See  "Movie 
Controller  Actions"  (V-2773)  for  information  about  the  parameters  required  for 
each  supported  action. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 


Inside  QuickTime:  Function  l-Q 


11-801 


MCDoAction 


(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Movie  Controller  Actions"  (V-2773) 

Related  Java  Methods 

qui ckti me. std. mo vies. Mo vieController. activate! ) , 

qui ckti me. std. mo vies. Mo vieController. deactivate!), 

qui ckti me. std. mo vies. Mo vieController. play!), 

qui ckti me . std .movi es . Movi eControl 1 er . goToTimet ) , 

quickti me. std. mo vies. Mo vieController.setVol ume( ) , 

quicktime.std.movies.MovieController.getVol ume( ) , 

quicktime.std.movies.MovieController.stept), 

quicktime.std.movies.MovieController.setLoopingO, 

quicktime.std.movies.MovieController.getLoopingt), 

quicktime.std.movies.MovieController.setLoopIsPali ndromet ) , 

quicktime.std.movies.MovieController.getLoopIsPali ndromet ) , 

quicktime.std.movies.MovieController.setGrowBoxBoundst), 

quicktime.std.movies.MovieController.setSelectionBegint ) , 

quicktime.std.movies.MovieController.setSelectionDurationt ) , 

quicktime.std.movies.MovieControll er . setKeysEnabl ed( ) , 

quicktime.std.movies.MovieController. getKeysEnabl ed( ) , 

quicktime.std.movies.MovieController.setPlaySelectiont), 

qui ckti me. std .movi es .Movi eControl 1 er . get PI  ay Sel ecti on( ) , 

quicktime.std.movies.MovieController.setUseBadget), 

quicktime.std.movies.MovieController.getUseBadget ) , 

quicktime.std.movies.MovieController.setFlagst), 

quicktime.std.movies.MovieController.getFlagst ) , 

qu i c kti me. std. mo vies. Mo vieController.setPl ay  Every  Frame ( ) , 

qu i c kti me. std. mo vies. Mo vieController.getPl ay  Every  Frame ( ) , 

quicktime.std.movies.MovieController.getPlayRatet), 

qui ckti me. std. mo vies. Mo vieController. suspend! ) , 

quicktime.std.movies.MovieController. resumet ) , 

quicktime.std.movies.MovieController.setControll erKeysEnabl ed( ) , 

quicktime.std.movies.MovieController.getTimeSliderRectt ) , 

quicktime.std.movies.MovieController.getDragEnabledt), 

quicktime.std.movies.MovieController.setDragEnabledt), 

quicktime.std.movies.MovieController.getSelectionBegint ) , 


11-802 


Inside  QuickTime:  Function  l-Q 


MCDraw 


qui cktime . std .movi es . Movi eControl 1 er . getSel ecti onDurati on( ) , 

qui cktime . std .movi es . Movi eControl 1 er . prerol 1  And  PI  ay ( ) , 

qui  cktime . std .movi es . Movi eControl 1 er . getCursorSetti ngEnabl ed( ) , 

qui  cktime . std .movi es . Movi eControl 1 er . setCursorSetti ngEnabl ed( ) , 

qui  cktime . std .movi es . Movi eControl 1 er . setCol orTabl e( ) , 

quicktime.std.movies.MovieController.controllerSizeChangedi), 

qui  cktime . std .movi es . Movi eControl 1 er . badgeCl i ck( ) , 

qui  cktime . std .movi es . Movi eControl 1 er .movi eEdi ted( ) , 

qui  cktime .  std  .movi  es  .  Movi  eControl  1  er .  f  orceTi meTabl  ellpdate( ) , 

qui  cktime . std .movi  es . Movi eControl 1 er . 1 i nkToURLC ) , 

qui  cktime . std .movi es . Movi eControl 1 er . cl i ckAndHol dPoi nt( ) 


MCDraw 


Responds  to  an  update  event. 

ComponentResul t  MCDraw  ( 
Movi eControl 1 er  me, 

WindowPtr  w  ); 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 

w 

A  pointer  to  the  window  in  which  the  update  event  has  occurred. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Customizing  Event  Processing"  (V-2779) 

Related  Java  Methods 

qui cktime . std .movi es . Movi eControl 1 er . draw( ) 


Inside  QuickTime:  Function  l-Q 


11-803 


MCDrawBadge 


MCDrawBadge 


Displays  a  controller's  badge. 

ComponentResul t  MCDrawBadge  ( 

Movi eControl 1 er  me, 

RgnHandle  movieRgn, 

RgnHandle  *badgeRgn  ); 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi eControl  1  er  (11-1071). 
movi eRgn 

The  boundary  region  of  the  controller's  movie. 
badgeRgn 

A  pointer  to  a  region  that  is  to  receive  information  about  the  location  of  the 
badge.  The  movie  controller  returns  the  region  where  the  badge  is  displayed.  If 
you  are  not  interested  in  this  information,  you  may  set  this  parameter  to  NIL. 
Your  application  must  dispose  of  this  handle. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

This  function  places  the  badge  in  an  appropriate  location  based  on  the  location  of 
the  controller's  movie.  MCDrawBadge  can  be  useful  in  circumstances  where  you  are 
using  a  movie  controller  component  but  do  not  want  to  incur  the  overhead  of 
having  the  QuickTime  movie  in  memory  all  the  time.  This  function  allows  you  to 
display  the  badge  without  having  to  display  the  movie.  In  addition,  you  can  use  the 
badge  region  to  perform  mouse-down  event  testing. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi es .  h 

Programming  summary:  "Managing  Controller  Attributes"  (V-2775) 

Related  Java  Methods 

qui ckti me . qd . Regi on . f romMovi eControl lerBadget), 
quicktime.std.movies.MovieController.drawBadgeO 


11-804 


Inside  QuickTime:  Function  l-Q 


MCEnableEditing 


MCEnableEditing 


Enables  and  disables  editing  for  a  movie  controller. 

ComponentResul t  MCEnableEditing  ( 

Movi eControl 1 er  me. 

Boolean  enabled  ); 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 

enabl ed 

Specifies  whether  to  enable  or  disable  editing  for  the  controller.  Set  this 
parameter  to  TRUE  to  enable  editing;  set  it  to  FALSE  to  disable  editing. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

Once  editing  is  enabled  for  a  controller,  the  user  may  edit  the  movie  associated  with 
the  controller. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Editing  Movies  With  a  Controller"  (V-2777) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi eControl 1 er . enabl eEdi ti ng( ) 


MCGetClip 


Obtains  information  describing  a  movie  controller's  clipping  regions. 

ComponentResul t  MCGetClip  ( 

Movi eControl 1 er  me, 

RgnHandle  *theClip, 

RgnHandle  *movieClip  ); 


Inside  QuickTime:  Function  l-Q 


11-805 


MCGetControllerBoundsRect 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi eControl  1  er  (11-1071). 
theCl 1 p 

A  pointer  to  a  field  that  is  to  receive  a  handle  to  the  clipping  region  of  the  entire 
movie  controller.  You  must  dispose  of  this  region  when  you  are  done  with  it.  If 
you  are  not  interested  in  this  information,  set  this  parameter  to  NIL. 

movi eCl i p 

A  pointer  to  a  field  that  is  to  receive  a  handle  to  the  clipping  region  of  the 
controller's  movie.  You  must  dispose  of  this  region  when  you  are  done  with  it. 
If  you  are  not  interested  in  this  information,  set  this  parameter  to  NIL. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Managing  Controller  Attributes"  (V-2775) 

Related  Java  Methods 

qui ckti me . qd . Regi on  .  f  romMovi  eControllerClipO, 
quicktime.std.movies.MovieController.getClipO 


See  Also 

For  the  corresponding  set  function,  see  MCSetCl  i  p  (11-830). 


MCGetControllerBoundsRect 


Returns  a  movie  controller's  boundary  rectangle. 

ComponentResul t  MCGetControllerBoundsRect  ( 
Movi eControl 1 er  me, 

Rect  *bounds  ) ; 


The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 


11-806 


Inside  QuickTime:  Function  l-Q 


MCGetControllerBoundsRgn 


bounds 

A  pointer  to  a  Rect  (IV-2399)  structure  that  is  to  receive  the  coordinates  of  the 
movie  controller's  boundary  rectangle.  If  there  is  insufficient  screen  space  to 
display  the  controller,  the  function  may  return  an  empty  structure. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Managing  Controller  Attributes"  (V-2775) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi eControl 1 er . get Bounds ( ) 


See  Also 

For  the  corresponding  set  function,  see  MCSetControl  1  erBoundsRect  (11-832). 


MCGetControllerBoundsRgn 


Returns  the  actual  region  occupied  by  the  controller  and  its  movie. 

RgnHandle  MCGetControllerBoundsRgn  ( 

Movi eControl 1 er  me  ); 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 

function  result  A  handle  to  a  MacRegi  on  (IV-2303)  structure  that  reflects  the  size, 

shape,  and  location  of  the  controller.  Your  application  must  dispose 
of  this  structure. 

Discussion 

As  with  MCGetControl  1  erBoundsRect  (11-806),  this  function  returns  a  region  even  if 
the  controller  is  hidden.  Some  movie  controllers  may  not  be  rectangular  in  shape.  If 
the  movie  is  not  attached  to  its  controller,  the  boundary  region  encloses  only  the 
control  portion  of  the  controller. 


Inside  QuickTime:  Function  l-Q 
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MCGetControllerlnfo 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi es .  h 

Programming  summary:  "Managing  Controller  Attributes"  (V-2775) 

Related  Java  Methods 

qui  ckti  me .  qd  .  Regi  on  . f romMovi  eControllerBoundsO  , 
quicktime.std.movies.MovieController.getBoundsRgnO 


See  Also 

The  rectangle  returned  by  MCGetControl  1  erBoundsRect  (11-806)  bounds  the  region 
returned  by  this  function. 


MCGetControllerlnfo 


Determines  the  current  status  of  a  movie  controller  and  its  associated  movie,  for 
menu  highlighting. 

ComponentResul t  MCGetControllerlnfo  ( 

Movi eControl 1 er  me, 

1 ong  *someFl ags  ) ; 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi eControl  1  er  (11-1071). 
someFl ags 

A  pointer  to  flags  (see  below)  that  specify  the  current  status  and  capabilities  of 
the  controller.  More  than  one  flag  may  be  set  to  1. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

someFlags  Constants 

mclnfoUndoAvai 1 abl e 

The  user  has  edited  the  movie.  If  this  flag  is  set  to  1,  you  can  call  MCUndo  (11-838). 
mclnfoCutAvai 1 abl e 

The  user  has  selected  some  material  in  the  movie  and  editing  is  enabled.  If  this 
flag  is  set  to  1,  you  can  call  MCCut  (11-800). 
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MCGetControllerlnfo 


mclnfoCopyAvai 1 abl e 

The  user  has  selected  some  material  in  the  movie.  If  this  flag  is  set  to  1,  you  can 
call  MCCopy  (11-800). 
mclnfoPasteAvai 1 abl e 

There  is  movie  data  in  the  scrap  and  editing  is  enabled.  If  this  flag  is  set  to  1, 
you  can  call  MCPaste  (11-824).  If  your  application  maintains  a  private  scrap,  this 
flag  does  not  reflect  the  state  of  that  scrap. 

mclnfoCI earAvai 1 abl e 

The  user  has  selected  some  material  in  the  movie  and  editing  is  enabled.  If  this 
flag  is  set  to  1,  you  can  call  MCC1  ear  (11-798). 
mclnfoHasSound 

The  movie  has  sound.  If  this  flag  is  set  to  1,  the  controller  can  play  a  movie's 
sound. 

mclnfoIsPI ayi ng 

If  this  flag  is  set  to  1,  the  movie  is  playing. 
mclnfoIsLoopi ng 

The  controller  is  currently  set  to  play  its  movie  repeatedly.  If  this  flag  is  set  to 
1,  the  movie  is  looping. 
mclnfoIsInPal i ndrome 

The  controller  is  currently  set  to  play  its  movie  repeatedly,  alternating  between 
forward  and  backward  playback.  If  this  flag  is  set  to  1,  the  movie  is  in 
palindrome  looping  mode. 
mclnfoEdi ti ngEnabl  ed 

The  user  can  edit  the  movie  associated  with  this  controller.  If  this  flag  is  set  to 
1,  you  have  enabled  editing  by  calling  MCEnabi eEdi  ti  ng  (11-805). 

Discussion 

You  can  use  the  information  returned  by  this  function  to  control  your  application's 
menu  highlighting. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Handling  Movie  Events"  (V-2776) 

Related  Java  Methods 

qui cktime . std .movi es . Movi eControl 1 er . getControl 1 erlnf o( ) 


Inside  QuickTime:  Function  l-Q 
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MCGetControllerPort 


MCGetControllerPort 

Returns  a  movie  controller's  color  graphics  port. 

CGrafPtr  MCGetControllerPort  ( 

Movi eControl 1 er  me  ) ; 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi eControl  1  er  (11-1071). 

function  result  A  pointer  to  the  movie  controller's  CGraf  Port  (IV-2168)  structure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Managing  Controller  Attributes"  (V-2775) 

Related  Java  Methods 

quicktime.std.movies.MovieController.getPortO, 
qui ckti me . qd . QDGraphi cs . f romMovi eControllert ) 

See  Also 

For  the  corresponding  set  function,  see  MCSetControl  1  erPort  (11-833). 


MCGetCurrentTime 


Obtains  the  time  value  represented  by  the  indicator  on  the  movie  controller's  slider. 

TimeValue  MCGetCurrentTime  ( 

Movi eControll er  me, 

TimeScale  *scale  ) ; 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 

seal  e 

A  pointer  to  a  field  that  is  to  receive  the  time  scale  for  the  controller. 
function  result  A  time  value  containing  the  time  shown  by  the  indicator  on  the 
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movie  controller's  slider. 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Getting  and  Setting  Movie  Controller  Time"  (V-2778) 

Related  Java  Methods 

qui cktime . std .movi es . Movi eControl 1 er . getCurrentT ime( ) , 
qui cktime . std .movi es . Movi eControl 1 er . getTi meScal e( ) 


MCGetDoActionsProc 


Retrieves  the  DoMCActi  onProc  (III— 2082)  callback  attached  to  a  movie  controller. 

ComponentResul t  MCGetDoActionsProc  ( 

Movi eControl 1 er  me, 

DoMCActi on  U  P  P  *doMCActi onProc , 

long  *doMCActi onRefCon  ); 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 

doMCActi onProc 

A  pointer  to  a  DoMCActi  onProc  (III— 2082)  callback. 
doMCActi onRefCon 

A  reference  constant  that  is  passed  to  your  callback.  This  parameter  may  point 
to  a  data  structure  containing  information  your  function  needs. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


Inside  QuickTime:  Function  l-Q 
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MCGetlndMovie 


Lets  your  application  to  retrieve  the  movie  reference  for  a  movie  that  is  associated 
with  a  movie  controller. 

Movie  MCGetlndMovie  ( 

Movi eControl 1 er  me, 

short  i ndex  ) ; 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi eControl  1  er  (11-1071). 

i  ndex 

Index  for  the  movie.  When  set  to  0,  this  call  duplicates  the  action  of  the  previous 
call  to  this  function. 

function  result  The  movie  identifier  for  the  movie  that  is  assigned  to  the  specified 
controller,  or  N I L  if  there  is  no  movie  assigned  to  the  controller. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Associating  Movies  With  Controllers"  (V-2774) 

Related  Java  Methods 

quicktime.std.movies.MovieController.getMovieO, 

quicktime.std.movies.MultiMovieController.getlndMoviet) 


MCGetlnterfaceElement 


Gets  the  interface  element  of  a  specified  type  for  a  movie  controller. 

ComponentResul t  MCGetlnterfaceElement  ( 

Movi eControl 1 er  me, 

MCInterfaceEl ement  whi c  h  E 1 ement , 

voi d  *el ement  ) ; 
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MCGetlnterfaceElement 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 
whi chEl ement 

A  constant  (see  below)  that  identifies  the  interface  element  type, 
el ement 

A  pointer  to  the  element  type. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

whichElement  Constants 

kMCIEEnabl ed Butt on  Pi cture 

A  Picture  (IV-2331)  of  an  enabled  button. 
kMCIEDi sabl edButtonPi cture 

A  Picture  (IV-2331)  of  a  disabled  button. 
kMC I EDep res s edButtonPi cture 

A  Pi  cture  (IV-2331)  of  a  depressed  button. 
kMCIEEnabl edSi zeBoxPi cture 

A  Picture  (IV-2331)  of  an  enabled  size  box. 
kMCIEDi sabl ed Si zeBoxPi  cture 

A  Pi  cture  (IV-2331)  of  a  disabled  size  box. 
kMCIEEnabl edUnavai 1 abl eButtonPi cture 

A  Picture  (IV-2331)  of  an  enabled  but  unavailable  button. 
kMCIEDi sabl ed Unavail abl eButtonPi  cture 

A  Picture  (IV-2331)  of  a  disabled  and  unavailable  button. 
kMCIESoundSl ider 

The  sound  slider. 
kMCIESoundThumb 

The  indicator  on  the  sound  slider. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 
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MCGetMenuString 


Retrieves  the  text  string  for  a  movie  controller  menu  command. 

ComponentResul t  MCGetMenuString  ( 

Movi eControl 1 er  me, 
long  modifiers, 

short  item, 

Str255  aStri ng  ) ; 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi eControl  1  er  (11-1071). 
modi f i ers 

The  current  modifiers  from  the  mouse-down  or  key-down  event  to  which  you 
are  responding. 

i  tern 

One  of  the  movie  controller  Edit  menu  constants  (see  below). 
aStri ng 

On  entry,  pass  a  string  of  type  Str255;  on  exit,  this  string  is  set  to  the  text  of  the 
menu  item  specified  by  the  i  tern  parameter. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

item  Constants 

mcMenuUndo 

Return  the  menu  item  text  for  the  Undo  command. 
mcMenuCut 

Return  the  menu  item  text  for  the  Cut  command. 
mcMenuCopy 

Return  the  menu  item  text  for  the  Copy  command. 
mcMenuPaste 

Return  the  menu  item  text  for  the  Paste  command. 
mcMenuCl ear 

Return  the  menu  item  text  for  the  Clear  command. 

Discussion 

MCGetMenuStri  ng  is  used  by  MCSetUpEdi  tMenu  (11-836). 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Editing  Movies  With  a  Controller"  (V-2777) 

See  Also 

See  MCSetUpEdi  tMenu  (11-836). 


MCGetVisible 


Returns  a  value  that  indicates  whether  or  not  a  movie  controller  is  visible. 

ComponentResul t  MCGetVisible  ( 

Movi eControl 1 er  me  ); 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 

function  result  If  the  controller  is  visible,  the  function  result  is  set  to  1.  If  the 

controller  is  not  showing,  the  function  result  is  set  to  0.  You  can 
access  Movie  Toolbox  error  returns  through  GetMovi esError  (1-492) 
and  GetMovi  esSti  ckyError  (IM94).  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Managing  Controller  Attributes"  (V-2775) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi eControl 1 er . get Vi  si bl e( ) 


See  Also 

For  the  corresponding  set  function,  see  MCSetV i  s  i  b  1  e  (11-837). 


MCGetWindowRgn 

Determines  the  window  region  that  is  actually  in  use  by  a  controller  and  its  movie. 
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MCIdle 


RgnHandle  MCGetWi ndowRgn  ( 
Movi eControl 1 er  me, 

Wi ndowPtr  w  ) ; 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovI eControl  1  er  (11-1071). 
w 

A  pointer  to  the  window  in  which  the  movie  controller  and  its  movie  are 
displayed,  if  the  control  portion  of  the  controller  is  attached  to  the  movie.  If  the 
controller  is  detached  and  in  a  separate  window  from  the  movie,  specify  one  of 
the  windows. 

function  result  A  handle  to  the  MacRegi  on  (IV-2303)  structure  for  the  window  that  is 
actually  in  use.  Your  application  must  dispose  of  this  structure. 

Discussion 

The  region  returned  by  this  function  contains  only  the  visible  portions  of  the 
controller  and  its  movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es . h 

Programming  summary:  "Managing  Controller  Attributes"  (V-2775) 

Related  Java  Methods 

qui ckti me . qd . Regi on . f romMovi eControllerWindowt ) , 
quicktime.std.movies.MovieController.getWindowRgnO 


MCIdle 


Performs  idle  processing  for  a  movie  controller. 

ComponentResul t  MCIdle  ( 

Movi eControl 1 er  me  ) ; 


The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131),  or  from 
NewMovi eControl  1  er  (11-1071). 
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MCInvalidate 


function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Customizing  Event  Processing"  (V-2779) 

Related  Java  Methods 

qui cktime . std .movi es . Movi eControl 1 er . i dl e( ) 


MCInvalidate 


Invalidates  a  region  of  a  movie  controller's  display. 

ComponentResul t  MCInvalidate  ( 

Movi eControl 1 er  me, 

WindowPtr  w, 

RgnHandle  invalidRgn  ); 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 
w 

A  pointer  to  the  window  in  which  the  movie  controller  and  its  movie  are 
displayed,  if  the  control  portion  of  the  controller  is  attached  to  the  movie.  If  the 
controller  is  detached  and  in  a  separate  window  from  the  movie,  specify  one  of 
the  windows. 

invalidRgn 

A  handle  to  a  Mac  Reg  i  on  (IV-2303)  structure  that  defines  a  region  to  invalidate. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


Inside  QuickTime:  Function  l-Q 
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Related  Java  Methods 

qu ickti me. std. mo vies. Mo vieController. invalidate!) 


MCIsControllerAttached 

Returns  a  value  that  indicates  whether  a  movie  controller  is  attached  to  its  movie. 

ComponentResul t  MCIsControllerAttached  ( 

Movi eControl 1 er  me  ) ; 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi eControl  1  er  (11-1071). 

function  result  If  the  controller  is  attached,  the  returned  value  is  set  to  1.  If  the 
controller  is  not  attached,  the  returned  value  is  set  to  0.  You  can 
access  Movie  Toolbox  error  returns  through  GetMovi  esError  (1-492) 
and  GetMovi  esSti  ckyError  (1-494). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es . h 

Programming  summary:  "Managing  Controller  Attributes"  (V-2775) 

Related  Java  Methods 

qu i c kti me. std. mo vies. Mo vieController. is Attached!) 


See  Also 

You  can  use  MCSetControl  1  erAttached  (11-831)  to  attach  or  detach  a  movie 
controller. 


MCIsEditingEnabled 

Determines  whether  editing  is  currently  enabled  for  a  movie  controller. 

long  MCIsEditingEnabled  ( 

Movi eControl 1 er  me  ); 
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The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 


Discussion 


function  result  Returns  1  if  editing  is  enabled;  set  to  0  if  editing  is  disabled  or  if  the 
controller  component  does  not  support  editing. 

Once  editing  is  enabled  for  a  controller,  the  user  may  edit  the  movie  associated  with 
the  controller. 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Editing  Movies  With  a  Controller"  (V-2777) 

Related  Java  Methods 

qui cktime . std .movi es . Movi eControl 1 er . i s  Ed 1 ti ng Ena bl ed( ) 


MCIsPlayerEvent 


Handles  all  events  for  a  movie  controller. 

ComponentResul t  MCIsPlayerEvent  ( 

Movi eControl 1 er  me, 

const  EventRecord  *e  ); 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 
e 

A  pointer  to  the  current  EventRecord  (IV-2246)  structure. 

function  result  A  long  integer  indicating  whether  the  movie  controller  component 
handled  the  event.  The  component  sets  this  long  integer  to  1  if  it 
handled  the  event.  Your  application  should  then  skip  the  rest  of  its 
event  loop  and  wait  for  the  next  event.  The  return  value  is  0 
otherwise.  Your  application  must  then  handle  the  event  as  part  of  its 
normal  event  processing. 
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MCIsPlayerEvent 


Discussion 

The  movie  controller  component  does  everything  necessary  to  support  the  movie 
controller  and  its  associated  movie.  For  example,  the  component  calls  MoviesTask 
(11-973)  for  each  movie.  The  movie  controller  component  also  handles  suspend  and 
resume  events.  It  treats  suspend  events  as  deactivate  requests  and  resume  events  as 
activate  requests. 

The  following  sample  code  shows  how  to  convert  Windows  messages  to  Macintosh 
events  and  then  pass  those  events  to  the  QuickTime  movie  controller,  using  this 
function: 

//  MCIsPlayerEvent  coding  example 
//  See  “Discovering  QuickTime,”  page  240 


Movi eControl 1 er 

me ; 

// 

Movie  controller  for  movie 

LRESULT  CALLBACK 

WndProc 

( HWND 

hwnd , 

// 

Handle  to  window 

UINT 

i  Msg , 

// 

Message  type 

WPARAM 

wParam, 

// 

Message-dependent  parameter 

LPARAM 

1 Param) 

// 

Message-dependent  parameter 

{ 

MSG 

msg ; 

// 

Windows  message  structure 

EventRecord 

er ; 

// 

Macintosh  event  record 

DWORD 

dwPos ; 

// 

Mouse  coordinates  of  message 

msg . hwnd 

=  hwnd; 

// 

Window  handle 

msg. message 

=  i Msg ; 

// 

Message  type 

msg.wParam 

=  wParam; 

// 

Word-length  parameter 

msg.l Param 

=  1 Param; 

// 

Long-word  parameter 

msg. time  =  GetMessageTimet ) ; 

// 

Get  time  of  message 

dwPos  =  GetMessagePos ( ) ; 

// 

Get  mouse  position 

msg.pt.x  =  LOWORDt dwPos ) ; 

// 

Extract  x  coordinate 

msg.pt.y  =  HIWORD(dwPos) ; 

// 

Extract  y  coordinate 

WinEventToMacEvent(&msg,  &er); 

// 

Convert  to  event 

MCIsPl ayerEventtmc ,  &er); 

// 

Pass  event  to  QuickTime 

switch  ( i Ms g ) 

{ 

// 

Dispatch  on  message  type 

//  Handle  message  according  to  type 
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MCKey 


}  It  end  switch  ( i M s g ) 
}  //  end  WndProc 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Handling  Movie  Events"  (V-2776) 

See  Also 

You  can  provide  an  action  filter  function  that  is  called  by  the  movie  controller 
component.  The  component  calls  your  filter  function  after  it  decides  to  process  a 
particular  action,  but  before  it  actually  does  so.  In  this  manner,  your  application  can 
perform  custom  action  processing  for  a  movie  controller.  Set  your  action  filter 
function  with  MCSetActi  onFi  1  terWi  thRefCon  (11-829). 

MCKey 


Handles  keyboard  events  for  a  movie  controller. 

ComponentResul t  MCKey  ( 

Movi eControl 1 er  me, 

SInt8  key, 

long  modifiers  ); 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 
key 

The  keystroke.  You  obtain  this  value  from  the  event  structure, 
modi f i ers 

Modifier  flags  for  the  event.  You  obtain  this  value  from  the  EventRecord 
(IV-2246)  structure. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 


Inside  QuickTime:  Function  l-Q 
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MCMovieChanged 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi es .  h 

Programming  summary:  "Customizing  Event  Processing"  (V-2779) 

Related  Java  Methods 

quicktime.std.movies.MovieController. key ( ) 


MCMovieChanged 


Informs  a  movie  controller  component  that  your  application  has  used  the  Movie 
Toolbox  to  change  the  characteristics  of  its  associated  movie. 

ComponentResul t  MCMovieChanged  ( 

Movi eControll er  me, 

Movi e  m  ) ; 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi eControl  1  er  (11-1071). 

m 

The  movie  that  has  been  changed. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Movie  Controller  Actions"  (V-2773) 

Related  Java  Methods 

quicktime.std.movies.MovieController.movieChangedt ) , 
quicktime.std.movies.MultiMovieController.movieChangedO 
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MCNe  wAttachedController 


MCNewAttachedController 


Associates  a  specified  movie  with  a  movie  controller. 


Component  Res  ill t  MCNewAtt ached Control  1 er 
Movi eControl 1 er  me. 

Movie  theMovie, 

WindowPtr  w. 

Point  where  ); 


( 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 
theMovi e 

The  movie  to  be  associated  with  the  movie  controller, 
w 

A  pointer  to  the  window  in  which  the  movie  is  to  be  displayed.  The  movie 
controller  component  sets  the  movie's  graphics  world  to  match  this  window.  If 
you  set  the  w  parameter  to  NIL,  the  component  uses  the  current  window, 
where 

The  upper-left  corner  of  the  movie  within  the  window  specified  by  the  w 
parameter.  The  movie  controller  component  uses  the  movie's  boundary  Rect 
(IV-2399)  structure  to  determine  the  size  of  the  movie.  GetMovi  eBox  (1-460) 
returns  this  structure. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Associating  Movies  With  Controllers"  (V-2774) 

Related  Java  Methods 

qui cktime . std .movi es . Movi eControl 1 er . Movi eControl  1  er( ) , 
quicktime.std.movies.MultiMovieController.MultiMovieControllerC) 


Inside  QuickTime:  Function  l-Q 
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MCPaste 


MCPaste 


Inserts  a  specified  movie  at  the  current  movie  time  in  the  movie  associated  with  a 
specified  controller. 

ComponentResul t  MCPaste  ( 

Movi eControU er  me, 

Movi e  srcMovi e  ) ; 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi eControl  1  er  (11-1071). 

srcMovi e 

The  movie  to  be  inserted  into  the  current  selection  in  the  movie  associated  with 
the  movie  controller  specified  by  the  me  parameter.  If  you  set  this  parameter  to 
N I L,  the  movie  controller  component  retrieves  the  source  movie  from  the  scrap. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Editing  Movies  With  a  Controller"  (V-2777) 

Related  Java  Methods 

quicktime.std.movies.MovieController.pasteO 


MCPositionController 


Controls  the  position  of  a  movie  and  its  controller  on  the  computer  display. 


ComponentResul t  MCPos 
Movi eControl 1 er 
const  Rect 
const  Rect 
1  ong 


i ti onControl 1 er  ( 
me , 

*movi eRect , 
*control 1 erRect , 
someFl ags  ) ; 
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MCPositionController 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 
movi eRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  specifies  the  coordinates  of  the 
movie's  boundary  Rect  (IV-2399)  structure. 

control  1 erRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  specifies  the  coordinates  of  the 
controller's  boundary  Rect  (IV-2399)  structure.  The  movie  controller 
component  always  centers  the  control  portion  of  the  controller  inside  this 
rectangle.  The  movie  controller  component  only  uses  this  parameter  when  the 
control  portion  of  the  controller  is  detached  from  the  movie.  If  you  are  working 
with  an  attached  controller,  you  can  set  this  parameter  to  NIL. 
someFl  ags 

Flags  (see  below)  that  control  how  the  movie  is  drawn.  If  you  set  these  flags  to 
0,  the  movie  controller  component  centers  the  movie  in  the  rectangle  specified 
by  movi  eRect  and  scales  the  movie  to  fit  in  that  rectangle. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

someFlags  Constants 

mcTopLeftMovi e 

If  this  flag  is  set  to  1,  the  movie  controller  component  places  the  movie  into  the 
upper-left  corner  of  the  display  rectangle  specified  by  the  mov  i  eRect  parameter. 
The  component  scales  the  movie  to  fit  into  the  rectangle.  Note  that  the  control 
portion  of  the  controller  may  fall  outside  of  the  rectangle,  depending  upon  the 
results  of  the  scaling  operation. 

mcScal eMovi eToFi t 

If  this  flag  is  set  to  1,  the  movie  controller  component  resizes  the  movie  to  fit 
into  the  display  rectangle  specified  by  the  movi  eRect  parameter  after  it  places 
the  control  portion  of  the  controller  into  the  rectangle.  If  you  set  this  flag  and 
the  mcTopLeftMovi  e  flag  to  1,  the  movie  controller  component  resizes  the  movie 
to  fit  into  the  specified  rectangle  and  places  the  control  portion  of  the  controller 
outside  of  the  rectangle. 

mcPosi ti onDontlnval i date 

If  this  flag  is  set  to  1,  the  movie  controller  component  is  requested  not  to 
invalidate  areas  of  the  window  that  are  changed  as  a  result  of  repositioning  the 


M 
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11-825 


MCPtlnController 


movie  or  the  controller.  This  flag  is  useful  for  applications  that  use  the  movie 
controller  as  part  of  a  larger  document.  In  particular,  if  the  document  is  scrolled 
using  the  Mac  OS  Scrol  1  Rect  function,  optimal  redrawing  occurs  (that  is, 
scrolled  areas  are  not  redrawn)  if  this  flag  is  set. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Managing  Controller  Attributes"  (V-2775) 

Related  Java  Methods 

qu ickti me. std. mo vies. Mo vieController. position!) 


MCPtlnController 


Reports  whether  a  point  is  in  the  control  area  of  a  movie. 

ComponentResul t  MCPtlnController  ( 

Movi eControl 1 er  me, 

Point  thePt, 

Boolean  *i nControl 1 er  ); 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi eControl  1  er  (11-1071). 
thePt 

The  point  to  be  checked.  This  point  must  be  passed  in  local  coordinates  to  the 
controller's  window.  This  point  is  checked  only  against  the  movie  controller's 
controls,  not  the  movie  itself. 

i nControl 1 er 

Returns  true  if  the  point  is  in  the  controller;  false  if  it  is  not. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

While  you  could  always  determine  if  a  point  is  contained  in  a  movie,  using 
PtlnMovi  e  (11-1148),  the  MCPtlnControl  1  er  function  allows  you  to  determine  if  a 
point  is  in  the  control  area  of  a  movie. 
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MCRemoveAllMovies 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Handling  Movie  Events"  (V-2776) 

Related  Java  Methods 

qui cktime . std .movi es . Movi eControl 1 er . i nControl 1 er( ) 


MCRemoveAllMovies 


Removes  all  movies  associated  with  a  controller. 

ComponentResul t  MCRemoveAllMovies  ( 

Movi eControl 1 er  me  ); 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Related  Java  Methods 

qui cktime . std .movi es . Mul ti Movi eControl 1 er . removeAl 1 Movi es ( ) 


MCRemoveAMovie 


Removes  one  movie  from  a  multi-movie  controller. 

ComponentResul t  MCRemoveAMovie  ( 

Movi eControl 1 er  me. 

Movie  m  ); 
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MCRemoveMovie 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi eControl  1  er  (11-1071). 
m 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  or 
NewMovi  eFromHandl  e  (11-1084). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Related  Java  Methods 

quicktime.std.movies.MultiMovieController. removeAMovi e( ) 


MCRemoveMovie 

Removes  a  movie  from  a  movie  controller. 

ComponentResul t  MCRemoveMovie  ( 

Movi eControl 1 er  me  ) ; 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 
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MCSetActionFilter 


Related  Java  Methods 

qui cktime . std .movi es . Movi eControl 1 er . removeMovi e( ) , 
qui cktime . std .movi es . Mul ti Movi eControl 1 er . removeMovi e( ) 


MCSetActionFilter 


Sets  the  MCActi  onFi  1  terProc  (III— 2096)  callback  for  a  movie  controller. 

ComponentResul t  MCSetActionFilter  ( 

Movi eControl 1 er  me, 

MCActi onFi 1 terUPP  blob  ); 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 

bl  ob 

A  Universal  Procedure  Pointer  to  an  MCActi  onFi  1  terProc  (III— 2096)  callback. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


MCSetActionFilterWithRefCon 


Establishes  an  action  filter  function  for  a  movie  controller. 

ComponentResul t  MCSetActionFilterWithRefCon  ( 

Movi eControl 1 er  me, 

MCActi onFi 1 terWi thRefConUPP  blob, 

long  refCon  ); 


The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 
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MCSetClip 


bl  ob 

A  pointer  to  your  MCActi  onFi  1  terWi  thRefConProc  (III— 2097)  callback.  Set  this 
parameter  to  N I L  to  remove  an  existing  callback. 
refCon 

A  reference  constant  value.  The  movie  controller  component  passes  this 
reference  constant  to  your  action  filter  callback  each  time  it  calls  it.  Use  this 
parameter  to  point  to  a  data  structure  containing  any  information  your  callback 
needs. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

The  movie  controller  component  calls  your  action  filter  function  each  time  the 
component  receives  an  action  for  its  movie  controller.  Your  filter  function  is  then 
free  to  handle  the  action  or  to  refer  it  back  to  the  movie  controller  component.  If  you 
refer  it  back  to  the  movie  controller  component,  the  component  handles  the  action. 

If  your  filter  function  handles  an  action,  you  can  handle  the  action  in  any  way  you 
desire.  For  example,  your  filter  function  could  change  the  operation  of  movie 
controller  buttons.  More  commonly,  applications  use  the  action  filter  function  to 
monitor  actions  of  the  controller.  For  instance,  your  filter  function  might  enable  you 
to  find  out  when  the  user  clicks  the  play  button,  so  that  your  application  can  enable 
appropriate  menu  selections.  Alternatively,  you  can  use  the  filter  function  to  detect 
when  the  user  resizes  the  movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Movie  Controller  Actions"  (V-2773) 

Related  Java  Methods 

quicktime.std.movies.MovieControU  er .  set  Act  i  on  Fi  Her  ( ) , 
quicktime.std.movies.MovieController. removeActi onFi 1  ter ( ) 

MCSetClip 


Lets  you  set  a  movie  controller's  clipping  region. 
ComponentResul  t  MCSetClip  ( 
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Movi eControl 1 er 
RgnHandl e 
RgnHandl e 


me , 

theCl i p , 
movieClip  ); 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 
theCl i p 

A  handle  to  a  region  that  defines  the  controller's  clipping  region.  This  clipping 
region  affects  the  entire  movie  controller  and  its  movie,  including  the 
controller's  badge  and  associated  controls.  Set  this  parameter  to  N I L  to  clear  the 
controller's  clipping  region. 

movi eCl  i p 

A  handle  to  a  region  that  defines  the  clipping  region  of  the  controller's  movie. 
This  clipping  region  affects  only  the  movie  and  the  badge,  not  the  movie 
controller.  Set  this  parameter  to  N I L  to  clear  the  movie  clipping  region. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Managing  Controller  Attributes"  (V-2775) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi eControl  1  er . setCl i p( ) , 
qui ckti me . std .movi es . Movi eControl  1  er . setMovi eCl i p( ) 


See  Also 

For  the  corresponding  get  function,  see  MCGetCl  i  p  (11-805). 


MCSetControllerAttached 


Lets  your  application  control  whether  a  movie  controller  is  attached  to  its  movie  or 
detached  from  it. 

ComponentResul t  MCSetControllerAttached  ( 

Movi eControl 1 er  me. 

Boolean  attach  ); 
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MCSetControllerBoundsRect 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi eControl  1  er  (11-1071). 
attach 

The  action  for  this  function.  Set  the  attach  parameter  to  TRUE  to  cause  the 
controller  to  be  attached  to  its  movie.  Set  this  parameter  to  FALSE  to  detach  the 
controller  from  its  movie. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Managing  Controller  Attributes"  (V-2775) 

Related  Java  Methods 

quicktime.std.movies.MovieControll er . set Attached ( ) 


MCSetControllerBoundsRect 


Lets  you  change  the  position  and  size  of  a  movie  controller. 

ComponentResul t  MCSetControllerBoundsRect  ( 

Movi eControl 1 er  me, 

const  Rect  *bounds  ) ; 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 

bounds 

A  pointer  to  a  Rect  (IV-2399)  structure  that  contains  the  new  boundary  Rect 
(IV-2399)  structure  for  the  movie  controller. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  a  value  of 

control  1  erBoundsNotExact  if  the  boundary  rectangle  has  been 
changed  but  does  not  correspond  to  the  rectangle  you  specified.  In 
this  case,  the  new  boundary  rectangle  is  always  smaller  than  the 


11-832 


Inside  QuickTime:  Function  l-Q 


MCSetControllerPort 


requested  rectangle.  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Managing  Controller  Attributes"  (V-2775) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi eControl 1 er . set Bounds ( ) 


See  Also 

For  the  corresponding  get  function,  see  MCGetControl  1  erBoundsRect  (11-806). 


MCSetControllerPort 


Lets  your  application  set  the  graphics  port  for  a  movie  controller. 

ComponentResul t  MCSetControllerPort  ( 

Movi eControl 1 er  me, 

CGrafPtr  gp  ); 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 

9P 

A  pointer  to  the  new  graphics  port  for  the  movie  controller.  Set  this  parameter 
to  N I L  to  use  the  current  graphics  port. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

Movie  controller  components  use  MCSetControllerPort  each  time  you  create  a  new 
movie  controller.  Hence,  your  component  must  be  set  to  a  valid  port  before  creating 
a  new  movie  controller.  You  can  use  this  function  to  place  a  movie  and  its  associated 
movie  controller  in  different  graphics  ports.  If  you  are  using  an  attached  controller, 
both  the  controller  and  the  movie's  graphics  ports  are  changed.  If  you  are  using  a 
detached  controller,  this  function  changes  only  the  graphics  port  of  the  control 
portion  of  the  controller.  You  must  use  SetMovi  eGWorl  d  (III— 1619)  followed  by 
MCMovieChanged  (11-822)  to  change  other  portions. 


Inside  QuickTime:  Function  l-Q 


11-833 


MCSetDuration 


pascal  ComponentResul t  MCSetControl 1 erPort  ( Movi eControll er  me, 

CGrafPtr  gp) ; 


Special  Considerations 

The  movie  controller  component  may  use  the  foreground  and  background  colors 
from  the  graphics  port  at  the  time  this  function  is  called  to  colorize  the  movie 
controller. 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Managing  Controller  Attributes"  (V-2775) 

Related  Java  Methods 

quicktime.std.movies.MovieController.setPortO 


See  Also 

For  the  corresponding  get  function,  see  MCGetControl  1  erPort  (11-810). 


MCSetDuration 


Lets  your  application  set  a  controller's  duration  in  the  case  where  a  controller  does 
not  have  a  movie  associated  with  it. 

ComponentResul t  MCSetDuration  ( 

Movi eControl 1 er  me, 

TimeValue  duration  ); 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi eControl  1  er  (11-1071). 

durati on 

The  new  duration  for  the  movie.  This  duration  value  must  be  in  the  controller's 
time  scale. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


11-834 
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MCSetMovie 


Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Getting  and  Setting  Movie  Controller  Time"  (V-2778) 

Related  Java  Methods 

qui cktime . std .movi es . Movi eControl 1 er . set Dura ti on( ) 


MCSetMovie 


Associates  a  movie  with  a  specified  movie  controller. 


ComponentResul t  MCSetMovie  ( 

Movi eControl 1 er  me. 

Movie  theMovie, 

WindowPtr  movieWindow, 

Point  where  ); 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 
theMovi e 

The  movie  to  be  associated  with  the  movie  controller.  Set  this  value  to  N I L  to 
remove  the  movie  from  the  controller. 

movi eWi ndow 

The  window  in  which  the  movie  is  to  be  displayed.  The  movie  controller 
component  sets  the  movie's  graphics  world  to  match  this  window.  If  you  set  the 
w  parameter  to  NIL,  the  component  uses  the  current  window. 

where 

The  upper-left  corner  of  the  movie  within  the  window  specified  by  the 
movi  eWi  ndow  parameter.  The  movie  controller  component  uses  the  movie's 
boundary  Rect  (IV-2399)  structure  to  determine  the  size  of  the  movie. 

GetMovi  eBox  (1-460)  returns  this  structure. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Function  l-Q 


11-835 


MCSetUpEditMenu 


Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Associating  Movies  With  Controllers"  (V-2774) 

Related  Java  Methods 

quicktime.std.movies.MovieController.setMovieO, 
quicktime.std.movies.MultiMovieControll er . setMovi e( ) , 
quicktime.std.movies.MultiMovieController.addMovieO 


MCSetUpEditMenu 


Correctly  highlights  and  names  the  items  in  your  application's  Edit  menu. 

ComponentResul t  MCSetUpEditMenu  ( 

Movi eControl 1 er  me, 

long  modifiers, 

MenuHandl e  mh  ) ; 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131),  or  from 
NewMovi eControl  1  er  (11-1071). 

modi f i ers 

The  current  modifiers  from  the  mouse-down  or  key-down  event  to  which  you 
are  responding, 
mh 

A  menu  handler  to  your  current  Edit  menu.  The  first  six  items  in  your  Edit 
menu  should  be  the  standard  editing  commands:  Undo,  a  blank  line.  Cut, 
Copy,  Paste,  and  Clear. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Editing  Movies  With  a  Controller"  (V-2777) 


11-836 
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MCSetVisible 


MCSetVisible 


Lets  your  application  control  the  visibility  of  a  movie  controller. 

ComponentResul t  MCSetVisible  ( 

Movi eControl 1 er  me. 

Boolean  visible  ); 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 

vi sibl e 

Set  to  TRUE  to  cause  the  controller  to  be  visible,  or  FALSE  to  make  the  controller 
invisible. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Managing  Controller  Attributes"  (V-2775) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi eControl 1 er . set Vi  si bl e( ) 


See  Also 

For  the  corresponding  get  function,  see  MCGetVisible  (11-815). 


MCTrimMovieSegment 


Undocumented 

ComponentResul t  MCTrimMovieSegment  ( 
Movi eControl 1 er  me  ); 


The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 


Inside  QuickTime:  Function  l-Q 


11-837 


MCUndo 


function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Movi  es .  h 


MCUndo 


Lets  your  application  discard  the  effects  of  the  most  recent  edit  operation. 

ComponentResul t  MCUndo  ( 

Movi eControl 1 er  me  ) ; 


me 

The  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi eControl  1  er  (11-1071). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Editing  Movies  With  a  Controller"  (V-2777) 

Related  Java  Methods 

quicktime.std.movies.MovieController.undot) 


Media3DGetCameraAngleAspect 


Deprecated. 

ComponentResul t  Medi a3DGetCameraAngl eAspect  ( 
MediaHandler  mh, 

QTF1 oatSi ngl e  *fov, 

QTF1 oatSi ngl e  *aspectRati oXToY  ); 


11-838 


Inside  QuickTime:  Function  l-Q 


Media3DGetCameraData 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


Media3DGetCameraData 


Deprecated. 

ComponentResul t  Medi a3DGetCameraData  ( 
MediaHandler  mh, 

void  *cameraData  ); 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


Media3DGetCameraRange 


Deprecated. 

ComponentResul t  Medi a3DGetCameraRange  ( 
MediaHandler  mh, 

void  *tQ3CameraRange  ); 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


Media3DGetCurrentGroup 


Deprecated. 

ComponentResul t  Medi a3DGetCurrentGroup  ( 
MediaHandler  mh, 

void  *group  ); 


Inside  QuickTime:  Function  l-Q 


11-839 


Media3DGetNamedOb  j  ectList 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es .  h 


Media3DGetNamedObjectList 


Deprecated. 

ComponentResul t  Media3DGetNamed0bjectList  ( 
MediaHandler  mh, 

QTAtomContai ner  *objectl_ist  ); 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Related  Java  Methods 

quicktime.std.movies.media.ThreeDMediaHandler.getNamedObjectListt ) , 
quicktime.std.movi es . AtomContai ner . f romThreeDMedi aHandlerObjectt ) 


Media3DGetRendererList 


Deprecated. 

ComponentResul t  Medi a3DGetRendererLi st  ( 
MediaHandler  mh, 

QTAtomContai ner  *rendererl_i  st  ); 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Related  Java  Methods 

quicktime.std.movi es .medi a .ThreeDMedi aHandler.getRendererListt ) , 
qui  ckti  me .  std  .movi  es  .AtomContai  ner .  f  romThreeDMedi  aHandlerRendererO 
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Media3DGetViewOb  ject 


Media3DGetViewObject 


Deprecated. 

ComponentResul t  Medi a3DGetView0bject  ( 
MediaHandler  mh, 

void  *tq3viewdbject  ); 


Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


Media3DRotateNamedOb  j  ectT  o 

Deprecated. 


ComponentResul t  Medi a3DRotateNamed0bjectTo  ( 


Medi aHandl er 
char 
Fi  xed 
Fi  xed 
Fi  xed 


mh , 

*objectName, 
xDegrees , 
yDegrees , 
zDegrees  ); 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


Media3DScaleNamedObj  ectT  o 


Deprecated. 


ComponentResul t  Media3DScal eNamedObjectTo 


Medi aHandl er 
char 
Fi  xed 
Fi  xed 
Fi  xed 


mh , 

*objectName, 
xScal e , 
yScal e , 
zScale  ); 


( 


function  result 


Inside  QuickTime:  Function  l-Q 
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Media3DSetCameraAngleAspect 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es .  h 


Media3DSetCameraAngleAspect 


Deprecated. 

ComponentResul t  Medi a3DSetCameraAngl eAspect  ( 
MediaHandler  mh, 

QTF1 oatSi ngl e  fov, 

QTF1 oatSi ngl e  aspectRati 0XT0Y  ); 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es .  h 


Media3DSetCameraData 


Deprecated. 

ComponentResul t  Medi a3DSetCameraData  ( 
MediaHandler  mh, 

voi d  *cameraData  ) ; 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es .  h 


Media3DSetCameraRange 


Deprecated. 

ComponentResul t  Medi a3DSetCameraRange  ( 
MediaHandler  mh, 

void  *tQ3CameraRange  ); 


11-842 


Inside  QuickTime:  Function  l-Q 


Media3DTranslateNamedOb  j  ectTo 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


Media3DT  ranslateNamedOb  j  ectT  o 


Deprecated. 


Component Res ul t  Medi a3DTransl ateNamedObjectTo 


Medi aHandl er 
char 
Fi  xed 
Fi  xed 
Fi  xed 


mh , 

*objectName, 

x, 

y , 

z  ); 


( 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


MediaChangedNonPrimarySource 


Informs  a  media  handler  of  a  change  in  the  source  of  media  data  from  another 
media  handler. 

ComponentResul t  MediaChangedNonPrimarySource  ( 

MediaHandler  mh, 

long  inputlndex  ); 


mh 

A  reference  to  a  media  handler.  You  can  obtain  this  reference  from 
GetMedi  aHandl  er  (1-432). 

i nputlndex 

The  ID  of  the  entry  in  the  media's  input  map  to  which  the  changed  data 
corresponds. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Function  l-Q 


11-843 


MediaCompare 


Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaCompare 


Lets  a  media  handler  determine  whether  the  Movie  Toolbox  should  allow  one  track 
to  be  pasted  into  another. 


ComponentResul t  MediaCompare  ( 


Medi aHandl er 
Bool ean 
Medi  a 

Componentlnstance 


mh , 

*i sOK, 
srcMedi a , 
srcMedi a Component 


) : 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

isOK 

A  pointer  to  a  Bool  ean  value.  Your  media  handler  must  set  this  value  to  TRUE  if 
the  source  media  and  the  media  associated  with  the  media  handler  have 
equivalent  media  settings,  so  that  pasting  the  two  together  would  cause  no 
media  information  loss. 
srcMedi a 

The  source  media  for  this  operation. 
srcMedi a Component 

The  source  media  component  for  this  operation. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 


MediaCurrentMediaQueuedData 


Retrieves  the  timing  of  the  current  media  in  queued  data. 
ComponentResul t  MediaCurrentMediaQueuedData  ( 


11-844 


Inside  QuickTime:  Function  l-Q 


MediaDisposeTargetRefCon 


MediaHandler  mh, 

long  *milliSecs  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
mi  1 1 i Secs 

A  pointer  to  the  number  of  milliseconds  to  the  current  data. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers  .  h 


MediaDisposeT  argetRef  Con 


Undocumented 

ComponentResul t  MediaDisposeTargetRefCon  ( 
MediaHandler  mh, 

long  targetRefCon  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
targetRefCon 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaDoIdleActions 

Forces  a  media  handler  to  perform  its  idle-time  actions. 

ComponentResul t  MediaDoIdleActions  ( 

MediaHandler  mh  ); 


Inside  QuickTime:  Function  l-Q 
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MediaEmptySampleCache 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaEmptySampleCache 


Deletes  any  sample  data  that  the  media  handler  has  cached. 

ComponentResul t  MediaEmptySampleCache  ( 

MediaHandler  mh, 

long  sampleNum, 

1 ong  sampl eCount  ) ; 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
sampl eNum 

The  ID  of  the  first  sample  to  delete, 
sampl eCount 

The  number  of  samples  to  delete.  Passing  -1  means  delete  sampl  eNum  and  all 
samples  after  it. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  is  an  optional  media  handler  function.  Most  developers  will  not  need  to  call  it. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaEnterEmptyEdit 

Undocumented 

ComponentResul t  MediaEnterEmptyEdit  ( 


11-846 
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MediaFlushN  onPrimarySourceData 


Medi aHandl er  mh  ); 
mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaFlushNonPrimarySourceData 


Flushes  data  that  a  media  handler  gets  from  another  media  handler. 

ComponentResul t  MediaFlushNonPrimarySourceData  ( 

MediaHandler  mh, 

long  inputlndex  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
i nputlndex 

The  ID  of  the  entry  in  the  media's  input  map  to  which  the  flushed  data 
corresponds. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers  .  h 


MediaForceUpdate 


Forces  a  media  update. 

ComponentResul t  MediaForceUpdate  ( 
MediaHandler  mh, 

long  f orceUpdateFl ags  ); 


Inside  QuickTime:  Function  l-Q 


11-847 


MediaGetActionsForQTEvent 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
forceUpdateFl ags 

Flags  (see  below)  that  define  the  update  to  be  forced. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

forceUpdateFlags  Constants 

forceUpdate Redraw 
Force  a  redraw. 
forceUpdateNewBuffer 
Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaGetActionsForQTEvent 


Undocumented 


Component Res ul t  Medi aGetActi onsForQT Event 
MediaHandler  mh, 

QTEventRecordPtr  event, 

long  targetRefCon , 

QTAtomContai ner  Container, 

QTAtom  *atom  ); 


( 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
event 

A  pointer  to  a  QTEventRecord  (IV-2353)  structure. 
targetRefCon 

Undocumented 
contai ner 

Undocumented 

atom 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


11-848 


Inside  QuickTime:  Function  l-Q 


MediaGetClock 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaGetClock 


Gets  the  clock  component  associated  with  a  media. 

ComponentResul t  MediaGetClock  ( 

MediaHandler  mh, 

Componentlnstance  *clock  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
cl  ock 

A  pointer  to  a  clock  component. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaGetDrawingRgn 


Specifies  a  portion  of  the  screen  that  must  be  redrawn,  defined  in  the  movie's 
display  coordinate  system. 

ComponentResul t  MediaGetDrawingRgn  ( 

MediaHandler  mh, 

RgnHandle  *partialRgn  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

parti al Rgn 

A  pointer  to  a  handle  to  a  MacRegi  on  (IV-2303)  structure  that  defines  the  screen 
region  to  be  redrawn,  using  the  movie's  display  coordinate  system.  Note  that 


Inside  QuickTime:  Function  l-Q 


11-849 


MediaGetEffectiveSoundBalance 


your  component  is  responsible  for  disposing  of  this  region  once  drawing  is 
complete.  Since  the  base  media  handler  will  use  this  region  during  redrawing, 
it  is  best  to  dispose  of  it  when  your  component  is  closed. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  Movie  Toolbox  calls  this  function  in  order  to  determine  what  part  of  the  screen 
needs  to  be  redrawn.  By  default,  theMovi  e  Toolbox  redraws  the  entire  region  that 
belongs  to  your  component.  If  your  component  determines  that  only  a  portion  of 
the  screen  has  changed,  and  has  indicated  this  to  the  toolbox  by  setting  the 
mParti  al  Draw  flag  to  1  in  the  fl  agsOut  parameter  of  the  Medi  aldl  e  (11-874)  function, 
the  toolbox  calls  your  component's  Medi  aGetDrawi  ngRgn  (11-849)  function.  Your 
component  returns  a  region  that  defines  the  changed  portion  of  the  track's  display 
region. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "Managing  Graphics  Data"  (V-2864) 


MediaGetEffectiveSoundBalance 


Gets  the  effective  sound  balance  setting  of  a  media  handler. 

ComponentResul t  MediaGetEffectiveSoundBalance  ( 
MediaHandler  mh, 

short  *bal ance  ) ; 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
bal ance 

A  pointer  to  an  integer.  The  Movie  Toolbox  returns  the  current  balance  setting 
of  the  media  handler  as  a  16-bit,  fixed-point  value.  The  high-order  8  bits  contain 
the  integer  part  of  the  value;  the  low-order  8  bits  contain  the  fractional  part. 
Valid  balance  values  range  from  -1.0  to  1.0.  Negative  values  emphasize  the  left 
sound  channel,  and  positive  values  emphasize  the  right  sound  channel;  a  value 
of  0  specifies  neutral  balance. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


11-850 
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MediaGetEffective  Volume 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaGetEf  f  ective  V  olume 


Gets  the  effective  volume  setting  for  a  media  handler. 

ComponentResul t  Medi aGetEffecti veVol ume  ( 
MediaHandier  mh, 

short  *volume  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
vol ume 

The  media's  current  volume  setting.  This  value  is  represented  as  a  16-bit, 
fixed-point  number.  The  high-order  8  bits  contain  the  integer  portion;  the 
low-order  8  bits  contain  the  fractional  part.  Volume  values  range  from  -1.0  to 
1.0.  Negative  values  play  no  sound  but  preserve  the  absolute  value  of  the 
volume  setting. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaGetErrorString 


Undocumented 

aGetErrorStri ng  ( 
mh , 

theError , 
errorstring  ); 


ComponentResul  t  Medi 
Medi aHandl  er 
ComponentResul  t 
Str255 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
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MediaGetGraphicsMode 


theError 

An  error  identifier;  see  "Error  Codes"  (IV-2663). 
errorStri ng 

A  text  string  that  describes  the  error. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaGetGraphicsMode 


Obtains  the  graphics  mode  and  blend  color  values  currently  in  use  by  any  media 
handler. 

ComponentResul t  MediaGetGraphicsMode  ( 

MediaHandler  mh, 

long  *mode, 

RGBCol or  *opCol or  )  ; 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

mode 

A  pointer  to  a  long  integer.  The  media  handler  returns  the  graphics  mode 
currently  in  use  by  the  media  handler;  see  "Graphics  Transfer  Modes" 
(IV-2670). 

opCol or 

A  pointer  to  an  RGBCol  or  (IV-2403)  structure.  The  Movie  Toolbox  returns  the 
color  currently  in  use  by  the  media  handler.  This  is  the  blend  value  for  blends 
and  the  transparent  color  for  transparent  operations.  The  toolbox  supplies  this 
value  to  QuickDraw  when  you  draw  in  addPi  n,  subPi  n,  bl  end,  transparent,  or 
graphi  csModeStrai  ghtAl  phaBl  end  mode. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


11-852 


Inside  QuickTime:  Function  l-Q 


MediaGetlnvalidRegion 


Programming  Info 

C  interface  file:  Medi  aHandl  ers  .  h 

Programming  summary:  "Managing  Graphics  Data"  (V-2864),  "Video  Media 
Handler  Functions"  (V-2755) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Vi sual Medi aHandl er . getGraphi csMode( ) 


See  Also 

You  can  set  the  graphics  mode  and  blend  color  of  any  media  handler  by  calling 
Medi  aSetGraphi  csMode  (11-892). 


MediaGetlnvalidRegion 


Gets  the  invalid  region  for  a  media  handler's  current  display. 

ComponentResul t  MediaGetlnvalidRegion  ( 

MediaHandler  mh, 

RgnHandle  rgn  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
rgn 

A  handle  to  aMac  Region  (IV-2303)  structure  that  defines  an  invalid  region. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaGetMedialnfo 


Lets  a  derived  media  handler  obtain  the  private  data  stored  in  its  media. 

ComponentResul t  MediaGetMedialnfo  ( 

MediaHandler  mh. 

Handle  h  ); 


Inside  QuickTime:  Function  l-Q 
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MediaGetMediaLoadState 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 
h 

A  handle  to  storage  containing  your  media  handler's  proprietary  information. 
Your  media  handler  creates  this  private  data  when  the  Movie  Toolbox  calls 
your  Medi  aPutMedialnfo  (11-884)  function.  Do  not  dispose  of  this  handle;  it  is 
owned  by  the  Movie  Toolbox. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  derived  media  handler  should  support  this  function  if  you  store  private  data 
in  your  media. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 


MediaGetMediaLoadState 


Queried  byGetMovieLoadState  (1-477)  to  help  determine  a  movie's  load  state. 

ComponentResul t  MediaGetMediaLoadState  ( 

MediaHandler  mh, 

long  *medi aLoadState  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
medi aLoadState 
Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

GetMovieLoadState  (1-477)  queries  any  idling  importers  associated  with  a  movie, 
checks  if  the  movie  is  fast  starting,  and  queries  media  handlers.  The  minimum  load 
state  of  all  of  these  is  then  considered  to  be  the  load  state  of  the  movie. 

Version  Notes 

Introduced  in  QuickTime  4.1. 


11-854 
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MediaGetName 


Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaGetName 


Returns  the  name  of  the  media  type. 

ComponentResul t  MediaGetName  ( 

Medi aHandl er  mh, 

Str255  name, 

long  requestedLanguage, 

long  *actual Language  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

name 

The  name  of  the  media  type;  for  example,  the  video  media  handler  returns  the 
string  ‘ vi deo ’ . 
requestedLanguage 

The  language  in  which  you  want  the  name  returned;  see  "Localization  Codes" 
(IV-2673). 

actual  Language 

A  pointer  to  the  actual  language  in  which  the  name  is  returned;  see 
"Localization  Codes"  (IV-2673) 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 


MediaGetNextBoundsChange 


Determines  when  a  media  causes  a  spatial  change  to  a  movie. 

ComponentResul t  MediaGetNextBoundsChange  ( 

MediaHandler  mh, 

TimeValue  *when  ); 


Inside  QuickTime:  Function  l-Q 
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MediaGetNextStepTime 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

when 

A  pointer  to  a  movie  time  value,  which  your  media  handler  must  set.  Be  sure  to 
use  the  movie's  time  base.  Use  the  current  effective  rate  to  determine  the 
direction  your  media  is  playing.  Set  this  value  to  -1  if  there  are  no  more  changes 
in  the  specified  direction. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  derived  media  handler  should  support  this  function  if  you  change  the  shape 
of  your  media's  spatial  representation  during  playback.  The  Movie  Toolbox  calls 
this  function  only  if  you  have  set  the  handl  erHasSpati  al  flag  to  1  in  the  f  1  ags 
parameter  of  Medi  aSetHandl  erCapabi  1  i  ti  es  (11-894). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "Managing  Graphics  Data"  (V-2864) 


MediaGetNextStepTime 


Searches  for  the  next  forward  or  backward  step  time  from  the  given  media  time. 


Component  Re sul t  Medi aGetNextStepT i me 


Medi aHandl er 
short 
T i meVal ue 
T i  meVal  lie 
Fi  xed 


mh , 

fl ags , 

medi aTi mein , 
*medi aT i meOut , 
rate  ) ; 


( 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

fl  ags 

Flags  (see  below)  that  specify  search  parameters. 


11-856 
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medi a Time  In 

A  time  value  that  establishes  the  starting  point  for  the  search.  This  time  value 
is  in  the  media's  time  scale, 
medi aTi meOut 

The  step  time  (the  time  of  the  next  frame)  calculated  by  the  media  handler.  The 
media  handler  should  return  the  first  time  value  it  finds  that  meets  the  search 
criteria  specified  in  the  flags  parameter.  This  time  value  is  in  the  media's  time 
scale. 

rate 

The  search  direction.  Negative  values  search  backward  from  the  starting  point 
specified  in  the  medi  aTi  me  In  parameter.  Other  values  cause  a  forward  search. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

nextTimeStep 

Set  this  flag  to  1  to  search  for  the  next  frame.  The  normal  method  for  stepping 
forward  to  the  next  frame  is  to  use  one  of  these  calls  to  locate  the  time  of  the  next 
visual  sample.  This  works  well  for  most  media  types,  including  video  and  text. 
Unfortunately,  it  does  not  work  well  for  MPEG,  because  QuickTime  stores  an 
entire  MPEG  stream  as  a  single  sample.  Therefore,  stepping  to  the  next  sample 
would  actually  skip  to  the  end  of  the  entire  sequence.  To  solve  this  problem,  set 
this  flag,  which  is  specifically  intended  for  stepping  through  frames. 
nextTimeEdgeOk 

Instructs  the  Movie  Toolbox  that  you  are  willing  to  receive  information  about 
elements  that  begin  or  end  at  the  time  specified  by  the  mediaTimeln  parameter. 
Set  this  flag  to  1  to  accept  this  information.  This  flag  is  especially  useful  at  the 
beginning  or  end  of  a  media. 

Discussion 

This  function  allows  a  derived  media  handler  to  return  the  next  step  time  from  the 
specified  media  time.  The  mechanism  in  QuickTime  used  for  stepping  backwards 
and  forwards  a  frame  at  a  time  are  the  interesting  time  calls: 
GetMovieNextlnterestingTime  (1-480),  GetTrackNextlnterestingTime  (1-537),  and 
GetMedi  a  Next  Interest!  ngTime  (1-437). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 
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MediaGetOffscreenBufferSize 


MediaGetOffscreenBufferSize 

Determines  the  dimensions  of  the  offscreen  buffer. 

ComponentResul t  MediaGetOffscreenBufferSize  ( 

MediaHandler  mh, 

Rect  *bounds, 

short  depth, 

CTabHandl e  ctab  ) ; 

mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 
bounds 

A  Rect  (IV-2399)  structure  that  defines  the  boundaries  of  your  offscreen  buffer, 
depth 

The  depth  of  the  offscreen. 

ctab 

A  handle  to  the  Col  orTabl  e  (IV-2210)  structure  associated  with  the  offscreen 
buffer. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Before  the  base  media  handler  allocates  an  offscreen  buffer  for  your  derived  media 
handler,  it  calls  this  function.  The  depth  and  color  table  used  for  the  buffer  are  also 
passed.  When  this  function  is  called,  the  bounds  parameter  specifies  the  size  that  the 
base  media  handler  intends  to  use  for  your  offscreen  buffer.  You  can  modify  this  as 
appropriate  before  returning.  This  capability  is  useful  if  your  media  handler  can 
draw  only  at  particular  sizes.  It  is  also  useful  for  implementing  antialiased  drawing; 
you  can  request  a  buffer  that  is  larger  than  your  destination  area  and  have  the  base 
media  handler  scale  the  image  down  for  you. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 


11-858 
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MediaGetPublicInfo 


MediaGetPublicInfo 


Undocumented 

ComponentResul t  MediaGetPublicInfo  ( 
MediaHandler  mh, 

OSType  i nf oSel ector , 

void  *infoDataPtr, 

Size  *ioDataSize  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 
i nf oSel ector 

Undocumented 
i nfoDataPtr 

Undocumented 
i oDataSi ze 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers  .  h 


MediaGetSampleDataPointer 


Allows  a  derived  media  handler  to  obtain  a  pointer  to  the  sample  data  for  a 
particular  sample  number,  the  size  of  that  sample,  and  the  index  of  the  sample 
description  associated  with  that  sample. 

ComponentResul t  MediaGetSampleDataPointer  ( 

MediaHandler  mh, 
long  sampleNum, 

Ptr  *dataPtr, 

long  *dataSize, 

long  *sampl eDescIndex  ); 


Inside  QuickTime:  Function  l-Q 
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MediaGetSoundBalance 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 
sampl eNum 

The  number  of  the  sample  that  is  to  be  loaded. 
dataPtr 

A  pointer  to  a  pointer  to  receive  the  address  of  the  loaded  sample  data. 
dataSi ze 

A  pointer  to  a  field  that  is  to  receive  the  size,  in  bytes,  of  the  sample, 
sampl eDescIndex 

A  pointer  to  a  long  integer.  This  function  returns  an  index  value  to  the  sample 
description  that  corresponds  to  the  returned  sample  data.  If  you  do  not  want 
this  information,  set  the  parameter  to  NIL. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns  a  pointer  to  the  data  for  a  particular  sample  number  from  a 
movie  data  file.  It  provides  access  to  the  base  media  handler's  caching  services  for 
sample  data.  It  is  a  service  provided  by  the  base  media  handler  for  its  clients. 

Special  Considerations 

Each  call  to  this  function  must  be  balanced  by  a  call  to 

Medi  aRel  easeSampl  eDataPoi  nter  (11-886)  or  the  memory  will  not  be  released.  This 
function  generally  provides  better  overall  performance  than  GetMedi  a  Sampl  e  (1-443). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 


MediaGetSoundBalance 


Obtains  the  sound  balance  of  the  media  handler. 

ComponentResul t  MediaGetSoundBalance  ( 
MediaHandler  mh, 

short  *bal ance  ) ; 


11-860 


Inside  QuickTime:  Function  l-Q 


MediaGetSoundBassAndTreble 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
bal ance 

A  pointer  to  an  integer.  The  Movie  Toolbox  returns  the  current  balance  setting 
of  the  media  handler  as  a  16-bit,  fixed-point  value.  The  high-order  8  bits  contain 
the  integer  part  of  the  value;  the  low-order  8  bits  contain  the  fractional  part. 
Valid  balance  values  range  from  -1.0  to  1.0.  Negative  values  emphasize  the  left 
sound  channel,  and  positive  values  emphasize  the  right  sound  channel;  a  value 
of  0  specifies  neutral  balance. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "Sound  Media  Handler  Functions"  (V-2755) 

Related  Java  Methods 

qui cktime . std .movi es .medi a .Audi oMedi aHandl er . get Bal  ance( ) , 
qui cktime . std .movi es .medi a.SoundMediaHandler.getBalanceO, 
qui  cktime .  std  .movi  es  .medi  a.MPEGMediaHandler.getBalanceO 


See  Also 

For  the  corresponding  set  function,  see  Medi  aSetSoundBal  ance  (11-904). 


MediaGetSoundBass  AndT  reble 


Gets  the  bass  and  treble  settings  for  a  media  handler. 

ComponentResul t  MediaGetSoundBassAndTreble  ( 
MediaHandler  mh, 

short  *bass, 

short  *treble  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 

bass 

Undocumented 
trebl e 

Undocumented 
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MediaGetSoundEqualizerBandLevels 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

See  Also 

For  the  corresponding  set  function,  see  Medi  aSetSoundBassAndT rebl  e  (11-905). 


MediaGetSoundEqualizerBandLevels 


Gets  the  sound  equalizer  band  levels  for  a  media  handler. 

ComponentResul t  Medi aGetSoundEqual i zerBandLevel s  ( 
MediaHandler  mh, 

UInt8  *bandLevels  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
bandLevel s 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaGetSoundEqualizerBands 


Gets  the  sound  equalizer  settings  for  a  media  handler. 

ComponentResul t  MediaGetSoundEqualizerBands  ( 
MediaHandler  mh, 

Medi aEQSpectrumBandsRecordPtr  spectrumlnfo  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 


11-862 


Inside  QuickTime:  Function  l-Q 


MediaGetSoundLevelMeterlnfo 


spectrumlnfo 

A  pointer  to  a  Medi  aEQSpectrumBandsRecord  (IV-2304)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

See  Also 

For  the  corresponding  set  function,  see  Medi  aSetSoundEqual  i  zerBands  (11-906). 


MediaGetSoundLevelMeterlnfo 


Gets  the  right  and  left  sound  level  meter  values  for  a  media  handler. 

ComponentResul t  MediaGetSoundLevelMeterlnfo  ( 

MediaHandler  mh. 

Level MeterlnfoPtr  levellnfo  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
1 evel Info 

A  pointer  to  a  Level  Meterlnfo  (IV-2301)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaGetSoundLevelMeteringEnabled 


Determines  if  a  media  handler's  sound  level  metering  capability  is  enabled. 

ComponentResul t  Medi aGetSoundLevel Meteri ngEnabl ed  ( 

MediaHandler  mh. 

Boolean  *enabled  ); 


Inside  QuickTime:  Function  l-Q 


11-863 


MediaGetSoundOutputComponent 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
enabl ed 

A  pointer  to  a  Bool  ean;  it  is  TRUE  if  sound  level  metering  is  enabled,  FALSE 
otherwise. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

See  Also 

For  the  corresponding  set  function,  see  Medi  aSetSoundLevel  Meteri  ngEnabl  ed 
(11-906). 

MediaGetSoundOutputComponent 


Gets  the  sound  output  component  associated  with  a  media  handler. 

ComponentResul t  MediaGetSoundOutputComponent  ( 

MediaHandler  mh, 

Component  *outputComponent  ) ; 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
outputComponent 

An  instance  of  a  sound  output  component. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

See  Also 

For  the  corresponding  set  function,  see  Medi  aSetSoundOutputComponent  (11-908). 


11-864 


Inside  QuickTime:  Function  l-Q 


MediaGetSrcRgn 


MediaGetSrcRgn 


Specifies  an  irregular  destination  display  region  to  the  Movie  Toolbox. 

ComponentResul t  MediaGetSrcRgn  ( 

MediaHandler  mh, 

RgnHandle  rgn, 

TimeValue  atMediaTime  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 
rgn 

A  handle  to  a  Mac  Reg  i  on  (IV-2303)  structure.  When  the  Movie  Toolbox  calls 
your  function,  this  region  is  initialized  to  the  track's  boundary  rectangle,  which 
is  defined  by  the  width  and  height  fields  in  the  GetMovi  eCompl  eteParams 
(IV-2268)  structure  that  you  obtain  when  the  Movie  Toolbox  calls  your 
Medi  alni  ti  al  i  ze  (11-877)  function.  Your  media  handler  may  then  alter  this 
region  as  appropriate,  so  that  it  corresponds  to  the  boundaries  of  your  media's 
display  image.  Note  that  this  region  is  in  the  track's  coordinate  system,  not  the 
movie's.  Do  not  dispose  of  this  region;  it  is  owned  by  the  Movie  Toolbox. 
atMedi aTi me 

The  time  value  at  which  the  Movie  Toolbox  wants  to  know  what  the  source 
region  is. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  derived  media  handler  should  support  this  function  if  your  media  does  not 
completely  fill  the  track  rectangle  during  playback.  The  Movie  Toolbox  calls  this 
function  only  if  you  have  set  the  handlerHasSpatial  flag  to  1  in  the  flags  parameter 
of  the  Medi  aSetHandl  erCapabi  1  i  ti  es  (11-894)  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "Managing  Graphics  Data"  (V-2864) 


MediaGetTrackOpaque 


Determines  whether  a  media  is  transparent  or  opaque  when  displayed. 


Inside  QuickTime:  Function  l-Q 


11-865 


MediaGetURLLink 


ComponentResul t  Medi aGetTrackOpaque  ( 
MediaHandler  mh, 

Boolean  *trackls0paque  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 
tracklsOpaque 

A  pointer  to  a  Bool  ean  value.  Your  media  handler  must  set  this  value  to  TRUE  if 
your  media  is  semitransparent  (that  is,  you  draw  in  blend  mode);  otherwise, 
leave  the  flag  unchanged. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  derived  media  handler  should  support  this  function  if  your  media  is 
semitransparent  when  displayed  or  if  you  handle  display  transfer  modes.  The 
Movie  Toolbox  calls  this  function  only  if  you  have  set  the  handlerHasSpatial  or 
handl  erCanT ransferMode  flag  to  1  in  the  f  1  ags  parameter  of  the 
Medi  aSetHandl  erCapabi  1  i  ti  es  (11-894)  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "Managing  Graphics  Data"  (V-2864) 

Related  Java  Methods 

qu i c kti me. std. mo vies. medi a. Visual MediaHandler. getT rackOpaquet ) 


MediaGetURLLink 


Undocumented 

ComponentResul t  MediaGetURLLink  ( 
MediaHandler  mh, 

Point  di spl ayWhere , 

Handle  *urlLink  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
di spl ayWhere 

Undocumented 


11-866 


Inside  QuickTime:  Function  l-Q 


MediaGetUserPreferredCodecs 


url  Li  nk 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaGetUserPreferredCodecs 


Retrieves  the  list  of  components  last  passed  to  the  media  handler  by  a  call  to 
Medi  aSetUserPreferredCodecs  (11-909). 

ComponentResul t  MediaGetUserPreferredCodecs  ( 

MediaHandier  mh, 

CodecComponentHandl e  *userPreferredCodecs  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 
userP referred Codecs 

A  pointer  to  a  handle  containing  component  identifiers.  If  the  media  handler 
currently  has  a  preferred  component  list,  it  will  copy  that  list  into  a  new  handle 
and  store  the  new  handle  in  this  variable.  If  the  media  handler  does  not 
currently  have  a  preferred  component  list,  it  will  store  NI L  in  this  variable.  The 
caller  must  dispose  of  this  handle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  badComponentSel  ector  if  the 
media  handler  component  does  not  support  this  call.  Returns  noErr 
if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

See  Also 

For  the  corresponding  set  function,  see  Medi  aSetUserPreferredCodecs  (11-909). 


Inside  QuickTime:  Function  l-Q 


11-867 


MediaGetVideoParam 


MediaGetVideoParam 


Retrieves  the  value  of  the  brightness,  contrast,  hue,  sharpness,  saturation,  black 
level,  or  white  level  of  a  video  image. 

ComponentResul t  MediaGetVideoParam  ( 

MediaHandler  mh, 

long  whichParam, 

unsigned  short  *value  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 
whi chParam 

A  constant  (see  below)  that  specifies  the  video  parameter  whose  value  you 
want  to  retrieve, 
val  ue 

The  actual  value  of  the  requested  video  parameter.  The  meaning  of  the  values 
vary  depending  on  the  implementation. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

whichParam  Constants 

kMedi aVideoParamBrightness 

The  brightness  value  controls  the  overall  brightness  of  the  digitized  video 
image.  Brightness  values  range  from  0  to  65,535,  where  0  is  the  darkest  possible 
setting  and  65,535  is  the  lightest  possible  setting. 
kMedi aVideoParamContrast 

The  contrast  value  ranges  from  0  to  65,535,  where  0  represents  no  change  to  the 
basic  image  and  larger  values  increase  the  contrast  of  the  video  image  (that  is, 
increase  the  slope  of  the  transform). 
kMedi aVideoParamHue 

Hue  is  similar  to  the  tint  control  on  a  television.  It  is  specified  in  degrees  with 
complementary  colors  set  180  degrees  apart  (red  is  0  degrees,  green  is  +120 
degrees,  and  blue  is  -120  degrees).  QuickTime  supports  hue  values  that  range 
from  0  (-180  degrees  shift  in  hue)  to  65,535  (+179  degrees  shift  in  hue),  where 
32,767  represents  a  0  degrees  shift  in  hue. 

kMedi aVideoParamSharpness 

The  sharpness  value  ranges  from  0  to  65,535,  where  0  represents  no  sharpness 
filtering  and  65,535  represents  full  sharpness  filtering.  Higher  values  result  in  a 
visual  impression  of  increased  picture  sharpness 


11-868 


Inside  QuickTime:  Function  l-Q 


MediaGGetStatus 


kMedi aVideoParamSaturation 

The  saturation  value  controls  color  intensity.  For  example,  at  high  saturation 
levels,  red  appears  to  be  red;  at  low  saturation,  red  appears  pink.  Valid 
saturation  values  range  from  0  to  65,535,  where  0  is  the  minimum  saturation 
value  and  65,535  specifies  maximum  saturation. 

kMedi a Vi deoParamBl ackLevel 

Black  level  refers  to  the  degree  of  blackness  in  an  image.  The  highest  setting 
produces  an  all-black  image;  on  the  other  hand,  the  lowest  setting  yields  little, 
if  any,  black  even  with  black  objects  in  the  scene.  Black  level  values  range  from 
0  to  65,535,  where  0  represents  the  maximum  black  value  and  65,535  represents 
the  minimum  black  value. 

kMedi aVi deoParamWhi teLevel 

White  level  refers  to  the  degree  of  whiteness  in  an  image.  White  level  values 
range  from  0  to  65,535,  where  0  represents  the  minimum  white  value  and  65,535 
represents  the  maximum  white  value 

Discussion 

This  function  and  Medi  aSetVi  deoParam  (11-910)  are  currently  used  by  the  MPEG 
media  handler. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 

See  Also 

For  the  corresponding  set  function,  see  Medi  aSetVi  deoParam  (11-910). 


MediaGGetStatus 


Reports  error  conditions  to  the  Movie  Toolbox. 

ComponentResul t  MediaGGetStatus  ( 
MediaHandier  mh, 

ComponentResul t  *statusErr  ); 


The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 


Inside  QuickTime:  Function  l-Q 


11-869 


MediaGSetActiveSegment 


statusErr 

A  pointer  to  a  component  result  field.  If  you  have  error  information  that  you 
would  like  to  report  to  the  Movie  Toolbox,  place  an  appropriate  result  code  into 
the  field  referred  to  by  this  pointer.  See  "Error  Codes"  (IV-2663). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  derived  media  handler  should  support  this  function  if  you  anticipate  that  you 
may  encounter  an  error  when  playing  your  media.  Because  these  errors  may 
include  such  conditions  as  low  memory  or  missing  hardware,  you  should  only 
rarely  create  a  derived  media  handler  that  does  not  support  this  function.  If  your 
media  handler  does  not  support  this  function,  the  base  media  handler  always  sets 
the  returned  result  code  to  noErr. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "Managing  Your  Media  Handler  Component"  (V-2861) 


MediaGSetActiveSegment 


Informs  your  derived  media  handlers  of  the  current  active  segment. 

ComponentResult  MediaGSetActiveSegment  ( 

MediaHandler  mh. 

Time Value  activeStart, 

TimeValue  acti veDurati on  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

acti veStart 

The  starting  time  of  the  active  segment  to  play.  This  time  value  is  expressed  in 
your  movie's  time  scale, 
acti veDurati on 

A  time  value  that  specifies  the  duration  of  the  active  segment.  This  value  is 
expressed  in  the  movie's  time  scale. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


11-870 


Inside  QuickTime:  Function  l-Q 


MediaGSetVolume 


Discussion 

Using  SetMovi  eActi  veSegment  (III— 1609),  an  application  can  limit  the  time  segment 
of  the  movie  that  will  be  used  for  play  back.  Derived  media  handlers  are  given  the 
values  for  the  active  segment  when  this  function  is  called  by  the  Movie  Toolbox. 
Active  segment  information  is  usually  only  needed  by  media  handlers  that  perform 
their  own  scheduling. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 


MediaGSetVolume 


Specifies  changes  to  the  sound  volume  setting. 

ComponentResul t  MediaGSetVolume  ( 
MediaHandler  mh, 

short  volume  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

vol ume 

The  media's  current  volume  setting.  This  value  is  represented  as  a  16-bit, 
fixed-point  number.  The  high-order  8  bits  contain  the  integer  portion;  the 
low-order  8  bits  contain  the  fractional  part.  Volume  values  range  from  -1.0  to 
1.0.  Negative  values  play  no  sound  but  preserve  the  absolute  value  of  the 
volume  setting.  The  Movie  Toolbox  scales  your  media's  volume  in  light  of  the 
track's  and  movie's  volume  settings,  but  it  does  not  take  into  account  the 
system  speaker  volume  setting.  This  value  is  appropriate  for  use  with  the 
Sound  Manager. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  derived  media  handler  should  support  this  function  if  it  can  play  sounds. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Function  l-Q 


11-871 


MediaHasCharacteristic 


Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaHasCharacteristic 


Called  by  Movie  Toolbox  with  a  specified  character!  stic  to  allow  tracks  to  be 
identified  by  various  attributes. 

ComponentResul t  MediaHasCharacteristic  ( 

MediaHandler  mh, 

OSType  characteristic, 

Boolean  *haslt  ); 


mh 

The  Movie  Toolbox's  connection  to  your  derived  media  handler.  You  can 
obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 

characteri sti c 

A  constant  that  specifies  the  attribute  of  a  track.  Examples  of  characteristics  that 
are  currently  defined  are  the  constants  Visual  Medi  aCharacteri  sti  c  and 
Audi oMedi aCharacteri sti c. 

haslt 

A  pointer  toaBoolean  value  that  specifies  whether  the  track  has  the  attribute 
specified  in  the  characteri  stic  parameter.  Set  this  value  to  TRUE  if  the  attribute 
applies  to  your  media  handler;  otherwise,  set  this  value  to  FALSE. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  should  implement  this  function  for  any  media  handler  that  has  characteristics 
in  addition  to  spatial  ones.  If  you  have  set  the  handlerHasSpatial  capabilities  flag, 
the  base  media  handler  automatically  handles  the  VisualMedi  aCharacteri  stic 
constant  for  you. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 


11-872 


Inside  QuickTime:  Function  l-Q 


MediaHitTestForTargetRefCon 


MediaHitT  estForT  argetRef  Con 

Undocumented 

ComponentResul t  MediaHitTestForTargetRefCon  ( 

MediaHandler  mh, 
long  flags. 

Point  loc, 

long  *targetRefCon  ); 

mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMediaHandler  (1-432). 
fl  ags 

Flags  (see  below)  that  define  the  hit. 

1  oc 

Undocumented 

targetRefCon 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

mHi tTestBounds 

The  point  may  only  be  within  the  targetRefCon  bounding  box. 
mHi tTestlmage 

The  point  must  be  within  the  shape  of  the  targetRefCon  image. 
mHi tTestlnvi si bl e 

An  invisible  targetRefCon  may  be  hit  tested. 
mHi tTestlsCl i ck 

The  hit  is  a  mouse  click  (for  codecs  that  want  mouse  events). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaHitT  estT  argetRef  Con 

Undocumented 

ComponentResul t  Medi aHi tTestTargetRefCon  ( 


Inside  QuickTime:  Function  l-Q 


11-873 


Medialdle 


Medi aHandl er 
1  ong 
1  ong 
Poi  nt 
Bool ean 


mh , 

targetRefCon , 
fl ags , 

1  oc , 

*wasHit  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
targetRefCon 

Undocumented 
fl  ags 

Flags  (see  below)  that  define  the  hit. 

1  oc 

Undocumented 
wasHi t 

A  pointer  to  a  Bool  ean;  it  is  TRUE  if  there  was  a  hit,  FALSE  otherwise. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

mHi tTestBounds 

The  point  may  only  be  within  the  targetRefCon  bounding  box. 
mHi tTestlmage 

The  point  must  be  within  the  shape  of  the  targetRefCon  image. 
mHi tTestlnvi si bl e 

An  invisible  targetRefCon  maybe  hit  tested. 
mHi tTestlsCl i ck 

The  hit  is  a  mouse  click  (for  codecs  that  want  mouse  events). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


Medialdle 


Provides  processing  time  to  a  derived  media  handler  during  movie  playback. 

ComponentResul t  Medialdle  ( 

MediaHandler  mh, 

TimeVal ue  at Medi aTime , 


11-874 


Inside  QuickTime:  Function  l-Q 


Medialdle 


long  flagsln, 

long  *flagsOut, 

const  TimeRecord  *movieTi'me  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 
atMedi aTi me 

The  current  time,  in  your  media's  time  base.  You  can  use  this  value  to  obtain 
the  appropriate  samples  and  sample  descriptions  from  your  media  (using  the 
Movie  Toolbox's  GetMedi  aSampl  e  (1-443)  function).  Your  media  handler  may 
then  work  with  the  sample  data  and  descriptions  as  appropriate. 

fl agsln 

Contains  flags  (see  below)  that  indicate  what  the  Movie  Toolbox  wants  your 
media  handler  to  do.  These  flags  are  applicable  only  to  media  handlers  that 
perform  their  own  scheduling.  The  toolbox  may  use  none,  or  it  may  set  one  or 
more  flag  to  1.  Your  handler  should  examine  the  flagsln  parameter  each  time 
the  Movie  Toolbox  calls  its  Medi  a  Idl  e  function.  The  flags  in  this  parameter 
indicate  the  actions  that  your  handler  may  perform.  In  addition,  when  you 
return  f rom  your  M  e  d  i  a  I  d  1  e  function,  you  should  report  what  you  did  using  the 
f  1  agsOut  parameter.  You  tell  the  base  media  handler  that  you  perform  your 
own  scheduling  by  setting  the  handl  erNoSchedul  er  flag  to  1  in  the  f  1  ags 
parameter  of  the  Medi  aSetHandl  erCapabi  1  i  ti  es  (11-894)  function, 
f 1 agsOut 

Flags  (see  below)  that  are  contained  in  a  pointer  to  a  long  integer  that  your 
media  handler  uses  to  indicate  to  the  Movie  Toolbox  what  the  handler  did.  You 
must  always  set  the  values  of  these  flags  appropriately, 
movi eT i me 

A  pointer  to  the  movie  time  value  corresponding  to  the  atMedi  a  Time  parameter. 
Note  that  this  may  differ  from  the  current  value  returned  by  GetMovi  eT i  me 
(1-495). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flagsln  Constants 

mMustDraw 

Indicates  that  your  media  handler  must  play  its  media  at  this  time.  For 
graphical  media,  this  means  that  your  handler  must  draw  the  appropriate 
media  data  on  the  screen.  For  sound-based  media,  your  handler  must  play  the 
media's  sounds.  If  this  flag  is  set  to  1,  the  Movie  Toolbox  has  encountered  a  new 
sample  in  your  media. 


M 
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mAtEnd 

Indicates  that  the  current  time  corresponds  to  the  end  of  the  movie. 
mParti al Draw 

Indicates  that  only  a  portion  of  the  available  drawing  area  needs  to  be  redrawn. 
Whenever  you  set  this  flag  to  1,  the  Toolbox  calls  your  component's 
Medi  aGetDrawi  ngRgn  function  in  order  to  determine  the  portion  of  the  image  that 
needs  to  be  redrawn.  As  an  example,  consider  a  full-screen  animation.  Only 
rarely  is  the  entire  image  in  motion.  Typically,  only  a  small  portion  of  the  screen 
image  moves.  By  using  partial  redrawing,  you  can  significantly  improve  the 
playback  performance  of  such  a  movie. 

mPref 1 i ghtDraw 

Indicates  that  your  media  handler  must  not  play  its  media  at  this  time.  Your 
handler  may  examine  the  media  data  and  prepare  to  play  it,  but  you  should  not 
draw  any  graphical  data  or  play  any  sounds.  If  this  flag  is  set  to  1,  your  handler 
must  not  play  its  data.  If  these  flags  are  set  to  0,  then  your  media  handler  is  free 
to  decide  whether  to  play  the  media  data  or  not. 

flagsOut  Constants 

mDi  dDraw 

Indicates  that  your  media  handler  played  its  media's  data  with  the 
handlerHasSpatial  flag  set,  then  it  drew  the  data.  Any  time  your  media  handler 
plays  its  media's  data,  you  should  set  this  flag  to  1  when  you  return  from  your 
Medialdle  function.  The  Movie  Toolbox  uses  this  information  when  it  is 
displaying  a  composited  movie;  that  is,  a  movie  whose  image  is  derived  by 
blending  several  tracks  together.  If  your  media's  track  is  obscured  by  other, 
semitransparent  tracks,  the  Movie  Toolbox  must  redraw  those  other  tracks 
whenever  your  media's  image  changes. 
mNeedsToDraw 

Indicates  that  your  media  handler  needs  to  play  its  data.  Typically,  you  use  this 
flag  when  the  Movie  Toolbox  calls  your  Medialdle  function  with  the 
mPrefli  ghtDraw  flag  in  the  f  1  agsln  field  set  to  1,  and  you  discover  that  you  have 
data  that  must  be  played  at  the  current  time.  Set  this  flag  to  1  if  your  handler 
needs  to  play  its  media's  data. 

Discussion 

From  time  to  time,  your  derived  media  handler  component  may  determine  that 
only  a  portion  of  the  available  drawing  area  needs  to  be  redrawn.  You  can  signal 
that  condition  to  the  base  media  handler  component  by  setting  the  mParti  al  Draw 
flag  to  1  in  the  flags  your  component  returns  to  the  Movie  Toolbox  from  your 
Medialdle  function.  You  return  these  flags  using  the  fl  agsOut  parameter.  Whenever 
you  set  this  flag  to  1,  the  Movie  Toolbox  calls  your  component's  Medi  aGetDrawi  ngRgn 
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(11-849)  function  in  order  to  determine  the  portion  of  the  image  that  needs  to  be 
redrawn. 

As  an  example,  consider  a  full-screen  animation.  Only  rarely  is  the  entire  image  in 
motion.  Typically,  only  a  small  portion  of  the  screen  image  moves.  By  using  partial 
redrawing,  you  can  significantly  improve  the  playback  performance  of  such  a 
movie. 

Your  derived  media  handler  should  support  this  function  if  you  need  to  do  work 
during  movie  playback.  If  you  set  the  handlerNoIdle  flag  to  1  in  the  fl  ags  parameter 
of  Medi  aSetHandl  erCapabi  1  i  ti  es  (11-894),  the  Movie  Toolbox  does  not  call  your 
Medi  a  Idl  e  function.  If  you  encounter  an  error,  save  the  result  code.  The  Movie 
Toolbox  polls  you  for  status  information  using  Medi  aGGetStatus  (11-869). 

Special  Considerations 

If  your  media  handler  changes  any  of  the  settings  of  the  movie's  graphics  port  or 
graphics  world,  be  sure  to  restore  the  original  settings  before  you  exit.  In  addition, 
note  that  you  may  be  drawing  into  a  black-and-white  graphics  port.  Finally,  be 
aware  that  the  Movie  Toolbox  also  uses  this  function  to  obtain  data  for  QuickDraw 
pictures.  Therefore,  if  your  media  handler  does  not  use  QuickDraw  when  drawing 
to  the  screen,  be  sure  to  examine  the  pi cSave  field  in  the  graphics  port  so  that  you 
can  detect  when  the  Movie  Toolbox  wants  to  save  an  image.  Your  media  handler  is 
then  responsible  for  performing  the  appropriate  display  processing. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "Managing  Your  Media  Handler  Component"  (V-2861) 

See  Also 

For  more  information,  see  also  Medialnval  i dateRegi  on  (11-879)  and 
Medi  aGetDrawi  ngRgn  (11-849). 


Medialnitialize 


Prepares  a  derived  media  handler  component  to  provide  access  to  its  media. 

ComponentResul t  Medialnitialize  ( 

MediaHandler  mh, 

GetMovi eCompl eteParams  *gmc  ); 
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mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

gmc 

A  pointer  to  a  GetMovi  eCompl  eteParams  (IV-2268)  structure.  You  can  obtain 
information  about  the  current  media  from  this  structure.  You  should  copy  any 
values  you  need  to  save  into  your  derived  media  handler's  local  data  area. 
Because  this  data  structure  is  owned  by  the  Movie  Toolbox,  you  do  not  need  to 
worry  about  disposing  of  any  of  the  data  in  it. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error.  If  you 
return  an  error,  the  Movie  Toolbox  disables  the  track  that  uses  your 
media.  In  cases  where  your  media  has  just  been  created,  the  Movie 
Toolbox  immediately  disposes  of  your  media. 

Discussion 

This  function  gives  your  media  handler  an  opportunity  to  get  ready  to  support  the 
Movie  Toolbox.  As  part  of  these  preparations,  your  derived  media  handler  should 
report  its  capabilities  to  the  base  media  handler  by  calling 

Medi  aSetHandl  erCapabi  1  i  ti  es  (11-894).  You  may  choose  to  examine  the  data  in  the 
GetMovi  eCompl  eteParams  (IV-2268)  structure;  you  may  also  save  values  from  this 
structure.  If  you  save  references  to  structures  (such  as  the  matte  pixel  map),  do  not 
dispose  of  the  memory  associated  with  these  structures.  The  Movie  Toolbox  owns 
these  structures. 

Note  that  the  Movie  Toolbox  may  call  other  functions  supported  by  your  media 
handler  before  it  calls  your  Medialnitialize  function.  In  particular,  it  may  call  your 
MediaGetMedialnfo  (11-853)  and  MediaPutMedialnfo  (11-884)  functions.  However, 
before  the  Movie  Toolbox  tries  to  do  anything  with  the  data  in  your  media,  it  will 
call  your  Medi  alni  tial  i  ze  function.  The  Movie  Toolbox  loads  the  movie's  data 
using  functions  that  are  supported  by  the  base  media  handler;  your  media  handler 
does  not  have  to  support  those  functions. 

Special  Considerations 

All  derived  media  handlers  should  support  this  function.  In  addition,  if  your  media 
handler  saves  values  from  the  GetMovi  eCompl  eteParams  (IV-2268)  structure  that  may 
change,  be  sure  to  support  the  corresponding  functions  that  allow  the  Movie 
Toolbox  to  report  changes  to  your  media  handler.  For  example,  if  your  handler 
saves  the  movie  time  scale  from  the  movi  eScal  e  field,  you  should  also  support  the 
MediaSetMovieTimeScale  (11-899)  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "Managing  Your  Media  Handler  Component"  (V-2861) 


MedialnvalidateRegion 


Updates  the  invalidated  display  region  the  next  time  Medi  a  Idl  e  is  called. 

ComponentResul t  MedialnvalidateRegion  ( 

MediaHandler  mh, 

RgnHandle  invalRgn  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 
i nval Rgn 

A  handle  to  a  region  that  has  been  invalidated.  Your  media  handler  should  not 
dispose  or  modify  this  region.  The  i nval  Rgn  parameter  is  never  NIL. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  called  by  the  Movie  Toolbox  when  UpdateMovi  e  (III— 1981)  or 
InvalidateMovieRegion  (11-771)  is  called  with  a  region  that  intersects  your  media's 
track.  Derived  media  handlers  need  to  implement  Medi  a  I  nval  i  dateRegi  on  only  if 
they  can  perform  efficient  updates  on  a  portion  of  their  display  area. 

If  a  media  handler  implements  this  function,  it  is  responsible  for  ensuring  that  the 
appropriate  areas  of  the  screen  are  updated  on  the  next  call  to  Medialdle  (11-874).  If 
a  media  handler  does  not  implement  this  function,  the  base  media  handler  sets  the 
mMustDraw  flag  the  next  time  Medi  a  Idl  e  is  called. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers  .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 


MediaMakeMediaT  imeT  able 


Called  by  the  base  media  handler  to  create  a  media  time  table. 
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MediaMakeMediaTimeTable 


Component Res ul t  Medi aMakeMedi aTi meTabl e 


Medi aHandl er 
1  ong 

TimeVal ue 
TimeVal ue 
TimeVal ue 
short 
short 
1  ong 


mh , 

**offsets , 

startTime, 

endT i me , 

ti melncrement , 

f i rst Data  Ref Index , 

1 astDataRef Index , 

*retDataRefSkew  ) ; 


( 


mh 

The  media  handler  to  create  the  time  table.  You  can  obtain  this  reference  from 
GetMedi  aHandl  er  (1-432). 
offsets 

A  handle  to  an  unlocked  relocatable  memory  block  that  is  allocated  by  an 
application  or  other  software  when  it  calls  QTMovi  eNeedsT  1  meTabl  e  (11-1202), 
GetMaxLoadedTimelnMovie  (I — 423),  MakeTrackTimeTable  (11-793),  or 
Ma  keMedi  aT i  meTabl  e  (11-788).  Your  derived  media  handler  returns  the  time  table 
for  the  media  in  this  block.  Your  media  handler  has  to  resize  the  handle. 

startTime 

The  first  point  of  the  media  to  be  included  in  the  time  table.  This  time  value  is 
expressed  in  the  media's  time  coordinate  system. 
endT i me 

The  last  point  of  the  media  to  be  included  in  the  time  table.  This  time  value  is 
expressed  in  the  media's  time  coordinate  system, 
ti melncrement 

The  resolution  of  the  time  table.  The  values  in  a  time  table  are  for  a  points  in  the 
media,  and  these  points  are  separated  by  the  amount  of  time  specified  by  this 
parameter.  The  time  value  is  expressed  in  the  media's  time  coordinate  system. 

f i rstDataRef Index 

The  first  in  the  range  of  data  reference  indexes  you  are  querying. 

1 astDataRef Index 

The  last  in  the  range  of  data  reference  indexes  you  are  querying. 
retDataRefSkew 

A  pointer  to  the  number  of  entries,  i.e.,  the  number  of  entries  in  the  offset  table 
per  data  reference. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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Discussion 

The  Movie  Toolbox  calls  your  derived  media  handler's  Medi  aMakeMedi  aT i  meTabl  e 
function  whenever  an  application  or  other  software  calls  the  Toolbox's 
QTMovi  eNeedsTi meTabl  e  (11-1202),  GetMaxLoadedTimelnMovi  e  (1-423), 

MakeT rackTi meTabl  e  (11-793),  or  MakeMedi  aT i meTabl  e  (11-788)  function.  When  an 
application  or  other  software  calls  one  of  these  functions,  it  allocates  an  unlocked 
relocatable  memory  block  for  the  time  table  to  be  returned  and  passes  a  handle  to  it 
in  the  offsets  parameter.  Your  derived  media  handler  must  resize  the  block  to 
accommodate  the  time  table  it  returns. 

The  time  table  your  derived  media  handler  returns  is  a  two-dimensional  array  of 
long  integers  that  is  organized  so  that  each  row  in  the  table  contains  values  for  one 
data  reference.  The  first  column  in  the  table  contains  values  for  the  time  in  the  media 
specified  by  the  sta  rtT i  me  parameter,  and  each  subsequent  column  contains  values 
for  the  point  in  the  media  that  is  later  by  the  value  specified  by  the  time  I  increment 
parameter.  Each  long  integer  value  in  the  table  specifies  the  offset,  in  bytes,  from  the 
beginning  of  the  data  reference  for  that  point  in  the  media. 

Special  Considerations 

The  number  of  columns  in  the  table  returned  by  your  derived  media  handler  must 
beequalto  (endTime  -  startTime)  /  timelncrement,  rounded  up.  Itmustalso  return 
the  offset  to  the  next  row  of  the  time  table,  in  long  integers,  in  the  retdata  Ref  Skew 
parameter.  Because  of  alignment  issues,  this  value  is  not  always  equal  to  (endTime 
-  startTime)  /  timelncrement  rounded  up. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "Making  a  Progressive  Download  Time  Table"  (V-2866) 


MediaMCIsPlayerEvent 


Undocumented 

ComponentResul t  MediaMCIsPlayerEvent  ( 
MediaHandler  mh, 

const  EventRecord  *e. 

Boolean  *handledlt  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
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e 

A  pointer  to  an  Event  Re  cord  (IV-2246)  structure, 
handl edit 

A  pointer  to  a  Bool  ean;  it  is  TRUE  if  the  event  was  handled,  FALSE  otherwise. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaPrePrerollBegin 


Undocumented 

ComponentResul t  MediaPrePrerollBegin  ( 

MediaHandler  mh, 

T imeVal ue  time , 

Fixed  rate, 

PrePreroll Compl eteUPP  compl eteProc , 
voi  d  *refcon  ) ; 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 

time 

Undocumented 

rate 

Undocumented 
compl eteProc 

A  PrePrerol  1  Compl  eteProc  (III — 2111)  callback, 
refcon 

A  reference  constant  to  be  passed  to  your  callback.  Use  this  parameter  to  point 
to  a  data  structure  containing  any  information  your  function  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 
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MediaPrePrerollCancel 


Cancels  a  media  handler  pre-preroll  operation  that  was  started  by 
Medi  aPrePrerol  1  Begi  n  (11-882). 

ComponentResul t  MediaPrePrerollCancel  ( 

MediaHandler  mh, 

void  *refcon  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
ref con 

The  reference  constant  that  was  passed  to  your  PrePreroll  Compl  eteProc 
(III— 2111)  callback. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaPreroll 


Prepares  a  media  handler  for  playback. 

ComponentResul t  MediaPreroll  ( 
MediaHandler  mh, 

TimeValue  time. 

Fixed  rate  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

ti  me 

The  starting  time  of  the  media  segment  to  play.  This  time  value  is  expressed  in 
your  media's  time  scale. 

rate 

The  rate  at  which  the  Movie  Toolbox  expects  to  play  the  media.  This  is  a  32-bit, 
fixed-point  number.  Positive  values  indicate  forward  rates;  negative  values 
correspond  to  reverse  rates. 
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MediaPutMedialnfo 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 


MediaPutMedialnfo 


Lets  a  derived  media  handler  store  proprietary  information  in  its  media. 

ComponentResul t  MediaPutMedialnfo  ( 

MediaHandler  mh, 

Handl e  h  ) ; 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

h 

A  handle  to  storage  into  which  your  media  handler  may  place  its  proprietary 
information.  You  determine  the  format  and  content  of  the  data  that  you  store  in 
this  handle.  Your  media  handler  must  resize  the  handle  as  appropriate  before 
you  exit  this  function.  Do  not  dispose  of  this  handle;  it  is  owned  by  the  Movie 
Toolbox.  The  Movie  Toolbox  uses  the  base  media  handler  to  write  this  data  to 
your  media. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Whenever  the  Movie  Toolbox  opens  your  media,  it  provides  this  private  data  to 
your  media  handler  by  calling  your  Medi  aGetMedi  a  Info  (11-853)  function.  Note  that 
the  Movie  Toolbox  may  call  this  function  before  it  calls  your  Medi  a  Ini  ti  al  i  ze 
(11-877)  function.  Your  derived  media  handler  should  support  this  function  if  you 
need  to  store  private  data  in  your  media. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 
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MediaQueueN  onPrimarySourceData 


MediaQueueNonPrimarySourceData 


Undocumented 


ComponentResul t  MediaQueueNonPrimarySourceData  ( 


Medi aHandl er 
1  ong 
1  ong 
Handl e 
voi  d 
1  ong 

ICMCompl eti onProcRecordPtr 
const  ICMFrameTimeRecord 
Uni versal ProcPtr 
voi  d 


mh , 

i nputlndex, 
dataDescri pti on Seed  , 
dataDescri pti  on , 
*data , 
dataSi ze , 

asyncCompi eti on P roc , 
*f rameT i me , 
transferProc , 

*refCon  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
i nputlndex 

The  ID  of  the  entry  in  the  media's  input  map  to  which  the  queued  data 
corresponds. 
dataDescri pti on Seed 
Undocumented 
dataDescri pti  on 
Undocumented 

data 

Undocumented 
dataSi ze 

Undocumented 
asyncCompi eti onProc 

A  pointer  to  an  ICMCompl  eti  onProcRecord  (IV-2279)  structure, 
f rameT i me 

A  pointer  to  an  ICMFrameTimeRecord  (IV-2281)  structure. 
transferProc 

Undocumented 

refCon 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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MediaReleaseSampleDataPointer 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaReleaseSampleDataPointer 


Balances  calls  to  Medi  aGetSampl  eDataPoi  nter  (11-859)  to  release  allocated  memory. 

ComponentResul t  MediaReleaseSampleDataPointer  ( 

MediaHandler  mh, 

1 ong  sampl eNum  ) ; 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

sampl eNum 

The  number  of  the  sample  that  is  to  be  released. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  should  be  used  only  by  derived  media  handlers. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 


MediaResolveT  argetRef  Con 


Undocumented 

ComponentResul t  MediaResol veTargetRefCon  ( 
MediaHandler  mh, 

QTAtomContai ner  container, 

QTAtom  atom, 

long  *targetRefCon  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
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MediaSampleDescriptionB2N 


contai ner 

Undocumented 

atom 

Undocumented 

targetRefCon 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaSampleDescriptionB2N 


Undocumented 

ComponentResul t  Medi aSampl eDescri pti onB2N  ( 
MediaHandler  mh, 

Sampi eDescri pti onHandl e  sampl eDescri pti onH  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
sampl eDescri pti onH 

A  handle  to  a  Sampl  eDescri  pti  on  (IV-2414)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaSampleDescriptionChanged 

Informs  a  media  handler  that  SetMedi  aSampl  eDescri  pti  on  (III— 1606)  has  been  called 
for  a  specified  sample  description. 

ComponentResul t  MediaSampleDescriptionChanged  ( 

MediaHandler  mh. 


Inside  QuickTime:  Function  l-Q 


11-887 


MediaSampleDescriptionN2B 


1  ong 


i ndex  ) ; 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

i  ndex 

The  index  of  the  sample  description  that  has  been  changed. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 


MediaSampleDescriptionN2B 


Undocumented 

ComponentResul t  Medi aSampl eDescri pti onN2B  ( 
MediaHandler  mh, 

Sampl eDescri pti onHandl e  sampl eDescri pti onH  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
sampl eDescri pti onH 
Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaSetActionsCallback 

Sets  an  Acti  onsProc  (III— 2075)  callback  for  a  media  handler. 
ComponentResul t  MediaSetActionsCallback  ( 


11-888 


Inside  QuickTime:  Function  l-Q 


MediaSetActive 


Medi aHandl er 
Acti onsUPP 
voi  d 


mh , 

actionsCallbackProc, 
*refcon  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
actionsCallbackProc 

A  Universal  Procedure  Pointer  to  an  Acti  onsProc  (III— 2075)  callback, 
ref con 

A  pointer  to  a  reference  constant  to  be  passed  to  your  callback.  Use  this  constant 
to  point  to  a  data  structure  containing  any  information  your  function  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers  .  h 


MediaSetActive 


Enables  and  disables  media. 

ComponentResul t  MediaSetActive  ( 
MediaHandler  mh. 

Boolean  enableMedia  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

enabl eMedi a 

A  Bool  ean  value  that  indicates  whether  your  media  is  enabled  or  disabled.  If 
this  parameter  is  set  to  TRUE,  your  media  is  enabled;  if  the  parameter  is  FALSE, 
your  media  is  disabled. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  derived  media  handler  should  support  this  function  if  you  perform  your  own 
scheduling  or  if  your  media  handler  uses  significant  amounts  of  temporary  storage. 
If  you  are  doing  your  own  scheduling  (that  is,  you  have  set  the  handlerNoScheduler 
flag  to  1  in  the  f  1  ags  parameter  of  the  Medi  aSetHandl  erCapabi  1  i  ti  es  (11-894) 


Inside  QuickTime:  Function  l-Q 


11-889 


MediaSetClip 


function),  your  media  handler  needs  to  keep  account  of  the  media's  active  state  so 
that  you  can  properly  respond  to  Movie  Toolbox  requests.  When  your  media  is 
disabled,  you  may  choose  to  dispose  of  temporary  storage  you  have  allocated,  so 
that  the  storage  is  available  to  other  programs. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 


MediaSetClip 


Specifies  changes  to  a  derived  media  handler's  clipping  region. 

ComponentResul t  MediaSetClip  ( 

MediaHandler  mh, 

RgnHandl e  theCl ip  ) ; 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

theCl i p 

A  handle  to  your  media's  clipping  region.  Your  media  handler  is  responsible 
for  disposing  of  this  region  when  you  are  done  with  it.  Note  that  this  region  is 
defined  in  the  movie's  coordinate  system. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  derived  media  handler  should  support  this  function  if  you  draw  during 
playback.  The  Movie  Toolbox  calls  this  function  only  if  you  have  set  the 
handl  erHasSpati  al  and  handl  erCanCl  i  p  flags  to  1  in  the  f  1  ags  parameter  of  the 
Medi aSetHandl  erCapabi  1  i  ti es  (11-894)  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "Managing  Graphics  Data"  (V-2864) 


11-890 


Inside  QuickTime:  Function  l-Q 


MediaSetDimensions 


MediaSetDimensions 


Informs  a  media  handler  when  its  media's  spatial  dimensions  change. 

ComponentResul t  MediaSetDimensions  ( 

MediaHandier  mh. 

Fixed  width. 

Fixed  height  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 
wi  dth 

The  width,  in  pixels,  of  the  track  rectangle.  This  field,  along  with  the  height 
field,  specifies  a  rectangle  that  surrounds  the  image  that  is  displayed  when  the 
current  media  is  played.  This  value  corresponds  to  the  x  coordinate  of  the 
lower-right  corner  of  the  rectangle  and  is  expressed  as  a  fixed-point  number, 
hei ght 

The  height,  in  pixels,  of  the  track  rectangle.  This  value  corresponds  to  the  y 
coordinate  of  the  lower-right  comer  of  the  rectangle  and  is  expressed  as  a 
fixed-point  number. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  obtain  the  initial  dimension  information  from  the  width  and  height  fields  of  the 
GetMovi  eCompl  eteParams  (IV-2268)  structure  that  the  Movie  Toolbox  provides  to 
your  Medi  a  Ini  ti  al  i  ze  (11-877)  function.  Your  derived  media  handler  should 
support  this  function  if  you  draw  during  playback. 

Special  Considerations 

The  Movie  Toolbox  calls  this  function  only  if  you  have  set  the  handlerHasSpatial 
flag  to  1  in  the  f  1  ags  parameter  of  the  Medi  aSetHandl  erCapabi  1  i  ti  es  (11-894) 
function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "Managing  Graphics  Data"  (V-2864) 


Inside  QuickTime:  Function  l-Q 


11-891 


MediaSetDoMCActionCallback 


MediaSetDoMCActionCallback 


Sets  a  DoMCActi  onProc  (III— 2082)  callback  for  a  media  handler. 

ComponentResul t  MediaSetDoMCActionCallback  ( 

MediaHandler  mh, 

DoMCActi onUPP  doMCActi onCallbackProc, 

voi d  *refcon  ) ; 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
doMCActi onCallbackProc 

A  Universal  Procedure  Pointer  to  a  DoMCActi  onProc  (III— 2082)  callback, 
refcon 

A  pointer  to  a  reference  constant  to  be  passed  to  your  callback.  Use  this  constant 
to  point  to  a  data  structure  containing  any  information  your  callback  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaSetGraphicsMode 


Sets  the  graphics  mode  and  blend  color  of  any  media  handler. 

ComponentResul t  MediaSetGraphicsMode  ( 

MediaHandler  mh, 

long  mode, 

const  RGBColor  *opColor  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

mode 

The  graphics  mode  of  the  media  handler;  see  "Graphics  Transfer  Modes" 
(IV-2670). 


11-892 


Inside  QuickTime:  Function  l-Q 


MediaSetGWorld 


opCol or 

A  pointer  to  the  color  for  use  in  blending  and  transparent  operations.  The 
media  handler  passes  this  color  to  QuickDraw  as  appropriate  when  you  draw 
in  addP in,  subPin,  blend,  transparent,  orgraphicsModeStraightAlphaBlend 
mode. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers  .  h 

Programming  summary:  "Managing  Graphics  Data"  (V-2864),  "Video  Media 
Handler  Functions"  (V-2755) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Vi sual Medi aHandl er . setGraphi cs Model ) 


See  Also 

You  can  retrieve  the  graphics  mode  and  blend  color  currently  in  use  by  any  media 
handler  by  calling  Medi  aGetGraphi  csMode  (11-852). 


MediaSetGWorld 


Lets  a  derived  media  handler  learn  about  changes  to  its  media's  graphic 
environment. 

ComponentResul t  MediaSetGWorld  ( 

MediaHandler  mh, 

CGrafPtr  aPort, 

GDHandl e  aGD  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 
aPort 

A  pointer  to  the  new  graphics  port.  Note  that  this  may  be  either  a  color  or  a 
black-and-white  port. 

aGD 

A  handle  to  the  new  graphics  device. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Inside  QuickTime:  Function  l-Q 


11-893 


MediaSetHandlerCapabilities 


Discussion 

Your  derived  media  handler  should  support  this  function  if  you  perform 
specialized  graphics  processing  or  if  you  are  using  the  Image  Compression 
Manager  to  decompress  your  media.  Note  that  when  the  Movie  Toolbox  calls  your 
Medi  aldl  e  (11-874)  function,  it  supplies  you  with  information  about  the  current 
graphics  environment.  Consequently,  you  do  not  need  to  support  the 
MediaSetGWorld  function  in  order  to  draw  during  playback.  However,  if  your  media 
data  is  compressed  and  you  are  using  the  Image  Compression  Manager  to 
decompress  sequences,  you  may  need  to  provide  updated  graphics  environment 
information  before  playback. 

You  obtain  the  initial  graphics  environment  information  from  the  movi  ePort  and 
movi  eGD  fields  of  the  GetMovi  eCompl  eteParams  (IV-2268)  structure  that  the  Movie 
Toolbox  provides  to  your  Medialnitialize  (11-877)  function.  The  Movie  Toolbox 
calls  this  function  only  if  you  have  set  the  handl  erHasSpati  al  flag  to  1  in  the  fl  ags 
parameter  of  the  Medi  aSetHandl  erCapabi  1  i  ti  es  (11-894)  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "Managing  Graphics  Data"  (V-2864) 


MediaSetHandlerCapabilities 


Lets  a  derived  media  handler  report  its  capabilities  to  the  base  media  handler. 

ComponentResul t  MediaSetHandlerCapabilities  ( 

MediaHandler  mh, 

long  flags, 

1 ong  f 1 agsMask  ) ; 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
fl  ags 

Flags  (see  below)  that  specify  the  capabilities  of  your  derived  media  handler. 
This  parameter  contains  a  number  of  flags,  each  of  which  corresponds  to  a 
particular  feature.  You  may  work  with  more  than  one  flag  at  a  time.  Be  sure  to 
set  unused  flags  to  0. 


11-894 


Inside  QuickTime:  Function  l-Q 


MediaSetHandlerCapabilities 


fl agsMask 

Indicates  which  flags  in  the  flags  parameter  are  to  be  considered  in  this 
operation.  For  each  bit  in  the  flags  parameter  that  you  want  the  base  media 
handler  to  consider,  you  must  set  the  corresponding  bit  in  the  fl  agsMask 
parameter  to  1.  Set  unused  flags  to  0.  This  allows  you  to  work  with  a  single  flag 
without  altering  the  settings  of  other  flags. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

handl erHasSpati al 

Indicates  that  your  handler  does  spatial  processing.  If  you  set  this  flag  to  1,  the 
Movie  Toolbox  informs  your  derived  media  handler  about  changes  to  the 
graphics  environment  or  spatial  representation  of  your  media. 

handl erCanCl i p 

Indicates  that  your  media  handler  can  perform  clipping.  If  you  set  this  flag  to 
1,  the  Movie  Toolbox  calls  your  Medi  aSetCl  i  p  (11-890)  function  whenever  the 
clipping  region  changes, 
handl erCanMatte 

Reserved  for  Apple.  Do  not  set  this  flag  to  1. 
handl erCanTransferMode 

Indicates  that  you  can  work  with  transfer  modes  other  than  source  copy  or 
dither  copy.  If  you  set  this  flag  to  1,  the  Movie  Toolbox  calls  your 
Medi  aGetT rackOpaque  (11-865)  function  to  determine  whether  your  track  is 
transparent. 

handl erNeedsBuffer 

Indicates  that  your  media  handler  needs  help  during  playback.  If  you  set  this 
flag  to  1,  the  base  media  handler  allocates  an  offscreen  buffer  and  handles  all 
display  transformations  for  you. 
handl erNoIdl e 

Indicates  that  your  derived  media  handler  does  not  need  any  processing  time 
during  playback.  If  you  set  this  flag  to  1,  the  Movie  Toolbox  never  calls  your 
Medi  a  I  dl  e  (11-874)  function.  This  is  useful  for  media  handlers  that  store  data  in 
a  media,  but  do  not  play  that  data, 
handl erNoScheduler 

Indicates  that  your  media  handler  performs  special  processing  during 
playback.  Normally,  the  Movie  Toolbox  calls  your  Medi  aldl  e  (11-874)  function 
only  when  it  is  time  for  your  handler  to  draw  data  from  a  new  media  sample. 
If  you  set  this  flag  to  1,  the  Movie  Toolbox  calls  that  function  other  times  as  well. 


M 


Inside  QuickTime:  Function  l-Q 


11-895 


MediaSetHints 


so  that  your  media  handler  can  prepare  for  playback  or  perform  other 
necessary  processing, 
handl erWantsT i me 

Indicates  that  your  media  handler  needs  additional  processing  time.  If  you  set 
this  flag  to  1,  the  Movie  Toolbox  calls  your  Medialdl  e  (11-874)  function  as  often 
as  possible, 
handl erCGrafPortOnly 

Indicates  that  your  media  handler  can  only  draw  into  color  graphics  ports.  If 
you  set  this  flag  to  1,  the  base  media  handler  performs  the  necessary  processing 
to  display  your  color  media  on  a  black-and-white  graphics  port.  This  involves 
drawing  to  an  offscreen  buffer  and  then  transferring  the  image  to  the  screen. 

Discussion 

Your  media  handler  may  call  this  function  at  any  time.  In  general,  you  should  call 
it  from  your  Medi  a  Ini  ti  al  i  ze  (11-877)  function ,  so  that  you  report  your  capabilities 
to  the  base  media  handler  before  the  Movie  Toolbox  starts  working  with  your 
media.  You  may  call  this  function  again  later,  in  response  to  changing  conditions. 
For  example,  if  your  media  handler  receives  a  matrix  that  it  cannot  accommodate 
from  the  Medi  aSetMatri  x  (11-897)  function,  you  can  allow  the  base  media  handler  to 
handle  your  drawing  by  calling  this  function  and  setting  the  handl  erNeedsBuffer 
flag  in  both  the  fl  ags  parameter  and  the  flagsMask  parameter  to  1. 

Special  Considerations 

Note  that  this  function  is  provided  by  the  base  media  handler;  your  media  handler 
does  not  support  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "Reporting  Capabilities  to  the  Base  Media  Handler" 
(V-2866) 

MediaSetHints 


Implements  the  appropriate  behavior  for  the  various  media  hints  such  as  scrub 
mode  and  high-quality  mode. 

ComponentResul t  MediaSetHints  ( 

MediaHandler  mh, 

1 ong  hi nts  ) ; 


11-896 


Inside  QuickTime:  Function  l-Q 


MediaSetMatrix 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 
hi  nts 

All  hint  bits  that  currently  apply  to  the  given  media. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

When  an  application  calls  SetMovi  ePl  ayHi  nts  (III— 1623)  or  SetMedi  aPl  ayHi  nts 
(III— 1601),  your  media  handler's  Medi  aSetHi  nts  routine  is  called. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 


MediaSetMatrix 


Tells  a  media  handler  about  changes  to  either  the  movie  matrix  or  the  track  matrix. 

ComponentResul t  MediaSetMatrix  ( 

MediaHandler  mh, 

MatrixRecord  *trackMovi eMatrix  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

trackMovi eMatri x 

A  pointer  to  the  matrix  that  transforms  your  media's  pixels  into  the  movie's 
coordinate  system.  The  Movie  Toolbox  obtains  this  matrix  by  concatenating  the 
track  matrix  and  the  movie  matrix.  You  should  use  this  matrix  whenever  you 
are  displaying  graphical  data  from  your  media. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  obtain  the  initial  matrix  from  the  trackMovi  eMatri  x  field  of  the 
GetMovi  eCompl  eteParams  (IV-2268)  structure  that  the  Movie  Toolbox  provides  to 
your  Medi  a  Ini  ti  al  i  ze  (11-877)  function.  Your  derived  media  handler  should 
support  this  function  if  you  draw  during  playback. 


Inside  QuickTime:  Function  l-Q 


11-897 


MediaSetMediaTimeScale 


Special  Considerations 

The  Movie  Toolbox  calls  this  function  only  if  you  have  set  the  handlerHasSpatial 
flag  to  1  in  the  f  1  ags  parameter  of  the  Medi  aSetHandl  erCapabi  1  i  ti  es  (11-894) 
function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "Managing  Graphics  Data"  (V-2864) 


MediaSetMediaTimeScale 


Informs  a  media  handler  that  its  media's  time  scale  has  been  changed. 

ComponentResul t  MediaSetMediaTimeScale  ( 

MediaHandler  mh, 

TimeScale  newTimeScale  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

newT i meScal e 

Specifies  your  media's  new  time  scale. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  obtain  the  initial  media  time  scale  information  from  the  medi  aScal  e  field  of  the 
GetMovi  eCompl  eteParams  (IV-2268)  structure  that  the  Movie  Toolbox  provides  to 
your  Medialnitialize  (11-877)  function. 

Special  Considerations 

Your  derived  media  handler  should  support  this  function  if  your  media  handler 
stores  time  information  that  pertains  to  its  media. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 


11-898 


Inside  QuickTime:  Function  l-Q 


MediaSetMovieTimeScale 


MediaSetMovieTimeScale 


Informs  a  media  handler  that  the  movie's  time  scale  has  been  changed. 

ComponentResul t  MediaSetMovieTimeScale  ( 

MediaHandler  mh, 

TimeScale  newTimeScale  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

newT i meScal e 

The  movie's  new  time  scale. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  obtain  the  initial  movie  time  scale  information  from  the  movieScale  field  of  the 
GetMovi  eCompl  eteParams  (IV-2268)  structure  that  the  Movie  Toolbox  provides  to 
your  Medi  a  Ini  ti  al  i  ze  (11-877)  function. 

Special  Considerations 

Your  derived  media  handler  should  support  this  function  if  your  media  handler 
stores  time  information  in  the  movie's  time  coordinate  system. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 


MediaSetN  onPrimary  SourceData 


Allows  a  media  handler  to  support  receiving  media  data  from  other  media 
handlers. 


ComponentResul t  MediaSetNonPrimarySourceData  ( 


Medi aHandl er 
1  ong 
1  ong 
Handl e 
voi  d 
1  ong 

ICMCompl eti onProcRecordPtr 


mh , 

i nputlndex, 
dataDescri pti on Seed  , 
dataDescri pti on , 
*data , 
dataSi ze , 

a syn eCompl eti on P roc , 
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Uni versal ProcPtr  transferProc , 

voi d  *refCon  ) ; 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 
i nputlndex 

This  value  is  the  ID  of  the  entry  in  the  media's  input  map  to  which  the  data 
provided  by  the  call  corresponds. 

dataDescri pti onSeed 

This  value  is  changed  each  time  the  dataDescri  pti  on  has  changed.  This  allows 
for  a  quick  check  by  the  media  handler  to  see  if  the  dataDescri  pti  on  has 
changed. 

dataDescri pti on 

A  handle  to  a  data  structure  describing  the  input  data. 

data 

A  pointer  to  the  input  data.  This  pointer  must  contain  a  32-bit  address. 
dataSi ze 

The  size  of  the  sample  in  bytes. 
asyncCompl etionProc 

A  pointer  to  a  ICMCompl  eti  onProcRecord  (IV-2279)  structure.  If 
asyncCompl  eti  on  P  roc  is  set  to  NIL,  the  data  pointer  will  be  valid  only  for  the 
duration  of  this  call.  If  asyncCompl  eti  onProc  is  not  N I L,  it  contains  an 
ICMCompl  eti  onProcRecord  (IV-2279)  structure  that  must  be  called  when  your 
media  handler  is  done  with  the  provided  data  pointer. 
transferProc 

A  routine  that  allows  the  application  to  transform  the  type  of  the  input  data  to 
the  kind  of  data  preferred  by  the  codec.  The  client  of  the  codec  passes  the  source 
data  in  the  form  most  convenient  for  it.  If  the  codec  needs  the  data  in  another 
form,  it  can  negotiate  with  the  caller  or  directly  with  the  Image  Compression 
Manager  to  obtain  the  required  data  format. 
refCon 

A  reference  constant,  defined  as  a  void  pointer.  Your  application  specifies  the 
value  of  this  reference  constant  in  the  function  structure  you  pass  to  the  media 
handler. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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MediaSetNonPrimarySourceData 


Discussion 

There  are  two  tasks  required  to  support  modifier  tracks  in  a  derived  media  handler: 
sending  and  receiving.  The  base  media  handler  takes  care  of  sending  data  for  all  its 
clients.  Therefore,  authors  of  derived  media  handlers  do  not  usually  need  to 
implement  sending  data  support. 

Receiving  data  is  a  more  complex  situation.  The  base  media  handler  takes  care  of 
input  types  that  it  understands.  The  base  media  handler  supports  the  following 
types  of  data:  If  a  media  handler  wants  to  support  receiving  other  types  of  data  it 
must  implement  MediaSetNonPrimary  Source  Data.  Medi  aSetNonPri  marySourceData  is 
called  by  modified  tracks  to  supply  the  current  data  for  each  input.  All 
unrecognized  input  types  should  be  delegated  to  the  base  media  handler  so  that 
they  can  be  handled. 

The  following  is  a  basic  shell  implementation  of  a  derived  media  handler's 
Medi  aSetNonPri  marySourceData  function.  Note  that  your  derived  media  handler 
must  delegate  all  input  types  it  does  not  handle  to  the  base  media  handler: 

//  MySetNonPrimarySourceData  coding  example 

kT  rackModi f i erTypeMatri x 

kT  rackModi f i erTypeGraphi csMode 

kT  rackModi f i erTypeCl i p 

kT  rackModi fi erTypeVol  ume 

kTrackModi fi erTypeBal  ance 

pascal  ComponentResul t  MySetNonPrimarySourceDatal  MyGlobals  store, 

long  inputlndex,  long  dataDescri pti onSeed ,  Handle  dataDescri pti on  , 
void  *data,  long  dataSize, 

ICMCompl eti on P roc Record Ptr  asyncCompl eti on P roc , 

Uni versal ProcPtr  transferProc ,  void  *refCon  ) 

{ 

ComponentResul t  err  =  noErr; 

QTAtom  inputAtom; 

QTAtom  typesAtom; 
long  inputType; 

//  determine  what  kind  of  input  this  is 
inputAtom  =  QT  Fi ndChi 1 dBy I D ( store->i nputMap , 

kParentAtomlsContainer,  kTrackModi fi erlnput ,  inputlndex,  NIL); 
if  ( ! i nputAtom)  { 

err  =  cannotFi ndAtomErr ; 
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goto  bail ; 

} 

typesAtom  =  QTFi ndChi 1 dBy I D ( store->i nputMap ,  inputAtom, 
kTrackModi f i erType ,  1,  NIL); 

err  =  QTCopyAtomDataToPtr(store->inputMap,  typesAtom,  FALSE, 
sizeoft inputType) ,  &inputType,  NIL); 
if  ( err )  goto  bail ; 

swi tch ( i nputType )  { 
case  kMy InputType ; 

if  (data  ==  NIL)  { 

//  no  data,  reset  to  default  value 

} 

el  se  { 

//  use  this  data 

//  when  done,  notify  caller  we're  done  with  this  data 
if  ( asyncCompl eti onProc ) 

Call  ICMCompl etionProct 

asyncCompl eti onProc->compl eti onProc, 

noErr,  codecCompl eti onSource  |  codecCompl eti onDest , 

asyncCompl eti onProc->compl eti on  Ref Con ) ; 

} 

break; 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 

MediaSetPublicInfo 


Undocumented 

ComponentResul t  MediaSetPublicInfo  ( 
MediaHandler  mh, 

OSType  i nfoSel ector , 

void  *i nfoDataPtr , 

Si ze  dataSi ze  ) ; 
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mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 
i nf oSel ector 

Undocumented 
i nfoDataPtr 

Undocumented 
dataSi ze 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaSetRate 


Sets  a  media's  playback  rate. 

ComponentResul t  MediaSetRate  ( 
MediaHandler  mh. 

Fixed  rate  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

rate 

A  32-bit,  fixed-point  number  that  indicates  your  media's  new  effective 
playback  rate.  This  effective  rate  accounts  for  any  master  time  bases  that  may 
be  in  use  with  the  current  movie.  Positive  values  represent  forward  rates  and 
negative  values  indicate  reverse  rates. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  obtain  the  initial  rate  information  from  the  effecti  veRate  field  of  the 
GetMovi  eCompl  eteParams  (IV-2268)  structure  that  the  Movie  Toolbox  provides  to 
your  Medi  a  Ini  ti  al  i  ze  (11-877)  function.  Your  derived  media  handler  should 
support  this  function  if  you  perform  your  own  scheduling;  that  is,  you  have  set  the 
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handl  erNoSchedul  er  flag  to  1  in  the  f  1  ags  parameter  of  Medi  aSetHandlerCapabilities 
(11-894).  Your  media  handler  can  use  this  function  to  determine  when  your  media 
is  playing,  and  the  direction  and  rate  of  playback.  This  information  can  help  you 
prepare  for  playback  more  efficiently. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 


MediaSetScreenLock 


Locks  the  display  screen  for  a  media  handler. 

ComponentResul t  MediaSetScreenLock  ( 
MediaHandler  mh, 

Bool ean  1 ocklt  ) ; 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
1 ocklt 

Pass  TRUE  to  lock  the  screen,  FALSE  to  unlock  it. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaSetSoundBalance 


Sets  the  sound  balance  of  the  media  handler. 

ComponentResul t  MediaSetSoundBalance  ( 
MediaHandler  mh, 

short  bal ance  ) ; 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
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bal ance 

The  balance  setting  of  the  media  handler  as  a  16-bit,  fixed-point  value.  The 
high-order  8  bits  contain  the  integer  part  of  the  value;  the  low-order  8  bits 
contain  the  fractional  part.  Valid  balance  values  range  from  -1.0  to  1.0. 
Negative  values  emphasize  the  left  sound  channel,  and  positive  values 
emphasize  the  right  sound  channel;  a  value  of  0  specifies  neutral  balance. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "Sound  Media  Handler  Functions"  (V-2755) 

Related  Java  Methods 

qui cktime . std .movi es .medi a .Audi oMedi aHandl er . set Bal ance( ) , 
qui cktime . std .movi es .medi a . SoundMedi aHandl er . setBal ance( ) , 
qui  cktime .  std  .movi  es  .medi  a . MPEGMedi aHandl er . setBal ance ( ) 


See  Also 

For  the  corresponding  get  function,  see  Medi  aGetSoundBal  ance  (11-860). 


MediaSetSoundBass  AndT  reble 


Sets  the  bass  and  treble  controls  for  a  media  handler. 

ComponentResul t  MediaSetSoundBassAndTreble  ( 
MediaHandler  mh, 

short  bass, 

short  treble  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 

bass 

Undocumented 
trebl e 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 
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Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

See  Also 

For  the  corresponding  get  function,  see  Medi  aGetSoundBassAndTrebl  e  (11-861). 


MediaSetSoundEqualizerBands 


Sets  sound  equalizer  bands  for  a  media  handler. 

ComponentResul t  MediaSetSoundEqualizerBands  ( 
MediaHandler  mh, 

Medi aEQSpectrumBandsRecordPtr  spectrumlnfo  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
spectrumlnfo 

A  pointer  to  a  Medi  aEQSpectrumBandsRecord  (IV-2304)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

See  Also 

For  the  corresponding  get  function,  see  Medi  aGetSoundEqual  i  zerBands  (11-862). 


MediaSetSoundLevelMeteringEnabled 


Enables  or  disables  sound  level  metering  for  a  media  handler. 

ComponentResul t  Medi aSetSoundLevel Meteri ngEnabl ed  ( 
MediaHandler  mh, 

Bool ean  enabl e  ) ; 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
enabl e 

Pass  TRUE  to  enable  sound  level  metering,  FALSE  to  disable  it. 
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function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


See  Also 

For  the  corresponding  get  function,  see  Medi  aGetSoundLevel  Meteri  ngEnabl  ed 
(11-863). 


MediaSetSoundLocalizationData 


Supports  3D  sound  capabilities  in  a  media  handler  that  plays  sound. 

ComponentResul t  MediaSetSoundLocalizationData  ( 

MediaHandler  mh. 

Handle  data  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

data 

The  data  passed  to  your  media  handler,  in  the  format  of  a  Macintosh  Sound 
Sprockets  SSpLocal  i  zati  onData  (IV-2460)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  routine  is  passed  a  handle  containing  the  new  SSpLocal  i  zati  onData  (IV-2460) 
structure  to  use.  If  the  handle  is  N I L,  it  indicates  that  no  3D  sound  effects  should  be 
used.  If  you  implement  this  routine,  and  return  n  o  E  r  r  as  the  result,  it  is  assumed  that 
your  media  handle  assumes  responsibility  for  disposing  of  the  data  handle  passed. 
If  the  implementation  of  this  routine  returns  an  error,  the  caller  will  dispose  of  the 
handle.  The  reason  for  this  behavior  is  to  minimize  the  copying  of  the  settings 
handle,  making  it  easier  for  developers  to  implement  this  function.  This  function  is 
called  regardless  of  whether  the  3D  sound  settings  were  set  on  the  track  using 
SetT  rackSound  Local  i  zati  on  Sett  i  ngs  (III— 1666)  or  via  a  modifier  track  mechanism. 

Special  Considerations 

If  you  are  creating  a  media  handler  that  plays  sound  and  wish  to  support  3D  sound 
capabilities,  you  need  to  implement  this  routine. 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "Managing  Sound  Localization"  (V-2866) 


MediaSetSoundOutputComponent 


Sets  the  sound  output  component  for  a  media  handler. 

ComponentResul t  MediaSetSoundOutputComponent  ( 
MediaHandler  mh. 

Component  outputComponent  ) ; 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
outputComponent 

An  instance  of  a  sound  output  component.  Your  software  obtains  this  reference 
when  calling  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

See  Also 

For  the  corresponding  get  function,  see  Medi  aGetSoundOutputComponent  (11-864). 


MediaSetT  racklnputMapRef  erence 


Provides  a  derived  media  handler  with  an  updated  input  map. 

ComponentResul t  Medi aSetTracklnputMapReference  ( 
MediaHandler  mh, 

QTAtomContai ner  inputMap  ); 


The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 


11-908 


Inside  QuickTime:  Function  l-Q 


MediaSetUserPreferredCodecs 


i nputMap 

The  media  input  map  for  this  operation.  Do  not  modify  or  dispose  of  the  input 
map  provided. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

When  an  application  modifies  the  media  input  map,  this  function  provides  the 
derived  media  handler  with  the  updated  input  map.  When  this  function  is  called, 
the  media  handler  should  store  the  updated  input  map  and  recheck  the  types  of  all 
inputs,  if  it  is  caching  this  information.  The  input  map  reference  passed  to  this 
function  should  not  be  disposed  of  or  modified  by  the  media  handler. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 


MediaSetUserPreferredCodecs 


Requests  that  a  media  handler  favor  specified  codec  components  when  selecting 
components  with  which  to  play  media. 

ComponentResul t  MediaSetUserPreferredCodecs  ( 

MediaHandler  mh, 

CodecComponentHandl e  userPref erredCodecs  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

userP referred Codecs 

A  handle  containing  component  identifiers.  The  media  handler  component  will 
make  its  own  copy  of  this  handle.  The  components  should  be  specified  in  order 
from  most  preferred  to  least  preferred.  Pass  N I L  to  invalidate  the  standing 
request  without  substituting  another. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  badComponentSel  ector  if  the 
media  handler  component  does  not  support  this  call.  Returns  noErr 
if  there  is  no  error. 
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Discussion 

This  method  does  not  guarantee  that  the  specified  components  will  be  used;  other 
factors  may  take  precedence.  Components  that  are  preferred  may  not  be  used  if  they 
can't  be  part  of  the  chain  required  to  play  the  media;  for  example,  if  they  don't 
handle  the  pixel  format  or  the  video  output. 

Here  is  an  example  of  code  that  uses  this  function: 

CodecComponentHandl e  userPreferredCodecs  =  nil; 

ComponentDescri pti on  cd  =  {  decompressorComponentType , 

myPreferredCodecType, 

myPreferredCodecManufacturer, 

0. 

0  }; 

CodecComponent  c  =  FindNextComponentt  0,  &cd  ); 

MediaHandler  myMedia; 

OSErr  err; 

PtrToHandt  &c,  ( Handl e*)&userPreferredCodecs ,  sizeof(c)  ); 

myMedia  =  GetMedi aHandl er(  GetTrackMedi a (  track  )  ); 

err  =  Medi aSetUserPreferredCodecs (  myMedia,  userPreferredCodecs  ); 
DisposeHandl e(  (Handle)userPreferredCodecs  ); 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

See  Also 

For  the  corresponding  get  function,  see  Medi  aGetUserPreferredCodecs  (11-867). 

MediaSetVideoParam 

Lets  you  dynamically  adjust  the  bri  ghtness,  contrast,  hue,  sharpness,  saturation, 
black  level,  and  white  level  of  a  video  image. 

ComponentResul t  MediaSetVideoParam  ( 

MediaHandler  mh, 

1 ong  whi chParam , 

unsigned  short  *value  ); 
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mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 
whi chParam 

A  constant  (see  below)  that  specifies  the  video  parameter  you  want  to  adjust, 
val  ue 

The  actual  value  of  the  video  parameter.  The  meaning  of  the  values  vary 
depending  on  the  implementation. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

whichParam  Constants 

kMedi a Vi deoParamBri ghtness 

The  brightness  value  controls  the  overall  brightness  of  the  digitized  video 
image.  Brightness  values  range  from  0  to  65,535,  where  0  is  the  darkest  possible 
setting  and  65,535  is  the  lightest  possible  setting. 
kMedi aVideoParamContrast 

The  contrast  value  ranges  from  0  to  65,535,  where  0  represents  no  change  to  the 
basic  image  and  larger  values  increase  the  contrast  of  the  video  image  (that  is, 
increase  the  slope  of  the  transform). 

kMedi aVideoParamHue 

Hue  is  similar  to  the  tint  control  on  a  television.  It  is  specified  in  degrees  with 
complementary  colors  set  180  degrees  apart  (red  is  0  degrees,  green  is  +120 
degrees,  and  blue  is  -120  degrees).  QuickTime  supports  hue  values  that  range 
from  0  (-180  degrees  shift  in  hue)  to  65,535  (+179  degrees  shift  in  hue),  where 
32,767  represents  a  0  degrees  shift  in  hue. 
kMedi aVideoParamSharpness 

The  sharpness  value  ranges  from  0  to  65,535,  where  0  represents  no  sharpness 
filtering  and  65,535  represents  full  sharpness  filtering.  Higher  values  result  in  a 
visual  impression  of  increased  picture  sharpness 
kMedi aVideoParamSaturation 

The  saturation  value  controls  color  intensity.  For  example,  at  high  saturation 
levels,  red  appears  to  be  red;  at  low  saturation,  red  appears  pink.  Valid 
saturation  values  range  from  0  to  65,535,  where  0  is  the  minimum  saturation 
value  and  65,535  specifies  maximum  saturation. 

kMedi aVideoParamBlackLevel 

Black  level  refers  to  the  degree  of  blackness  in  an  image.  The  highest  setting 
produces  an  all-black  image;  on  the  other  hand,  the  lowest  setting  yields  little, 
if  any,  black  even  with  black  objects  in  the  scene.  Black  level  values  range  from 
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0  to  65,535,  where  0  represents  the  maximum  black  value  and  65,535  represents 
the  minimum  black  value. 

kMedi aVideoParamWhite Level 

White  level  refers  to  the  degree  of  whiteness  in  an  image.  White  level  values 
range  from  0  to  65,535,  where  0  represents  the  minimum  white  value  and  65,535 
represents  the  maximum  white  value. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 

See  Also 

For  the  corresponding  get  function,  see  Medi  aGetVi  deoParam  (11-868).  The 

Medi  aSetVi  deoParam  and  Medi  aGetVi  deoParam  (11-868)  functions  are  currently  used 

by  the  MPEG  media  handler. 


MediaT  argetRef  ConsEqual 


Undocumented 


Component Res ul t  MediaTargetRefConsEqual 
MediaHandler  mh, 
long  firstRefCon, 

long  secondRefCon , 

Bool ean  *equal  ) ; 


( 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
f i rstRefCon 

Undocumented 

secondRefCon 

Undocumented 

equal 

A  pointer  to  a  Bool  ean;  it  is  TRUE  if  f  i  rstRefCon  and  secondRefCon  are  equal, 
FALSE  otherwise. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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MediaTimeBaseChanged 


Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaTimeBaseChanged 

Undocumented 

ComponentResul t  MediaTimeBaseChanged  ( 

Medi aHandl er  mh  ); 

mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
function  result  Undocumented 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


MediaT  imeT  oSampleNum 


Lets  you  find  the  sample  that  contains  the  data  for  a  specified  time. 


void  MediaTimeToSampl eNum  ( 

Media  theMedia, 

TimeValue  time, 

long  *sampleNum, 

TimeValue  *sampleTime, 

TimeValue  *sampl eDurati on 


): 


theMedi  a 

The  media  for  this  operation.  You  obtain  this  media  identifier  from  such 
functions  as  NewTrackMedia  (11-1120)  and  GetTrackMedi a  (1-535). 

ti  me 

The  time  for  which  you  are  retrieving  sample  information.  You  must  specify 
this  value  in  the  media's  time  scale, 
sampl eNum 

A  pointer  to  a  long  integer  that  is  to  receive  the  sample  number.  The  Movie 
Toolbox  returns  the  sample  number  that  identifies  the  sample  that  contains 
data  for  the  time  specified  by  the  ti  me  parameter. 
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MediaTrackEdited 


sampl eT i me 

A  pointer  to  a  time  value.  The  Medi  aT i  meT oSampl  eNum  function  updates  this  time 
value  to  indicate  the  starting  time  of  the  sample  that  contains  data  for  the  time 
specified  by  the  time  parameter.  This  time  value  is  expressed  in  the  media's 
time  scale.  Set  this  parameter  to  N I L  if  you  don't  want  this  information, 
sampl eDurati on 

A  pointer  to  a  time  value.  The  Movie  Toolbox  returns  the  duration  of  the 
sample  that  contains  data  for  the  time  specified  by  the  ti  me  parameter.  This 
time  value  is  expressed  in  the  media's  time  scale.  Set  this  parameter  to  N I L  if  you 
don't  want  this  information. 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Media  Samples"  (V-2742) 

Related  Java  Methods 

qui ckti me . std .movi es .medi a . Medi a . ti meToSampl eNum( ) 


See  Also 

Medi  aT i meToSampl  eNum  does  not  account  for  edits  applied  to  the  media  by  a  movie's 
tracks.  If  you  want  to  work  with  edits,  use  the  functions  that  allow  you  to  look  for 
interesting  times,  such  as  GetMediaNextlnterestingTime  (1-437), 

GetMovi  eNext Interesti  ngT ime  (1-480),  and  GetT rackNext Interest!'  ngT i me  (1-537). 


MediaT  rackEdited 

Informs  a  derived  media  handler  about  edits  to  its  track. 

ComponentResul t  MediaTrackEdited  ( 

Medi aHandl er  mh  ) ; 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


11-914 
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MediaTrackPropertyAtomChanged 


Discussion 

Your  derived  media  handler  should  support  this  function  if  you  are  caching 
location  information  about  track  edits,  or  if  you  are  using  any  time  values  in  the 
movie's  time  base.  Whenever  the  Movie  Toolbox  calls  this  function,  your  media 
handler  should  recalculate  this  type  of  information. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers  .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 


MediaT  rackPropertyAtomChanged 

Notifies  the  derived  media  handler  whenever  its  media  property  atom  has  changed. 

ComponentResul t  MediaTrackPropertyAtomChanged  ( 

MediaHandler  mh  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Medi  aTrackPropertyAtomChanged  is  called  whenever  Set  Medi  aPropertyAtom  (III— 1604) 
is  called.  If  the  media  handler  uses  information  from  the  property  atom,  it  should 
rebuild  the  information  at  this  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 


MediaT  rackRef  erencesChanged 

Notifies  the  derived  media  handler  whenever  the  track  references  in  the  movie 
change. 

ComponentResul t  Medi aTrackReferencesChanged  ( 
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MediaVideoOutputChanged 


Medi aHandl er  mh  ) ; 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

When  an  application  creates,  modifies,  or  deletes  a  track  reference,  the  media 
handler's  Medi  aT rackReferencesChanged  function  is  called.  When  this  function  is 
called,  a  media  handler  should  rebuild  all  information  about  track  references  and 
reset  its  values  for  all  media  inputs  to  their  default  values. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 

Programming  summary:  "General  Data  Management"  (V-2861) 


MediaVideoOutputChanged 


Undocumented 

ComponentResul t  MediaVideoOutputChanged  ( 
MediaHandler  mh, 

Componentlnstance  vout  ); 


mh 

The  Toolbox's  connection  to  your  derived  media  handler.  You  can  obtain  this 
reference  from  GetMedi  aHandl  er  (1-432). 

vout 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 
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MIDIImportGetSettings 


Obtains  settings  that  control  the  importation  of  MIDI  files. 

ComponentResul t  MIDIImportGetSettings  ( 
TextExportComponent  ci  , 

long  *setting  ); 


ci 

A  text  export  component  instance  used  to  import  a  MIDI  file.  Your  software 
obtains  this  reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent 
(11-1131). 

setti ng 

Flags  (see  below)  that  control  the  importation  of  MIDI  files.  The  flags 
correspond  to  the  checkboxes  in  the  MIDI  Import  Options  dialog  box. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

setting  Constants 

kMIDI ImportSi lenceBefore 

Adds  one  second  of  silence  before  the  first  note. 
kMIDI ImportSi 1 enceAfter 

Adds  one  second  of  silence  after  the  last  note. 
kMIDI Import 20  PI ayabl e 

Imports  only  MIDI  data  that  can  be  used  with  QuickTime  2.0.  The  imported 
data  does  not  include  program  changes  and  has  at  most  32  parts. 
kMIDI ImportWantLyri  cs 

Imports  karaoke  lyrics  as  a  text  track. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Importing  MIDI  Files"  (V-2924) 

See  Also 

For  the  corresponding  set  function,  see  MIDI  ImportSetSetti  ngs  (11-917). 


MIDIImportSetSettings 

Define  settings  that  control  the  importation  of  MIDI  files. 
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MovieExecuteWiredActions 


ComponentResul t  MIDI ImportSetSetti ngs  ( 
TextExportComponent  cl, 

1 ong  setti ng  ) ; 


cl 

A  text  export  component  instance  used  to  import  a  MIDI  file.  Your  software 
obtains  this  reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent 
(11-1131). 

setti ng 

Flags  (see  below)  that  control  the  importation  of  MIDI  files.  The  flags 
correspond  to  the  checkboxes  in  the  MIDI  Import  Options  dialog  box. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

setting  Constants 

kMIDIImportSilenceBefore 

Adds  one  second  of  silence  before  the  first  note. 
kMIDIImportSil enceAfter 

Adds  one  second  of  silence  after  the  last  note. 
kMIDIImport20Playable 

Imports  only  MIDI  data  that  can  be  used  with  QuickTime  2.0.  The  imported 
data  does  not  include  program  changes  and  has  at  most  32  parts. 

kMIDIImportWantLyrics 

Imports  karaoke  lyrics  as  a  text  track. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Importing  MIDI  Files"  (V-2924) 

See  Also 

For  the  corresponding  get  function,  see  MIDI  ImportGetSetti  ngs  (11-917). 


MovieExecuteWiredActions 


Undocumented 

redActions  ( 
theMovi e , 
fl ags , 
acti ons  ) ; 


OSErr  Movi eExecuteWi 
Movi  e 
1  ong 

QTAtomContai ner 


11-918 


Inside  QuickTime:  Function  l-Q 


MovieExportAddDataSource 


theMovi e 

A  movie  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e 
(11-1084). 
fl  ags 

Undocumented 
acti ons 

Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

flags  Constant 

movi eExecuteWi redActi onDontExecute 
Undocumented 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


MovieExportAddDataSource 


Defines  a  data  source  for  use  with  an  export  operation  performed  by 
Movi eExportFromProceduresToDataRef  (11-922). 


ComponentResul t  MovieExportAddDataSource  ( 


Movi eExportComponent 
OSType 
T i meScal e 
1  ong 

Movi  eExportGetPropertyllPP 
Movi  eExportGetDatallPP 
voi  d 


ci  , 

trackType , 
scale, 

*trackID, 
getPropertyProc , 
getDataProc, 
*refCon  ); 


ci 

A  movie  export  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
trackType 

The  type  of  media  provided  by  this  data  source.  This  normally  corresponds  to 
a  QuickTime  media  type  such  as  Vi  deoMedi  aType  or  SoundMedi  aType. 
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MovieExportDisposeGetDataAndPropertiesProcs 


seal  e 

The  time  scale  for  time  values  passed  togetDataProc  parameter.  If  the  source 
data  is  being  taken  from  a  QuickTime  track,  this  value  is  typically  the  media's 
time  scale. 
trackID 

An  identifier  for  the  data  source.  This  identifier  is  returned  from  the  call. 
getPropertyProc 

A  Movi  eExportGetPropertyProc  (III— 2102)  callback  that  provides  information 
about  processing  source  samples. 
getDataProc 

A  Movi  eExportGetDataProc  (III— 2101)  callback  the  export  component  uses  to 
request  sample  data. 
refCon 

Passed  to  the  procedures  specified  in  the  getPropertyProc  and  getDataProc 
parameters.  Use  this  parameter  to  point  to  a  data  structure  containing  any 
information  your  callbacks  need. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Before  starting  an  export  operation,  all  the  data  sources  must  be  defined  by  calling 
this  function  once  for  each  data  source. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Exporting  Movie  Data"  (V-2858) 


MovieExportDisposeGetDataAndPropertiesProcs 


Disposes  of  the  memory  associated  with  the  procedures  returned  by 
Movi  e Expo rtNewGet Da taAndP rope rti  esProcs  (11-927). 


ComponentResul t  Movi eExportDi s 
Movi e Export Component 
Movi e Expo rtGetP rope rtyUPP 
Movi  e  Expo  rtGet  Da  tall  PP 
voi  d 


oseGetDataAndProperti esProcs  ( 
ci  , 

getPropertyProc , 
getDataProc , 

*refCon  ) ; 


11-920 
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MovieExportDoUserDialog 


ci 

A  movie  export  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
getPropertyProc 

A  Movi  eExportGetPropertyProc  (III— 2102)  callback  that  provides  information 
about  processing  source  samples. 
getDataProc 

A  Movi  eExportGetDataProc  (III— 2101)  callback  that  the  export  component  uses  to 
request  sample  data. 
refCon 

Passed  to  the  procedures  specified  in  the  getPropertyProc  and  getDataProc 
parameters.  Use  this  parameter  to  point  to  a  data  structure  containing  any 
information  your  callbacks  need. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Exporting  Movie  Data"  (V-2858) 


MovieExportDoUserDialog 


Requests  that  a  component  display  its  user  dialog  box. 


ComponentResul t  MovieExportDoUserDialog  ( 


Movi eExportComponent 

Movi  e 

T  rack 

T i meVal ue 

T i meVal ue 

Bool ean 


ci  , 

theMovi e , 
onlyThi sTrack, 
startTime, 
durati on , 
*canceled  ); 


ci 

A  movie  export  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

theMovi e 

The  movie  containing  the  data  to  be  exported. 
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MovieExportFromProceduresToDataRef 


onlyThi sT  rack 

Specifies  that  the  export  component  should  only  attempt  to  export  the  data 
from  a  single  track.  If  this  parameter  is  set  to  NIL,  the  exporter  should  attempt 
to  export  the  entire  movie,  or  all  of  the  tracks  in  the  movie  that  it  can  export.  For 
example,  an  audio  export  component  might  export  multiple  audio  tracks, 
mixing  them  if  necessary.  If  this  parameter  is  not  N I L,  the  exporter  should 
attempt  to  export  only  the  specified  track. 
startTime 

The  movie  time  at  which  to  begin  the  export  operation.  If  you  pass  0,  the 
operation  should  start  at  the  beginning  of  the  movie  or  track. 

durati on 

The  duration,  in  movie  timescale  units,  of  the  segment  to  be  exported.  To  export 
the  entire  movie,  or  an  entire  track,  pass  in  the  value  returned  by 
GetMovi  eDurati  on  (1-470)  or  GetT rackDurati  on  (1-529),  minus  the  value  passed 
in  startTime,  as  described  above, 
cancel ed 

A  pointer  to  a  Bool  ean  value.  Your  component  should  set  this  value  to  TRUE  if 
the  user  cancels  the  dialog  box,  otherwise  FALSE.  If  the  user  cancels  the  dialog 
box,  your  component  should  revert  to  its  settings  as  they  were  before  executing 
this  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuring  Movie  Data  Export  Components"  (V-2859) 

Related  Java  Methods 

qui ckti me . std . qt components . Movi e Exporter . doUserDialogt ) 


MovieExportFromProceduresToDataRef 


Exports  data  provided  by  Movi  eExportAddDataSource  (11-919)  to  a  specified  location. 

ComponentResul t  Movi eExportFromProceduresToDataRef  ( 

Movi eExportComponent  ci  , 

Handle  dataRef, 

OSType  dataRefType  ); 


11-922 


Inside  QuickTime:  Function  l-Q 


MovieExportGetAuxiliaryData 


ci 

A  movie  export  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
dataRef 

The  data  reference  for  the  export  operation. 
dataRefType 

The  type  identifier  for  the  data  reference  specified  by  dataRef. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  exports  data  provided  by  Movi  eExportAddDataSource  (11-919)  to  a 
location  specified  by  dataRef  and  dataRefType.  Typically  dataRef  contains  a 
Macintosh  file  alias  and  dataRefType  is  set  to  rAl  i  asType. 

Special  Considerations 

Movie  data  export  components  that  support  export  operations  from  procedures 
must  set  the  canMovi  eExportFromProcedures  flag  in  their  component  flags. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Exporting  Movie  Data"  (V-2858) 


MovieExportGetAuxiliaryData 


Retrieves  additional  data  from  a  component. 

ComponentResul t  MovieExportGetAuxiliaryData  ( 
Movi eExportComponent  ci  , 

Handle  dataH, 

OSType  *handleType  ); 


ci 

A  movie  export  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

dataH 

A  handle  that  is  to  be  filled  with  the  additional  data.  Your  component  should 
resize  this  handle  as  appropriate.  Your  component  is  not  responsible  for 
disposing  of  this  handle. 
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MovieExportG  etCreatorType 


handl eType 

A  pointer  to  the  type  of  data  you  place  in  the  handle  specified  by  the  data 
parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  component  should  expect  the  application  to  call  this  function  after  the  export 
process  ends. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuring  Movie  Data  Export  Components"  (V-2859), 
"Exporting  Movie  Data"  (V-2858) 

Related  Java  Methods 

qui ckti me . std . qt components . Movi e Exporter . getAuxi 1 i ary Data ( ) 


MovieExportGetCreatorT  ype 


Undocumented 

ComponentResul t  Movi eExportGetCreatorType  ( 
Movi eExportComponent  ci  , 

OSType  *creator  ) ; 


ci 

A  movie  export  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

creator 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Related  Java  Methods 

qui ckti me . std . qt components .Movi e Exporter .getCreatorTypet) 


11-924 


Inside  QuickTime:  Function  l-Q 


MovieExportGetFileNameExtension 


MovieExportGetFileNameExtension 


Undocumented 

ComponentResul t  Movi eExportGetFi 1 eNameExtensi on  ( 
Movi  eExportComponent  ci  , 

OSType  *extension  ); 


ci 

A  movie  export  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

extensi on 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Related  Java  Methods 

qui cktime . std . qt components .Movi e Exporter . get  Export Fi 1 eNameExtensi on( ) 


MovieExportGetSettingsAsAtomContainer 


Retrieves  the  current  settings  from  the  movie  export  component. 

ComponentResul t  Movi eExportGetSetti ngsAsAtomContainer  ( 

Movi  eExportComponent  ci  , 

QTAtomContai ner  *settings  ); 


ci 

A  movie  export  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
setti ngs 

The  address  where  the  newly-created  atom  container  should  be  stored  by  the 
call.  The  caller  is  responsible  for  disposing  of  the  returned  QT  atom  container. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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MovieExportGetShortFileTypeString 


Discussion 

Applications  can  call  this  function  to  obtain  a  correctly  formatted  atom  container  to 
use  with  Movi  eExportSetSetti  ngsFromAtomContai  ner  (11-932).  This  might  be  done 
after  a  call  to  Movi  eExportDoUserDi  al  og  (11-921),  for  example,  to  apply  the 
user-obtained  settings  to  a  series  of  exports. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Exporting  Movie  Data"  (V-2858) 

Related  Java  Methods 

qui ckti me . std . qt components .Movi e Exporter . get  Expo rtSetti ngsFromAtomContai ner 
qui ckti me . std .movi es . AtomContai ner . f romMovi e Exporter! ) 


MovieExportGetShortFileTypeString 


Undocumented 

ComponentResul t  Movi eExportGetShortFi 1 eTypeStri ng  ( 
Movi eExportComponent  ci  , 

Str255  typeStri ng  ) ; 


ci 

A  movie  export  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
typeStri ng 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Related  Java  Methods 

qui ckti me . std . qt components .Movi e Exporter . get  Expo rtShortFi leTypeStringt ) 


11-926 


Inside  QuickTime:  Function  l-Q 


MovieExportGetSourceMediaType 


MovieExportGetSourceMediaType 


Returns  either  the  track  type  if  a  movie  export  component  is  track-specific  or  0  if  it 
is  track-independent. 

ComponentResul t  MovieExportGetSourceMediaType  ( 

Movi  eExportComponent  ci  , 

OSType  *mediaType  ); 


ci 

A  movie  export  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

medi aType 

The  track  type  if  the  component  is  track-specific  or  0  if  it  is  track-independent. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  routine  returns  the  same  values  that  were  previously  stored  in  the 
componentManuf  acturer  field  of  the  ComponentDescri  pti  on  (IV-2212)  structure.  This 
frees  up  the  field  to  be  used  for  the  manufacturer. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Related  Java  Methods 

qui cktime . std . qt components .Movi e Exporter . get  Export Sou rceMedi aType( ) 


MovieExportNewGetDataAndPropertiesProcs 


Returns  Movi  eExportGetPropertyProc  (III— 2102)  and  Movi  eExportGetDataProc 
(III— 2101)  callbacks  that  can  be  passed  to  Movi  eExportAddDataSource  (11-919)  to 
create  a  new  data  source. 


ComponentResul t  MovieExportNewGetDataAndPropertiesProcs  ( 


Movi eExportComponent 

OSType 

T i meScal e 

Movi  e 

T  rack 

T i meVal ue 

T i meVal ue 


ci  , 

trackType , 
*scal e , 
theMovi e , 
theTrack, 
startTime, 
durati on , 
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MovieExportNewGetDataAndPropertiesProcs 


Movi e Expo rtGetP rope rtyUPP  *getPropertyProc, 

Movi eExportGetDataUPP  *getDataProc, 

void  **refCon  ); 


ci 

A  movie  export  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
trackType 

The  format  of  the  data  to  be  generated  by  the  returned  MovieExportGetDataProc 
(III— 2101). 

seal  e 

The  time  scale  returned  from  this  function;  this  should  be  passed  on  to 
Movi  eExportAddDataSource  (11-919)  with  the  procedures. 
theMovi e 

The  movie  for  this  operation,  supplied  by  the  Movie  Toolbox.  Your  component 
may  use  this  identifier  to  obtain  sample  data  from  the  movie  or  to  obtain 
information  about  the  movie. 
theT  rack 

The  track  for  this  operation.  This  track  identifier  is  supplied  by  the  Movie 
Toolbox. 

startTime 

The  starting  point  of  the  track  or  movie  segment  to  be  converted.  This  time 
value  is  expressed  in  the  movie's  time  coordinate  system, 
durati on 

The  duration  of  the  track  or  movie  segment  to  be  converted.  This  duration 
value  is  expressed  in  the  movie's  time  coordinate  system. 
getPropertyProc 

A  Movi  eExportGetPropertyProc  (III— 2102)  callback  that  provides  information 
about  processing  source  samples. 
getDataProc 

AMovieExportGetDataProc  (III— 2101 )  callback  that  the  export  component  uses  to 
request  sample  data. 
refCon 

Passed  to  the  procedures  specified  in  the  getPropertyProc  and  getDataProc 
parameters.  Use  this  parameter  to  point  to  a  data  structure  containing  any 
information  your  callbacks  need. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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MovieExportSetGetMoviePropertyProc 


Discussion 

This  function  exists  in  order  to  provide  a  standard  way  of  getting  data  using  this 
protocol  out  of  a  movie  or  track.  The  returned  procedures  must  be  disposed  by 
calling  Movi  eExportDi  sposeGetDataAndProperti  esProcs  (11-920). 

Special  Considerations 

This  function  is  only  implemented  by  movie  data  export  components. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Exporting  Movie  Data"  (V-2858) 


MovieExportSetGetMoviePropertyProc 


Specifies  the  procedure  that  the  export  component  should  call  to  retrieve  movie 
level  properties  during  Movi  eExportFromProceduresToDataRef  (11-922). 

ComponentResul t  Movi eExportSetGetMovi ePropertyProc  ( 

Movi eExportComponent  ci  , 

Movi e Expo rtGetPr ope rtyUPP  getPropertyProc , 

void  *refCon  ); 


ci 

A  movie  export  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

getPropertyProc 

The  Movi  eExportGetPropertyProc  (III— 2102)  callback  that  the  export  component 
will  call  to  retrieve  movie-level  properties. 

refCon 

The  reference  value  that  will  be  passed  to  the  callback  specified  by 
getPropertyProc.  Use  this  parameter  to  point  to  a  data  structure  containing  any 
information  your  callback  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4.  With  QuickTime  4,  applications  can  specify  a 
Movi  eExportGetPropertyProc  that  will  be  called  to  retrieve  movie  level  properties 
during  the  exporter's  Movi  eExportFromProceduresToDataRef  (11-922)  execution.  This 
procedure  is  identical  to  a  data  source  property  procedure  except  that  it  is  called  for 
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MovieExportSetProgressProc 


movie  properties.  For  example,  with  QuickTime  4,  the  QuickTime  movie  export 
component  calls  the  procedure  to  retrieve  the  time  scale  for  the  exported  movie.  If 
the  property  procedure  is  not  specified  or  doesn't  support  this  property,  than  the 
default  movie  time  scale  (600)  is  used. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Exporting  Movie  Data"  (V-2858) 


MovieExportSetProgressProc 


Assigns  a  movie  progress  function. 

ComponentResul t  MovieExportSetProgressProc  ( 
Movi eExportComponent  ci  , 

Movi eProgressUPP  proc, 

1 ong  refcon  ) ; 


ci 

A  movie  export  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

proc 

A  pointer  to  the  application's  MovieProgressProc  (III— 2105)  callback.  If  this 
parameter  is  set  to  N I L,  the  application  is  removing  its  progress  function.  In  this 
case,  your  component  should  stop  calling  the  progress  function. 

refcon 

A  reference  constant.  Your  component  should  pass  this  constant  back  to  the 
application's  progress  function  whenever  you  call  that  function.  Use  this 
parameter  to  point  to  a  data  structure  containing  any  information  the  callback 
needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

These  progress  functions  must  support  the  same  interface  as  Movie  Toolbox 
progress  functions.  Note  that  this  interface  not  only  allows  you  to  report  progress 
to  the  application,  but  also  allows  the  application  to  cancel  the  request. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


11-930 
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MovieExportSetSampleDescription 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuring  Movie  Data  Export  Components"  (V-2859) 

Related  Java  Methods 

qui cktime . std . qt components . Movi e Exporter . set  Prog  ressProcO 


MovieExportSetSampleDescription 


Requests  the  format  of  the  exported  data. 

ComponentResul t  Movi eExportSetSampl eDescri pti on  ( 
Movi eExportComponent  ci  , 

Sampi eDescri pti onHandl e  desc, 

OSType  mediaType  ); 


ci 

A  movie  export  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

desc 

A  handle  to  a  valid  Sampi  eDescri  pti  on  (IV-2414)  structure, 
medi aType 

The  type  of  media  the  Sampi  eDescri  pti  on  (IV-2414)  structure  is  for.  For 
example,  if  the  sample  description  was  a  sound  description,  this  parameter 
would  be  set  to  SoundMedi  aType. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  badComponentSel  ector  if  you 
should  be  passing  a  QT  atom  container  (see  discussion,  below). 
Returns  noErr  if  there  is  no  error. 

Discussion 

A  movie  export  component  may  use  all,  some,  or  none  of  the  settings  from  the 
Sampi  eDescri  pti  on  (IV-2414)  structure. 

If  your  application  attempts  to  set  the  sample  description  using  this  function,  and 
receives  the  badComponentSel  ector  error,  you  may  need  to  pass  in  the  sample 
description  using  Movi  eExportSetSetti  ngsFromAtomContai  ner  (11-932).  You  can  use 
Movi  eExportGetSetti  ngsAsAtomContai  ner  (11-925)  to  obtain  a  correctly  formatted 
atom  container  to  modify. 

Special  Considerations 

This  function  is  not  implemented  by  all  movie  export  components,  but  is  supported 
by  the  sound  movie  export  component,  for  example. 
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MovieExportSetSettingsFromAtomContainer 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Exporting  Movie  Data"  (V-2858) 

Related  Java  Methods 

qui ckti me . std . qt components . Movi e Exporter . setSampl eDescriptiont) 


MovieExportSetSettingsFromAtomContainer 


Sets  the  movie  export  component's  current  configuration  from  passed  settings  data. 

ComponentResul t  Movi eExportSetSetti ngsFromAtomContainer  ( 

Movi eExportComponent  ci  , 

QTAtomContai ner  settings  ); 


ci 

A  movie  export  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

setti ngs 

A  QT  atom  container  that  contains  the  settings. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  atom  container  may  contain  atoms  other  than  those  expected  by  the  particular 
component  type  or  may  be  missing  certain  atoms.  This  function  uses  only  those 
settings  it  understands. 

Here  is  sample  code  that  overrides  compression  settings: 

//  Movi eExportSetSetti ngsFromAtomContainer  coding  example 
Componentlnstance  sc; 

QTAtomContai ner  compressorData ; 

SCSpati al Setti ngs  ss; 

sc  =  OpenDefaultComponenttStandardCompressionType, 

StandardCompressionSubType) ; 
ss.codecType  =  kCi nepakCodecType ; 
ss  .  codec  =  NIL; 
ss. depth  =  0; 

ss  .  spati al Qual i ty  =  codecHi ghQual i ty 


11-932 
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err  =  SCSetInfo(sc,  scSpati al Setti ngsType ,  &ss); 

err  =  SCGetSetti ngsAsAtomContai ner( sc ,  &compressorData ) ; 

Movi e Export Set Setti ngsFromAtomContai ner  (qtvr Export,  compress  or Data ) ; 

Special  Considerations 

Some  movie  export  components  treat  sample  descriptions  as  part  of  their  settings. 
If  your  application  attempts  to  set  the  sample  description  using 
Movi  eExportSetSampl  eDescri  pti  on  (11-931),  and  receives  the  badComponentSel  ector 
error,  you  may  need  to  pass  in  the  Sampl  eDescri  pti  on  (IV-2414)  structure  using  this 
function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Exporting  Movie  Data"  (V-2858) 

Related  Java  Methods 

qui cktime . std . qt components .Movi e Exporter . set  Export Setti ngsFromAtomContai ner 


See  Also 

You  can  use  Movi  eExportGetSetti  ngsAsAtomContai  ner  (11-925)  to  obtain  a  correctly 
formatted  atom  container  that  you  can  then  modify. 


MovieExportT  oDataRef 


Allows  an  application  to  request  that  data  be  exported  to  a  data  reference  instead  of 
to  a  file. 


ComponentResul t  MovieExportToDataRef  ( 


Movi eExportComponent 

Handl e 

OSType 

Movi  e 

T  rack 

T i meVal ue 

T i meVal ue 


ci  , 

dataRef , 
dataRefType, 
theMovi e , 
onlyThi sTrack, 
startTime, 
duration  ); 


ci 

A  movie  export  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
dataRef 

A  handle  to  a  data  reference  indicating  where  the  data  should  be  stored. 
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MovieExportToFile 


dataRefType 

The  type  of  the  data  reference.  For  exporting  to  a  file,  the  d  a  t  a  Ref  is  a  Macintosh 
file  alias  and  the  dataRefType  is  rAl  i  asType. 
theMovi e 

The  movie  for  this  operation.  This  movie  identifier  is  supplied  by  the  Movie 
Toolbox.  Your  component  may  use  this  identifier  to  obtain  sample  data  from 
the  movie  or  to  obtain  information  about  the  movie. 

onlyThi sT  rack 

Identifies  a  track  that  is  to  be  converted.  This  track  identifier  is  supplied  by  the 
Movie  Toolbox.  If  this  parameter  contains  a  track  identifier,  your  component 
must  convert  only  the  specified  track. 
startTime 

The  starting  point  of  the  track  or  movie  segment  to  be  converted.  This  time 
value  is  expressed  in  the  movie's  time  coordinate  system, 
durati on 

The  duration  of  the  track  or  movie  segment  to  be  converted.  This  duration 
value  is  expressed  in  the  movie's  time  coordinate  system. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Exporting  Movie  Data"  (V-2858) 

Related  Java  Methods 

qui ckti me . std . qt components . Movi e Exporter . to Data  Ref ( ) 


MovieExportT  oFile 


Exports  data  to  a  file,  using  a  movie  data  export  component. 


ComponentResul t  MovieExportToFile  ( 

Movi eExportComponent  ci , 
const  FSSpec  *theFile, 

Movie  theMovie, 

Track  onlyThisTrack, 

TimeVal ue  startTime, 

TimeValue  duration  ); 


11-934 
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ci 

A  movie  export  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
theFi 1 e 

A  pointer  to  the  file  that  is  to  receive  the  converted  movie  data.  This  file's  type 
value  corresponds  to  your  component's  subtype  value. 

theMovi e 

The  movie  for  this  operation.  This  movie  identifier  is  supplied  by  the  Movie 
Toolbox.  Your  component  may  use  this  identifier  to  obtain  sample  data  from 
the  movie  or  to  obtain  information  about  the  movie. 
onlyThi  sTrack 

Identifies  a  track  that  is  to  be  converted.  This  track  identifier  is  supplied  by  the 
Movie  Toolbox.  If  this  parameter  contains  a  track  identifier,  your  component 
must  convert  only  the  specified  track. 
startTime 

The  starting  point  of  the  track  or  movie  segment  to  be  converted.  This  time 
value  is  expressed  in  the  movie's  time  coordinate  system. 

durati on 

The  duration  of  the  track  or  movie  segment  to  be  converted.  This  duration 
value  is  expressed  in  the  movie's  time  coordinate  system. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  requesting  program  or  Movie  Toolbox  must  create  the  destination  file  before 
calling  this  function.  Furthermore,  your  component  may  not  destroy  any  data  in  the 
destination  file.  If  you  cannot  add  data  to  the  specified  file,  return  an  appropriate 
error.  If  your  component  can  write  data  to  a  file,  be  sure  to  set  the 
canMovi  eExportFi  1  es  flag  in  the  component  FI  ags  field  of  your  component's 
Component  Descri  pti  on  (IV-2212)  structure.  Here  is  an  example  of  using  this  function 
with  a  flattener  component: 

//  MovieExportToFile  coding  example 
ComponentDescri pti on  desc; 

Component  flattener; 

Componentlnstance  qtvrExport  =  NIL; 

desc . componentType  =  Movi eExportType ; 

desc . componentSubType  =  Movi eFi 1 eType ; 

desc . componentManuf acturer  =  QTVRF1 attenerType ; 


M 
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flattener  =  FindNextComponent(NIL,  &desc); 
if  (flattener)  qtvrExport  =  OpenComponent  (flattener); 

if  (qtvrExport) 

Movi eExportToFi 1 e  (qtvrExport,  &myFi 1 eSpec ,  myQTVRMovi e ,  NIL,  0,  0); 

Special  Considerations 

Your  component  must  be  prepared  to  perform  this  function  at  any  time.  You  should 
not  expect  that  any  of  your  component's  configuration  functions  will  be  called  first. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Exporting  Movie  Data"  (V-2858) 

Related  Java  Methods 

qui ckti me . std . qt components .Movi e Exporter . toFi 1 e( ) 


MovieExportT  oHandle 


Exports  data  from  a  movie,  using  a  movie  data  export  component. 


ComponentResul t  MovieExportToHandle  ( 


Movi e Export Component 

Handl e 

Movi  e 

T  rack 

TimeVal ue 

TimeVal ue 


c  i  , 

dataH , 
theMovi e , 
onlyThisTrack, 
startTime, 
durati on  ) ; 


ci 

A  movie  export  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

dataH 

A  handle  to  be  filled  with  the  converted  movie  data.  Your  component  must 
write  data  into  this  handle  that  corresponds  to  your  component's  subtype 
value.  Your  component  should  resize  this  handle  as  appropriate. 

theMovi e 

The  movie  for  this  operation.  This  movie  identifier  is  supplied  by  the  Movie 
Toolbox.  Your  component  may  use  this  identifier  to  obtain  sample  data  from 
the  movie  or  to  obtain  information  about  the  movie. 
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onlyThi  sTrack 

Identifies  a  track  that  is  to  be  converted.  This  track  identifier  is  supplied  by  the 
Movie  Toolbox.  If  this  parameter  contains  a  track  identifier,  your  component 
must  convert  only  the  specified  track. 
startTime 

The  starting  point  of  the  track  or  movie  segment  to  be  converted.  This  time 
value  is  expressed  in  the  movie's  time  coordinate  system. 

durati on 

The  duration  of  the  track  or  movie  segment  to  be  converted.  This  duration 
value  is  expressed  in  the  movie's  time  coordinate  system. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  component  must  be  prepared  to  perform  this  function  at  any  time.  You  should 
not  expect  that  any  of  your  component's  configuration  functions  will  be  called  first. 
If  your  component  can  write  data  to  a  handle,  be  sure  to  set  the 
canMovi  eExportHandl  es  flag  in  in  the  componentFl  ags  field  of  your  component's 
ComponentDescri pti on  (IV-2212)  structure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Exporting  Movie  Data"  (V-2858) 

Related  Java  Methods 

qui cktime . std . qt components . Movi e Exporter . toHandl e( ) 


MovieExportV  alidate 


Determines  whether  a  movie  export  component  can  export  all  the  data  for  a 
specified  movie  or  track. 


ComponentResul t  MovieExportValidate  ( 

Movi eExportComponent  ci  , 

Movie  theMovie, 

Track  onlyThisTrack, 

Boolean  * v a  1  id  ); 
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MovielmportDataRef 


ci 

A  movie  export  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
theMovi e 

The  movie  to  validate. 
onlyThi sT  rack 

A  track  within  the  movie  to  validate,  or  N I L  if  the  entire  movie  is  to  be  validated, 
valid 

A  pointer  toaBoolean  value.  If  the  data  for  the  movie  or  track  can  be  exported 
by  the  component,  the  value  is  TRUE. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  allows  an  application  to  determine  if  a  particular  movie  or  track  could 
be  exported  by  the  specified  movie  data  export  component.  The  movie  or  track  is 
passed  in  the  t h e M o v i  e  and  onlyThi  sTrack  parameters  as  they  are  passed  to 
MovieExportToFile  (11-934).  Although  a  movie  export  component  can  export  one  or 
more  media  types,  it  may  not  be  able  to  export  all  the  kinds  of  data  stored  in  those 
media.  The  Movi  eExportVal  i  date  function  allows  applications  to  get  this  additional 
information.  Movie  data  export  components  that  implement  this  function  also  set 
the  canMovi  eExportVal  i  dateMovi  e  flag  in  in  the  componentFl  ags  field  of  their 
ComponentDescri pti  on  (IV-2212)  structure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Exporting  Movie  Data"  (V-2858) 

Related  Java  Methods 

qui ckti me . std . qt components .Movi e Exporter . validate! ) 


MovielmportDataRef 


Undocumented 

ComponentResul t  MovielmportDataRef  ( 

Movi elmportComponent  ci  , 

Handle  dataRef, 

OSType  dataRefType, 

Movie  theMovie, 


11-938 


Inside  QuickTime:  Function  l-Q 


MovielmportDataRef 


T  rack 
T  rack 
TimeVal ue 
TimeVal ue 
1  ong 
1  ong 


targetTrack, 

*usedTrack, 

atTime, 

*addedDurati on , 
i  n FI  ags  , 
*outFlags  ); 


ci 

A  movie  import  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
dataRef 

The  data  reference  to  the  data  to  be  imported. 
dataRefType 

The  type  of  data  reference  in  the  dataRef  parameter. 
theMovi e 

A  movie  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e 
(11-1084). 
targetTrack 

Undocumented 
usedT  rack 

Undocumented 
atT i me 

Undocumented 
addedDurati on 

Undocumented 
i n FI  ags 

Flags  (see  below)  that  control  the  behavior  of  this  function. 
outFl  ags 

Flags  (see  below)  that  this  function  sets  on  return. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

nFlags  Constants 

movi elmportCreateT  rack 
Undocumented 
movi e Import  In  Pa ral 1  el 
Undocumented 


Inside  QuickTime:  Function  l-Q 


11-939 


MovielmportDoUserDialog 


movielmportMustUseTrack 

Undocumented 

movielmportWithldle 

Undocumented 

outFlags  Constants 

movielmportResultUsedMultipleTracks 

Undocumented 

movielmportResultNeedldles 
Undocumented 
movi e Import Res ul tCompl ete 
Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Related  Java  Methods 

qui  ckti  me .  std  .movi  es  .T  rack,  f  romMovi  elmporterDataRefO  , 
qui ckti me . std . qt components . Mo vi el mporter. from Data  Reft ) 


MovielmportDoUserDialog 


Requests  that  a  component  display  its  user  dialog  box. 

ComponentResul t  MovielmportDoUserDialog  ( 

Movi elmportComponent  ci  , 
const  FSSpec  *theFile, 

Handle  theData, 

Bool ean  *cancel ed  ) ; 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

theFi  1  e 

A  pointer  to  a  valid  file  specification.  If  the  import  request  pertains  to  a  file,  the 
application  must  specify  the  source  file  with  this  parameter  and  set  the  theData 
parameter  to  NIL.  If  the  request  is  for  a  handle,  this  parameter  is  set  to  NIL. 


11-940 
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MovielmportEstimateCompletionTime 


theData 

A  handle  to  the  data  to  be  imported.  If  the  import  request  pertains  to  a  handle, 
the  application  must  specify  the  source  of  the  data  with  this  parameter,  and  set 
the  t h e F i  1  e  parameter  to  NIL.  If  the  request  is  for  a  file,  this  parameter  is  set  to 
NIL. 
cancel ed 

A  pointer  to  a  Boolean  value.  Your  component  should  set  this  value  to  TRUE  if 
the  user  cancels  the  dialog  box;  otherwise,  set  it  to  FALSE. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

If  your  component  supports  a  user  dialog  box,  be  sure  to  set  the 
hasMovielmportUserlnterface  flag  in  the  component  FI  ags  field  of  your  component's 
ComponentDescri pti  on  (IV-2212)  structure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuring  Movie  Data  Import  Components"  (V-2856) 

Related  Java  Methods 

qui  cktime .  std  .  qt  components  .  Movi  e  Importer  .doUserDialogO 


MovielmportEstimateCompletionTime 

Undocumented 

ComponentResul t  Movi elmportEstimateCompl eti onTime  ( 

Movi elmportComponent  ci , 

TimeRecord  *time  ); 

ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

ti  me 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 


Inside  QuickTime:  Function  l-Q 


11-941 


MovielmportFile 


Programming  Info 

C  interface  file:  QuickTimeComponents.h 


MovielmportFile 


Imports  data  from  a  file,  using  a  movie  data  import  component. 


ComponentResul t  MovielmportFile  ( 


Movi e Import Component 
const  FSSpec 
Movi  e 
T  rack 
T  rack 
TimeVal ue 
TimeVal ue 
1  ong 
1  ong 


c  i  , 

*theFi  1  e , 
theMovi e , 
targetTrack, 
*usedT  rack , 
atTime, 

*addedDurati on , 
i  n FI  ags  , 
*outFlags  ); 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

theFi  1  e 

A  pointer  to  the  file  that  contains  the  data  that  is  to  be  imported  into  the  movie. 
This  file's  type  value  corresponds  to  your  component's  subtype  value. 

theMovi e 

The  movie  for  this  operation.  This  movie  identifier  is  supplied  by  the  Movie 
Toolbox.  Your  component  may  use  this  identifier  to  add  sample  data  to  the 
target  movie  or  to  obtain  information  about  the  movie. 
targetTrack 

The  track  that  is  to  receive  the  imported  data.  This  track  identifier  is  supplied 
by  the  Movie  Toolbox  and  is  valid  only  if  the  movi  elmportMustUseT rack  flag  in 
the  in  FI  ags  parameter  is  set  to  1. 

usedT  rack 

A  pointer  to  the  track  that  received  the  imported  data.  Your  component  returns 
this  track  identifier  to  the  Movie  Toolbox.  Your  component  needs  to  set  this 
parameter  only  if  you  operate  on  a  single  track  or  if  you  create  a  new  track.  If 
you  modify  more  than  one  track,  leave  the  field  referred  to  by  this  parameter 
unchanged. 


11-942 
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MovielmportFile 


atT i me 

The  time  corresponding  to  the  location  where  your  component  is  to  place  the 
imported  data.  This  time  value  is  expressed  in  the  movie's  time  coordinate 
system. 
addedDurati on 

A  pointer  to  the  duration  of  the  data  that  your  component  added  to  the  movie. 
Your  component  must  specify  this  value  in  the  movie's  time  coordinate  system. 

i n FI  ags 

Flags  (see  below)  that  specify  control  information  governing  the  import 
operation. 
outFl  ags 

Flags  (see  below)  that  identify  a  field  that  is  to  receive  status  information  about 
the  import  operation.  Your  component  sets  the  appropriate  flags  in  this  field 
when  the  operation  is  complete. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

nFlags  Constants 

movi elmportCreateT  rack 

Indicates  that  your  component  should  create  a  new  track  to  receive  the 
imported  data.  You  must  create  a  track  whose  type  value  corresponds  to  the 
media  type  you  have  specified  in  your  component's  manufacturer  code.  You 
should  return  the  track  identifier  of  this  new  track  in  the  field  referred  to  by  the 
usedT rack  parameter,  unless  you  create  more  than  one  track.  If  you  create  more 
than  one  track,  be  sure  to  set  the  movi elmportResul  tUsedMul  ti  pi  eT racks  flag  (in 
the  field  referred  to  by  the  out  FI  ags  parameter)  to  1.  If  the 
movi  elmportCreateT  rack  flag  is  set  to  1,  then  the  movi  elmportMustUseT  rack  flag 
is  set  to  0. 

movi elmportMustUseT  rack 

Indicates  that  your  component  must  use  an  existing  track.  That  track  is 
identified  by  the  targetTrack  parameter.  If  you  create  more  than  one  track,  be 
sure  to  set  the  movi  elmportResul  tUsedMul  ti  pi  eT  racks  flag  (in  the  field  referred 
to  by  the  outFl  ags  parameter)  to  1.  If  the  movi  elmportMustUseT  rack  flag  is  set  to 
1,  then  the  movi  elmportCreateT  rack  flag  is  set  to  0.  If  both  the 
movi  elmportCreateT  rack  and  movi  elmportMustUseT  rack  flags  are  set  to  0,  then 
you  are  free  to  use  any  existing  tracks  in  the  movie,  or  to  create  a  new  track  (or 
tracks)  as  needed, 
movi e Import  In  Pa ral 1  el 

Indicates  whether  you  are  to  perform  an  insert  operation  or  a  paste  operation. 
If  this  flag  is  set  to  0,  then  you  should  insert  the  imported  data  into  the  target 


M 
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11-943 


MovielmportGetAuxiliaryDataType 


track.  If  this  flag  is  set  to  1,  then  you  should  add  the  imported  data  to  the  track, 
overwriting  the  preexisting  open  space  currently  in  the  track.  Note  that  an 
application  may  use  Movi  elmportSetDurati  on  (11-957)  to  control  the  amount  of 
data  you  paste  into  a  movie.  If  the  movi  elmportMustUseT rack  flag  is  set  to  1,  then 
you  should  use  the  track  specified  by  the  targetTrack  parameter .  If  this  is  not 
possible,  return  an  appropriate  Movie  Toolbox  result  code. 

outFlags  Constants 

movielmportResultUsedMultipleTracks 

Indicates  that  your  component  modified  more  than  one  track  in  the  movie.  Set 
this  flag  to  1  if  your  component  places  imported  data  into  more  than  one  track. 
In  this  case,  you  do  not  need  to  update  the  field  referred  to  by  the  usedT rack 
parameter. 

movi elmportlnParal  lei 

Indicates  whether  you  performed  an  insert  operation  or  a  paste  operation.  Set 
this  flag  to  0  if  you  inserted  the  imported  data  into  the  target  track.  Set  this  flag 
to  1  if  you  added  the  imported  data  to  the  track,  overwriting  preexisting  open 
space  currently  in  the  track. 

Discussion 

Your  component  must  be  prepared  to  perform  this  function  at  any  time.  You  should 
not  expect  that  any  of  your  component's  configuration  functions  will  be  called  first. 
If  your  component  can  accept  data  from  a  file,  be  sure  to  set  the  canMovi  e  Import  Fi  1  es 
flag  in  the  componentFl  ags  field  of  your  component's  ComponentDescri  pti  on 
(IV-2212)  structure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Importing  Movie  Data"  (V-2855) 

Related  Java  Methods 

qui ckti me . std .movi es .T  rack. f romMovi elmporterFilet ) , 
qui ckti me . std . qt components . Mo vielmporter. from Filet ) 


MovielmportGet  Auxiliary  DataT  ype 


Returns  the  type  of  the  auxiliary  data  that  a  component  can  accept. 

ComponentResul t  Movi elmportGetAuxi 1 iaryDataType  ( 

Movi elmportComponent  ci  , 

OSType  *auxType  ) ; 


11-944 


Inside  QuickTime:  Function  l-Q 


MovielmportGetDontBlock 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
auxType 

A  pointer  to  the  type  of  auxiliary  data  it  can  import. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns  the  type  of  the  auxiliary  data  that  the  ci  component  can 
accept.  For  example,  calling  the  text  import  component  with  this  function  indicates 
that  the  text  import  component  will  use  '  styl  '  information  in  addition  to  '  TEXT ' 
data.  Note  that  if  component  includes  a  private  component  resource  holding  this 
MIME  data,  it  can  use  GetComponentResource  (1-394)  to  retrieve  it.  If  the  resource  is 
a  public  component  resource,  it  either  use  GetComponentPubl  i  cResource  (1-392)  with 
the  public  type  and  ID  or  GetComponentResource  with  the  private  type  and  ID. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Importing  Movie  Data"  (V-2855) 

Related  Java  Methods 

qui cktime . std . qt components . Movi e Importer . getAuxi 1 i ary Data Type! ) 


MovielmportGetDontBlock 


Undocumented 

ComponentResul t  MovielmportGetDontBlock  ( 
Movi elmportComponent  ci  , 

Boolean  *willBlock  ); 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
wi  1 1  B1  ock 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Inside  QuickTime:  Function  l-Q 
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MovielmportGetFileType 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


MovielmportGetFileType 


Allows  your  movie  data  import  component  to  tell  the  Movie  Toolbox  the 
appropriate  file  type  for  the  most-recently  imported  movie  file. 

ComponentResul t  MovielmportGetFileType  ( 

Movi elmportComponent  ci  , 

OSType  *f i 1 eType  ) ; 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDefaul tComponent  (11-1131). 

f  i  1 eType 

A  pointer  to  an  OSType  field.  Your  component  should  place  the  file  type  value 
that  best  identifies  the  movie  data  just  imported.  For  example,  Apple's  Audio 
CD  movie  data  import  component  sets  this  field  to  '  A I FF '  whenever  it  creates 
an  AIFF  file  instead  of  a  movie  file. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  should  implement  this  function  only  if  your  movie  data  import  component 
creates  files  other  than  QuickTime  movies.  By  default,  the  Movie  Toolbox  makes 
new  files  into  movies,  unless  you  override  that  default  by  providing  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Importing  Movie  Data"  (V-2855) 

Related  Java  Methods 

qui ckti me . std . qt components .Movielmporter.getFileTypeO 


11-946 
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MovielmportGetLoadState 


MovielmportGetLoadState 


Undocumented 

ComponentResul t  MovielmportGetLoadState  ( 

Movi elmportComponent  ci  , 

long  *importerLoadState  ); 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

i mporterLoadState 
Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


MovielmportGetMaxLoadedT  ime 


Undocumented 

ComponentResul t  Movi elmportGetMaxLoadedTime  ( 
Movi elmportComponent  ci  , 

TimeValue  *time  ); 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

ti  me 

A  pointer  to  a  value  containing  the  maximum  loaded  time. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 


Inside  QuickTime:  Function  l-Q 


11-947 


MovielmportGetMIMETypeList 


MovielmportGetMIMETypeList 


Returns  a  list  of  MIME  types  supported  by  the  movie  import  component. 

ComponentResul t  MovielmportGetMIMETypeList  ( 

Movi elmportComponent  ci  , 

QTAtomContai ner  *mimeInfo  ); 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDefaul tComponent  (11-1131). 

mi melnfo 

A  pointer  to  a  MIME  type  list,  a  QT  atom  container  that  contains  a  list  of  MIME 
types  supported  by  the  movie  import  component.  The  caller  should  dispose  of 
the  atom  container  when  finished  with  it. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  movie  import  component  can  support  MIME  types  that  correspond  to  formats 
it  supports.  To  make  a  list  of  these  MIME  types  available  to  applications  or  other 
software,  it  must  implement  this  function.  To  indicate  that  your  movie  import 
component  supports  this  function,  set  the  hasMovi  elmportMIMELi  st  flag  in  the 
componentFl  ags  field  of  the  ComponentDescri  pti  on  (IV-2212)  structure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Importing  Movie  Data"  (V-2855) 

Related  Java  Methods 

qui ckti me . std . qt components .Movielmporter.getMIMETypeListO, 
qui  ckti  me .  std  .movi  es  .  AtomContai  ner .  f  romMovi  elmporterMIMEO 


See  Also 

If  your  component  includes  a  private  component  resource  holding  the  MIME  data, 
it  can  use  GetComponentResource  (1-394)  to  retrieve  it.  If  the  resource  is  a  public 
component  resource,  it  can  use  either  GetComponentPubl  i  cResource  (1-392)  with  the 
public  type  and  ID  or  GetComponentResource  with  the  private  type  and  ID. 
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MovielmportGetSampleDescription 


Gets  the  current  sample  description  for  a  movie  import  component. 

ComponentResul t  Movi elmportGetSampl eDescri ptl on  ( 

Movi elmportComponent  ci  , 

Samp! eDescri pti onHandl e  *desc, 

OSType  *mediaType  ); 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

desc 

A  pointer  to  a  handle  to  a  Sampl  eDescri  pti  on  (IV-2414)  structure, 
medi aType 

A  pointer  to  the  type  of  the  data;  see  "Data  References"  (IV-2661). 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Sampl eDescri pti on . f romMovi e Importer! ) , 
qui cktime . std . qt components .Movi e Importer . get Sampl  eDescri  pti  on( ) , 
qui cktime . std . qt components .Movi e Importer . getMedi aType ( ) 

See  Also 

For  the  corresponding  set  function,  see  Movi  elmportSetSampl  eDescri  pti  on  (11-961). 


MovielmportGetSettingsAsAtomContainer 


Retrieves  the  current  settings  from  the  movie  import  component. 

ComponentResul t  Movi elmportGetSetti ngsAsAtomContainer  ( 

Movi elmportComponent  ci  , 

QTAtomContai ner  *settings  ); 


A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
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MovielmportHandle 


setti ngs 

The  address  where  the  reference  to  the  newly  created  atom  container  should  be 
stored  by  the  call. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  caller  is  responsible  for  disposing  of  the  returned  QT  atom  container. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Importing  Movie  Data"  (V-2855) 

Related  Java  Methods 

qui ckti me . std . qt components .Movielmporter.getlmportSetti ngsFromAtomContai ner 
qui ckti me . std .movi es . AtomContai ner . f romMovi elmporterSettingst ) 


MovielmportHandle 


Imports  data  from  a  handle,  using  a  movie  data  import  component. 


ComponentResul t  MovielmportHandle  ( 


Movi e Import Component 

Handl e 

Movi  e 

T  rack 

T  rack 

TimeVal ue 

TimeVal ue 

1  ong 

1  ong 


c  i  , 

dataH , 
theMovi e , 
targetTrack, 
*usedT  rack , 
atTime, 

*addedDurati on , 
i  n FI  ags  , 
*outFlags  ); 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 
dataH 

A  handle  to  the  data  that  is  to  be  imported  into  the  movie  identified  by  the 
theMovi  e  parameter.  The  data  contained  in  this  handle  has  a  data  type  value 
that  corresponds  to  your  component's  subtype  value.  Your  component  is  not 
responsible  for  disposing  of  this  handle. 


11-950 


Inside  QuickTime:  Function  l-Q 


MovielmportHandle 


theMovi e 

The  movie  for  this  operation.  This  movie  identifier  is  supplied  by  the  Movie 
Toolbox.  Your  component  may  use  this  identifier  to  add  sample  data  to  the 
target  movie,  or  to  obtain  information  about  the  movie. 
targetTrack 

The  track  that  is  to  receive  the  imported  data.  This  track  identifier  is  supplied 
by  the  Movie  Toolbox  and  is  valid  only  if  the  movi  elmportMustUseT rack  flag  in 
the  i  n  FI  ags  parameter  is  set  to  1. 

usedT  rack 

A  pointer  to  the  track  that  received  the  imported  data.  Your  component  returns 
this  track  identifier  to  the  Movie  Toolbox.  Your  component  needs  to  set  this 
parameter  only  if  you  operate  on  a  single  track  or  if  you  create  a  new  track.  If 
you  modify  more  than  one  track,  leave  the  field  referred  to  by  this  parameter 
unchanged. 
atT i me 

The  time  corresponding  to  the  location  where  your  component  is  to  place  the 
imported  data.  This  time  value  is  expressed  in  the  movie's  time  coordinate 
system. 
addedDurati on 

A  pointer  to  the  duration  of  the  data  that  your  component  added  to  the  movie. 
Your  component  must  specify  this  value  in  the  movie's  time  coordinate  system. 

i n FI  ags 

Flags  (see  below)  that  specify  control  information  governing  the  import 
operation. 
outFl  ags 

Flags  (see  below)  that  receive  status  information  about  the  import  operation. 
Your  component  sets  the  appropriate  flags  in  this  field  when  the  operation  is 
complete. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

nFlags  Constants 

movi elmportCreateT  rack 

Indicates  that  your  component  should  create  a  new  track  to  receive  the 
imported  data.  You  must  create  a  track  whose  type  value  corresponds  to  the 
media  type  that  you  have  specified  in  your  component's  manufacturer  code. 
You  should  return  the  track  identifier  of  this  new  track  in  the  field  referred  to 
by  the  usedTrack  parameter,  unless  you  create  more  than  one  track.  If  you  create 
more  than  one  track,  be  sure  to  set  the  movi  elmportResul  tUsedMul  ti  pi  eT racks 
flag  in  the  field  referred  to  by  the  out  FI  ags  parameter  to  1.  If  the 


M 


Inside  QuickTime:  Function  l-Q 


11-951 


MovielmportHandle 


movi  elmportCreateTrack  flag  is  set  to  1,  then  the  movl  elmportMustUseTrack  flag 
is  set  to  0. 

movi elmportMustUseTrack 

Indicates  that  your  component  must  use  an  existing  track.  That  track  is 
identified  by  the  targetTrack  parameter.  If  you  create  more  than  one  track,  be 
sure  to  set  the  movi  e  Import  Res  ul  tUs  edMulti  pi  eT  racks  flag  in  the  field  referred  to 
by  the  outFl  ags  parameter  to  1.  If  the  movi  elmportMustUseT rack  flag  is  set  to  1, 
then  the  movi  elmportCreateT rack  flag  is  set  to  0.  If  both  the 
movi  elmportCreateT  rack  and  movi  elmportMustUseT  rack  flags  are  set  to  0,  then 
you  are  free  to  use  any  existing  tracks  in  the  movie  or  to  create  a  new  track  (or 
tracks)  as  needed. 

movi elmportlnParal  lei 

Indicates  whether  you  are  to  perform  an  insert  operation  or  a  paste  operation. 
If  this  flag  is  set  to  0,  then  you  should  insert  the  imported  data  into  the  target 
track.  If  this  flag  is  set  to  1,  then  you  should  add  the  imported  data  to  the  track, 
overwriting  preexisting  open  space  currently  in  the  track.  Note  that  an 
application  may  use  Movi  elmportSetDurati  on  (11-957)  to  control  the  amount  of 
data  you  paste  into  a  movie.  If  the  movi  elmportMustUseT  rack  flag  is  set  to  1,  then 
you  should  use  the  track  specified  by  the  targetTrack  parameter.  If  this  is  not 
possible,  return  an  appropriate  Movie  Toolbox  result  code. 

outFlags  Constants 

movielmportResultUsedMultipleTracks 

Indicates  that  your  component  modified  more  than  one  track  in  the  movie.  Set 
this  flag  to  1  if  your  component  places  imported  data  into  more  than  one  track. 
In  this  case,  you  do  not  need  to  update  the  field  referred  to  by  the  usedT rack 
parameter. 

movi elmportlnParal  lei 

Indicates  whether  you  performed  an  insert  operation  or  a  paste  operation.  Set 
this  flag  to  0  if  you  inserted  the  imported  data  into  the  target  track.  Set  this  flag 
to  1  if  you  added  the  imported  data  to  the  track,  overwriting  preexisting  open 
space  currently  in  the  track. 

Discussion 

Your  component  must  be  prepared  to  perform  this  function  at  any  time.  You  should 
not  expect  that  any  of  your  component's  configuration  functions  will  be  called  first. 
If  your  component  can  accept  data  from  a  handle,  be  sure  to  set  the 
canMovi  elmportHandl  es  flag  in  your  component's  componentFl  ags  field. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


11-952 


Inside  QuickTime:  Function  l-Q 


Movielmportldle 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Importing  Movie  Data"  (V-2855) 

Related  Java  Methods 

qui ckti me . std .movi es . Track. f romMovi elmporterHandl e( ) , 
qui cktime . std . qt components .Movi e Importer . f romHandl e( ) 


Movielmportldle 


Undocumented 

ComponentResul t  Movielmportldle  ( 

Movi elmportComponent  ci  , 

long  inFlags, 

long  *outFlags  ); 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

i  n FI  ags 

Undocumented 
outFl  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inFlags  Constants 

Undocumented 

Undocumented 

outFlags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


Inside  QuickTime:  Function  l-Q 


11-953 


MovielmportSetAuxiliaryData 


MovielmportSetAuxiliaryData 


Provides  additional  data  to  a  component. 

ComponentResul t  MovielmportSetAuxiliaryData  ( 
Movi elmportComponent  ci  , 

Handle  data, 

OSType  handleType  ); 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

data 

A  handle  to  the  additional  data.  Your  component  should  not  dispose  of  this 
handle.  Be  sure  to  copy  any  data  you  need  to  keep, 
handl eType 

The  type  of  data  in  the  specified  handle. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  component  should  expect  the  application  to  call  this  function  before  the 
import  process  begins. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuring  Movie  Data  Import  Components"  (V-2856) 

Related  Java  Methods 

qui ckti me . std . qt components . Movi e Importer . set Auxi 1 i ary Data ( ) 


MovielmportSetChunkSize 


The  amount  of  data  a  component  works  with  at  a  time. 

ComponentResul t  MovielmportSetChunkSize  ( 

Movi elmportComponent  ci  , 

1 ong  chunkSi ze  ) ; 


11-954 


Inside  QuickTime:  Function  l-Q 


MovielmportSetDimensions 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
chunkSi ze 

The  number  of  seconds  of  data  your  movie  data  import  component  places  into 
each  chunk  of  movie  data.  This  parameter  may  not  be  set  to  a  value  less  than  1. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Generally,  your  component  should  determine  a  reasonable  default  chunk  size, 
based  on  the  type  of  data  you  are  importing.  However,  you  may  choose  to  allow 
applications  to  override  your  default  value.  This  can  be  especially  useful  for  sound 
data,  where  the  chunk  size  affects  the  quality  of  sound  playback. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuring  Movie  Data  Import  Components"  (V-2856) 

Related  Java  Methods 

qui cktime . std . qt components . Movi e Importer . setChunkSi  ze( ) 


MovielmportSetDimensions 


Specifies  a  new  track's  spatial  dimensions. 

ComponentResul t  MovielmportSetDimensions  ( 
Movi  elmportComponent  ci  , 

Fixed  width. 

Fixed  height  ); 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

wi  dth 

The  width,  in  pixels,  of  the  track  rectangle.  This  parameter,  along  with  the 
height  parameter,  specifies  a  rectangle  that  surrounds  the  image  that  is  to  be 
displayed  when  the  current  media  is  played.  This  value  corresponds  to  the  x 
coordinate  of  the  lower-right  corner  of  the  rectangle,  and  it  is  expressed  as  a 
fixed-point  number. 


Inside  QuickTime:  Function  l-Q 


11-955 


MovielmportSetDontBlock 


hei ght 

The  height,  in  pixels,  of  the  track  rectangle.  This  value  corresponds  to  the  y 
coordinate  of  the  lower-right  corner  of  the  rectangle,  and  it  is  expressed  as  a 
fixed-point  number. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuring  Movie  Data  Import  Components"  (V-2856) 

Related  Java  Methods 

qui  ckti  me .  std .  qt  components  .Movielmporter.setDimensionsO 


See  Also 

If  you  want  to  change  the  track's  matrix,  call  SetTrackMatri x  (III— 1662)  after 
performing  the  import  operation. 


MovielmportSetDontBlock 


Undocumented 

ComponentResult  MovielmportSetDontBlock  ( 
Movi elmportComponent  ci  , 

Bool ean  dontBl ock  ) ; 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

dontBl ock 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 


11-956 


Inside  QuickTime:  Function  l-Q 


MovielmportSetDuration 


MovielmportSetDuration 


Controls  the  duration  of  the  data  that  a  component  pastes  into  the  target  movie. 

ComponentResul t  MovielmportSetDuration  ( 

Movi  elmportComponent  ci  , 

TimeValue  duration  ); 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

durati on 

The  duration  in  the  movie's  time  scale.  If  this  parameter  is  set  to  0,  then  you 
may  paste  any  amount  of  movie  data  that  is  appropriate  for  the  data  to  be 
imported. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

If  your  component  supports  paste  operations  (that  is,  your  component  allows  the 
application  to  set  the  movi  elmportlnParal  1  el  flag  to  1  with  the  Movi  elmportHandl  e 
(11-950)  or  Movi  elmportFi  1  e  (11-942)  function),  then  you  must  support  this  function. 
If  an  application  calls  this  function  and  sets  a  duration  limit,  you  must  abide  by  that 
limit.  This  function  is  not  valid  for  insert  operations  (where  the 
movi  elmportlnParal  1  el  flag  is  set  to  0). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Configuring  Movie  Data  Import  Components"  (V-2856) 

Related  Java  Methods 

qui cktime . std . qt components .Movi e Importer . set Duration!) 


MovielmportSetFromScrap 


Indicates  that  the  source  data  resides  on  the  scrap. 

ComponentResul t  MovielmportSetFromScrap  ( 

Movi elmportComponent  ci  , 

Boolean  fromScrap  ); 


Inside  QuickTime:  Function  l-Q 


11-957 


MovielmportSetMediaFile 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 
f romScrap 

Set  to  TRUE  if  the  data  originated  on  the  scrap;  otherwise,  set  to  FALSE. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuring  Movie  Data  Import  Components"  (V-2856) 

Related  Java  Methods 

qui ckti me . std . qt components .Movielmporter . set FromSc rapt ) 


MovielmportSetMediaFile 


Specifies  a  media  file  that  is  to  receive  the  imported  movie  data. 

ComponentResul t  MovielmportSetMediaFile  ( 

Movi elmportComponent  ci  , 

A1 i asHandl e  alias); 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

alias 

The  media  file  that  is  to  receive  the  imported  movie  data.  Your  component 
must  make  a  copy  of  this  parameter.  You  should  not  dispose  of  it. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Configuring  Movie  Data  Import  Components"  (V-2856) 

Related  Java  Methods 

qui ckti me . std . qt components .Movielmporter. set Med iaFilet) 


11-958 


Inside  QuickTime:  Function  l-Q 


MovielmportSetOffsetAndLimit 


MovielmportSetOffsetAndLimit 


Specifies  location  and  size  of  data  that  should  be  imported. 

ComponentResul t  MovielmportSetOffsetAndLimit  ( 

Movi elmportComponent  ci  , 

unsigned  long  offset, 

unsigned  long  limit  ); 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
offset 

A  byte  offset  into  the  file  that  indicates  where  the  import  operation  begins. 

1  i  mi  t 

A  byte  offset  into  the  file  that  indicates  the  last  data  in  the  file  that  can  be 
imported. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  badComponentSel  ector  if  the 
movie  import  component  does  not  support  this  function.  Returns 
n  o  E  r  r  if  there  is  no  error. 

Discussion 

Typically,  this  function  is  used  when  the  data  is  from  a  part  of  a  file  rather  than  the 
entire  file.  It  is  especially  useful  when  one  file  format  is  embedded  in  another;  it 
allows  your  application  to  skip  header  data  for  the  enclosing  file  and  begin 
importing  data  at  the  start  of  the  desired  format. 

Special  Considerations 

Not  all  movie  import  components  support  this  function.  Those  that  do  include  the 
movie  import  components  for  the  kQTFi  1  eTypeAI  FF,  kQTFi  1  eTypeWave,  and 
kQTFi  1  eTypeMuLaw  file  types.  Those  that  do  not  return  the  badComponentSel  ector 
result  code  in  response  to  a  this  call. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Importing  Movie  Data"  (V-2855) 

Related  Java  Methods 

qui cktime . std . qt components .Movi e Importer . setOff set And  Li  mi t( ) 


Inside  QuickTime:  Function  l-Q 


11-959 


MovieImportSetOffsetAndLimit64 


MovieImportSetOffsetAndLimit64 


Specifies  location  and  size  of  data  that  should  be  imported  from  a  file. 

ComponentResul t  Movi elmportSetOffsetAndLi mi t64  ( 

Movi elmportComponent  ci  , 

const  wide  *offset, 

const  wide  *1 i mi t  ) ; 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 
offset 

A  byte  offset  into  the  file  that  indicates  where  the  import  operation  begins, 
limit 

A  byte  offset  into  the  file  that  indicates  the  last  data  in  the  file  that  can  be 
imported. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  badComponentSel  ector  if  the 
movie  import  component  does  not  support  this  function.  Returns 
n  o  E  r  r  if  there  is  no  error. 

Discussion 

This  function  serves  the  same  purpose  as  Movi  elmportSetOffsetAndLi  mi  t  (11-959). 
The  only  difference  is  that  the  offset  and  limit  can  hold  64-bit  offsets.  This  function 
is  especially  useful  when  one  file  format  is  embedded  in  another;  it  allows  your 
application  to  skip  header  data  for  the  enclosing  file  and  begin  importing  data  at  the 
start  of  the  desired  format. 

Special  Considerations 

Not  all  movie  import  components  support  this  function.  Those  that  do  not  return 
the  badComponentSel  ector  result  code.  If  this  function  is  not  implemented  and  the 
offset  and  limit  can  be  expressed  using  32-bit  offsets,  MovielmportSetOffsetAndLimit 
(11-959)  should  be  tried. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Importing  Movie  Data"  (V-2855) 


11-960 


Inside  QuickTime:  Function  l-Q 


MovielmportSetProgressProc 


MovielmportSetProgressProc 


Assigns  a  movie  progress  function. 

ComponentResul t  MovielmportSetProgressProc  ( 
Movi  elmportComponent  ci  , 

Movi eProgressUPP  proc, 

long  ref con  ); 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

proc 

A  pointer  to  the  application's  Movi  eProgressProc  (III— 2105)  callback.  If  this 
parameter  is  set  to  N I L,  the  application  is  removing  its  progress  function.  In  this 
case,  your  component  should  stop  calling  the  progress  function, 
ref con 

Specifies  a  reference  constant.  Your  component  should  pass  this  constant  back 
to  the  application's  progress  function  whenever  you  call  that  function.  The 
application  may  use  this  parameter  to  point  to  a  data  structure  containing  any 
information  the  callback  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  Movi  eProgressProc  (III— 2105)  callback  interface  not  only  allows  you  to  report 
progress  to  the  application,  but  also  allows  the  application  to  cancel  the  request. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui ckTi  meComponents  .  h 

Programming  summary:  "Configuring  Movie  Data  Import  Components"  (V-2856) 

Related  Java  Methods 

qui cktime . std . qt components .Movi e Importer . set Progress Proc!) 


MovielmportSetSampleDescription 

Provides  a  Sampl  eDescri  pti  on  (IV-2414)  structure  to  a  movie  data  import 
component. 

ComponentResul t  Movi elmportSetSampl eDescri pti on  ( 


Inside  QuickTime:  Function  l-Q 


11-961 


MovielmportSetSampleDuration 


Movi e Import Component 

SampleDescriptionHandle 

OSType 


ci , 
desc , 

medi aType  ) ; 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDefaul tComponent  (11-1131). 

desc 

A  handle  to  a  Sampl  e  Description  (IV-2414)  structure.  Your  component  must  not 
dispose  of  this  handle.  If  you  want  to  save  any  data  from  the  structure,  be  sure 
to  copy  it  at  this  time. 

medi aType 

The  type  of  sample  description  referred  to  by  the  desc  parameter.  If  the  desc 
parameter  refers  to  an  ImageDescri  pti  on  (IV-2285)  structure,  this  parameter  is 
set  to  Vi  deoMedi  aType  ('vide');  for  SoundDescri  pti  on  (IV-2449)  structures,  this 
parameter  is  set  to  Sound  Medi  aType  ( '  soun '). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuring  Movie  Data  Import  Components"  (V-2856) 

Related  Java  Methods 

qui  ckti  me .  std .  qt  components  .Movielmporter.setSampleDescriptionO 


See  Also 

For  the  corresponding  get  function,  see  Movi  elmportGetSampl  eDescri  pti  on  (11-949). 


MovielmportSetSampleDuration 


Sets  the  sample  duration  for  new  samples  to  be  created  with  a  component. 

ComponentResul t  MovielmportSetSampleDuration  ( 

Movi elmportComponent  ci  , 

T imeVal ue  durati on , 

TimeScale  scale  ) ; 


A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 


11-962 


Inside  QuickTime:  Function  l-Q 


MovielmportSetSettingsFromAtomContainer 


durati on 

The  sample  duration  in  units  specified  by  the  scale  parameter, 
scale 

The  time  scale  for  the  duration  value.  This  may  be  any  arbitrary  time  scale;  that 
is,  it  may  not  correspond  to  the  movie's  time  scale.  You  should  convert  this  time 
scale  to  the  movie's  time  scale  before  using  the  duration  value,  using 
ConvertTimeScal e  (1-138). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuring  Movie  Data  Import  Components"  (V-2856) 

Related  Java  Methods 

qui cktime . std . qt components . Movi e Importer . setSampleDurationl) 


MovielmportSetSettingsFromAtomContainer 


Sets  the  movie  import  component's  current  configuration  from  the  passed  settings 
data. 

ComponentResul t  Movi elmportSetSetti ngsFromAtomContai ner  ( 

Movi elmportComponent  ci  , 

QTAtomContai ner  settings  ); 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

setti ngs 

A  QT  atom  container  containing  settings. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  settings  QT  atom  container  may  contain  atoms  other  than  those  expected  by  the 
particular  component  type  or  may  be  missing  certain  atoms.  The  function  uses  only 
those  settings  it  understands. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Function  l-Q 


11-963 


MovielmportValidate 


Programming  Info 

C  interface  file:  QuickTimeComponents.h 

Programming  summary:  "Importing  Movie  Data"  (V-2855) 

Related  Java  Methods 

qui ckti me . std . qt components .Movielmporter.setlmportSetti ngsFromAtomContai ner 


Movielmport  V  alidate 


Allows  your  movie  data  import  component  to  validate  the  data  to  be  passed  to  your 
component. 

ComponentResul t  MovielmportValidate  ( 

Movi elmportComponent  ci  , 
const  FSSpec  *theFile, 

Handle  theData, 

Boolean  *valid  ); 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 
t  h  e  F  i  1  e 

An  FSSpec  (IV-2262)  structure  that  defines  the  file  to  validate  if  the  importer 
imports  from  files. 

theData 

The  data  to  validate  if  the  importer  imports  from  handles, 
valid 

A  pointer  toaBoolean  value.  If  the  data  or  file  can  be  imported,  the  value 
returned  is  TRUE.  Otherwise,  it  returns  FALSE. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Movie  import  components  can  implement  this  function  to  allow  applications  to 
determine  if  a  given  file  or  handle  to  data  is  acceptable  for  a  particular  import 
component.  As  this  function  may  be  called  on  many  files,  the  validation  process 
should  be  as  fast  as  possible. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


11-964 


Inside  QuickTime:  Function  l-Q 


MovielmportValidateDataRef 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Importing  Movie  Data"  (V-2855) 

Related  Java  Methods 

qui cktime . std . qt components . Movi e Importer . validate!) 


See  Also 

See  MovielmportValidateDataRef  (11-965). 


MovielmportValidateDataRef 


Validates  the  data  file  indicated  by  the  data  reference. 

ComponentResul t  MovielmportValidateDataRef  ( 

Movi elmportComponent  ci  , 

Handle  dataRef, 

OSType  dataRefType, 

UInt8  * v a  1  id  ); 


ci 

A  movie  data  import  component  instance.  Your  software  obtains  this  reference 
from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

dataRef 

The  data  reference  to  the  file  to  be  validated. 
dataRefType 

The  type  of  data  reference  for  the  dataRef  parameter, 
valid 

A  pointer  to  a  U I nt8  value.  If  the  data  or  file  cannot  be  imported,  the  value 
returned  should  be  0.  Otherwise,  it  should  be  set  to  128. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Movie  import  components  can  implement  this  function  to  allow  applications  to 
determine  if  a  given  file  referenced  by  a  data  reference  is  acceptable  for  a  particular 
import  component.  The  data  reference  can  refer  to  any  data  for  which  there  is  a 
suitable  data  handler  component  installed  and  available  to  QuickTime.  As  this 
function  may  be  called  on  many  files,  the  validation  process  should  be  as  fast  as 
possible.  Furthermore,  the  importer  should  probably  limit  the  amount  of  reading  it 
performs,  especially  when  the  data  handler  refers  to  data  on  the  Internet. 


Inside  QuickTime:  Function  l-Q 


11-965 


MovieMediaGetChildDoMCActionCallback 


Special  Considerations 

Unlike  MovielmportVali  date  (11-964),  the  valid  parameter  for  this  function  is  a  value 
that  can  be  interpreted  as  the  degree  to  which  the  importer  can  interpret  the  file's 
contents.  In  all  cases,  returning  0  indicates  the  file  cannot  be  interpreted  by  the 
importer.  However,  other  non-zero  values  can  be  used  to  determine  the  relative 
weighting  between  multiple  importers  that  can  import  a  particular  kind  of  file.  For 
now,  it  is  best  to  return  either  0  or  128  only. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Importing  Movie  Data"  (V-2855) 

See  Also 

See  Movi elmportVal  i date  (11-964). 


MovieMediaGetChildDoMCActionCallback 


Undocumented 

ComponentResul t  Movi eMedi aGetChi 1 dDoMCActi onCal 1  back  ( 
MediaHandler  mh, 

DoMCActi onUPP  *doMCActi onCal IbackProc, 

1 ong  *refcon  ) ; 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
doMCActi onCal IbackProc 

A  pointer  to  a  Universal  Procedure  Pointer  that  accesses  a  DoMCActi  onProc 
(III— 2082)  callback. 

refcon 

A  pointer  to  a  reference  constant  to  be  passed  to  your  callback.  Use  this  constant 
to  point  to  a  data  structure  containing  any  information  your  callback  needs. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4.1. 


11-966 


Inside  QuickTime:  Function  l-Q 


MovieMediaGetChildMovieDataReference 


Programming  Info 

C  interface  file:  Movi  es  .  h 


MovieMediaGetChildMovieDataReference 


Undocumented 


ComponentResul t  MovieMedi aGetChi 1 dMovi eDataReference  ( 


Medi aHandl er 

QTAtomID 

short 

OSType 

Handl e 

QTAtomID 

short 


mh , 

dataRef ID, 
dataRef Index, 
*dataRefType, 
*dataRef , 

*dataRef IDOut, 
*dataRef IndexOut  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
dataRef ID 

Undocumented 
dataRef Index 

Undocumented 

dataRefType 

Undocumented 

dataRef 

Undocumented 
dataRef IDOut 

Undocumented 
dataRef IndexOut 
Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


Inside  QuickTime:  Function  l-Q 


11-967 


MovieMediaGetCurrentMovieProperty 


See  Also 

For  the  corresponding  set  function,  see  Movi  eMedi  aSetChi  1  dMovi  eDataReference 
(11-971). 


MovieMediaGetCurrentMovieProperty 


Retrieves  current  properties  from  a  media  handler's  movie. 

ComponentResul t  Movi eMedi aGetCurrentMovi eProperty  ( 
MediaHandler  mh, 

OSType  whi chProperty , 

voi d  *val ue  ) ; 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
whi chProperty 

A  constant  (see  below)  that  designates  the  property  to  be  retrieved, 
val  ue 

A  pointer  to  the  returned  property  value. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

whichProperty  Constants 

kMovi eProperty Duration 

The  movie's  duration.  The  value  of  the  constant  is  ’  dura  ’ . 
kMovi ePropertyT i meScal e 

The  movie's  time  scale.  The  value  of  the  constant  is  '  ti  ms ' . 
kMovi ePropertyT  i  me 

The  movie's  current  time.  The  value  of  the  constant  is  '  ti  mv ' . 
kMovi eProperty Natural  Bounds 

The  movie's  boundary  rectangle,  returned  as  a  Rect  (IV-2399)  structure.  The 
value  of  the  constant  is  '  natb ' . 

kMovi e Property Mat ri x 

The  movie's  matrix,  returned  as  a  Matri  xRecord  (IV-2304)  structure.  The  value 
of  the  constant  is  '  mt  rx ' . 

kMovi ePropertyT  rackLi  st 

A  pointer  to  the  movie's  track  list,  returned  as  a  long  integer.  The  value  of  the 
constant  is  '  1 1  s  t ' . 


11-968 
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MovieMediaGetCurrentTrackProperty 


Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


MovieMediaGetCurrentTrackProperty 


Retrieves  the  media  type  property  from  a  media  handler's  track. 


comporieri  LKesu  i  i  i» 
Medi aHandl er 
1  ong 
OSType 
void 


mh , 

trackID, 
whi  chProperty , 
*value  ); 


( 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
trackID 

The  ID  value  of  the  track  for  this  operation, 
whi chProperty 

A  constant  (see  below)  that  designates  the  property  to  be  retrieved.  Only  the 
track's  media  type  property  constant  is  currently  defined. 

val  ue 

A  pointer  to  the  returned  property  value. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

whichProperty  Constant 

kT  rackPropertyMedi a Type 

The  track's  media  type,  returned  as  an  OSType  value.  The  value  of  the  constant 
is  'mtyp'. 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es  .  h 
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11-969 


MovieMediaGetDoMCActionCallback 


MovieMediaGetDoMCActionCallback 


Gets  a  DoMCActi  onProc  (III— 2082)  callback  for  a  media. 

ComponentResul t  Movi eMedi aGetDoMCActi onCa  VI  back  ( 
MediaHandler  mh, 

DoMCActi onUPP  *doMCActi onCallbackProc, 

1 ong  *refcon  ) ; 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
doMCActi onCallbackProc 

A  pointer  to  a  Universal  Procedure  Pointer  that  accesses  a  DoMCActi  onProc 
(III— 2082)  callback, 
refcon 

A  pointer  to  a  reference  constant  to  be  passed  to  your  callback.  Use  this  constant 
to  point  to  a  data  structure  containing  any  information  your  callback  needs. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es .  h 


MovieMediaLoadChildMovieFromDataReference 


Undocumented 

ComponentResul t  Movi eMediaLoadChi 1 dMovi eFromDataReference  ( 
MediaHandler  mh, 

QTAtomID  dataRefID  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
dataRefID 

Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 


11-970 


Inside  QuickTime:  Function  l-Q 


MovieMediaSetChildMovieDataReference 


result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


MovieMediaSetChildMovieDataReference 

Undocumented 

ComponentResul t  MovieMedi aSetChi 1 dMovi eDataReference  ( 

MediaHandler  mh, 

QTAtomID  dataRefID, 

OSType  dataRefType, 

Handle  dataRef  ); 

mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
dataRefID 

Undocumented 

dataRefType 

Undocumented 

dataRef 

Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

See  Also 

For  the  corresponding  get  function,  see  Movi  eMedi  aGetChi  1  dMovi  eDataReference 
(11-967). 
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II-971 


MovieSearchText 


MovieSearchT  ext 


Searches  for  text  in  a  movie. 


OSErr  MovieSearc 
Movi  e 
Ptr 
1  ong 
1  ong 
T  rack 
TimeVal ue 
1  ong 


hText  ( 
theMovi e , 
text , 
size, 

searchFl ags , 
*searchTrack, 
*searchTime, 
*searchOffset  ) ; 


theMovi e 

A  movie  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e 
(11-1084). 


text 

The  text  to  be  searched  for. 


si  ze 

The  size  of  the  text. 
searchFl ags 

Flags  (see  below)  that  narrow  the  search  process. 
searchTrack 

On  return,  a  pointer  to  the  found  track. 
searchTime 

On  return,  a  pointer  to  the  found  time. 
searchOffset 

On  return,  a  pointer  to  the  found  offset  to  the  text. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

searchFlags  Constants 

s ea r c hText Don tGoToFoundTi  me 

By  default,  MovieSearchText  automatically  moves  to  the  sample  containing  the 
found  text  and  highlights  it;  this  flag  and  searchTextDontHi  1  i  teFoundText 
override  those  default  behaviors. 

searchTextDontHi 1 i teFoundText 
Don't  highlight  the  found  text. 


11-972 
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MoviesTask 


searchTextOneTrackOnly 

Search  the  track  designated  bysearchTrack  only. 
searchTextEnabl edTracksOnly 
Search  only  enabled  tracks. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . searchText( ) 


MoviesTask 


Services  active  movies. 

void  MoviesTask  ( 

Movie  theMovie, 

long  maxMi  1 1 iSecToUse  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi eFromHandl  e  (11-1084).  If  you  set  this  parameter  to  NIL,  the  Movie 
Toolbox  services  all  of  your  active  movies. 

maxMi 1 1 i SecToUse 

Determines  the  maximum  number  of  milliseconds  that  MoviesTaskcan  work 
before  returning.  If  this  parameter  is  0,  Movi  esTask  services  every  active  movie 
exactly  once  and  then  returns.  If  the  parameter  is  nonzero,  Movi  esTask  services 
as  many  movies  as  it  can  in  the  allotted  time  before  returning.  Once  the 
MoviesTask  function  starts  servicing  a  movie,  it  cannot  stop  until  it  has 
completely  met  the  requirements  of  the  movie.  Consequently,  the  MoviesTask 
function  may  execute  for  a  longer  time  than  that  specified  in  maxMi  1 1  i  SecToUse. 
However,  the  function  does  not  start  servicing  a  new  movie  if  the  time  specified 
by  maxMi  1 1  i  SecToUse  has  elapsed.  The  preferred  way  to  use  Movi  esTask  is  to  set 
the  maxMi  1 1  i  SecToUse  parameter  to  0;  however,  if  you  just  want  to  play  one 
movie,  you  can  call  Movi  esTask  on  that  one.  If  your  rate  is  0,  MoviesTask  draws 
that  frame  and  no  other. 

function  result  You  can  access  error  returns  from  this  function  through 
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11-973 


MusicDerivedCloseResFile 


GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

You  should  call  MoviesTaskas  often  as  possible  from  your  application's  main  event 
loop.  Note  that  you  should  call  this  function  after  you  have  performed  your  own 
event  processing.  Movi  esTask  services  only  active  movies,  and  only  enabled  tracks 
within  those  active  movies. 

Special  Considerations 

Note  that  the  Movi  esTask  function  services  only  your  movies.  Your  application  must 
give  other  applications  the  opportunity  to  call  Movi  esTask  for  their  movies. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es . h 

Programming  summary:  "Movies  and  Your  Event  Loop"  (V-2720) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . taskAl 1 ( ) ,  quicktime.std.movies.Movie.taskO 


See  Also 

Use  SetMovi  eActi  ve  (III— 1609)  and  SetT rackEnabl  ed  (III— 1658)  to  enable  and  disable 
movies  and  tracks. 


MusicDerivedCloseResFile 


Closes  a  music  movie  resource  file. 

ComponentResul t  MusicDerivedCloseResFile  ( 
Musi cComponent  me, 

short  resRef Num  ) ; 


me 

A  music  component.  Your  software  obtains  this  reference  when  calling 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

resRef Num 

The  resource  file  to  be  closed.  Your  application  obtains  this  value  from  the 
OpenMovi eFi  1  e  (11-1133)  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


11-974 
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MusicDerivedMIDISend 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 


MusicDerivedMIDISend 


Sends  a  MIDI  packet  to  a  music  component. 

ComponentResul t  MusicDerivedMIDISend  ( 
Musi cComponent  me, 

MusicMIDIPacket  *packet  ); 


me 

A  music  component.  Your  software  obtains  this  reference  when  calling 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131)  function. 

packet 

A  pointer  to  the  music  MIDI  packet  to  be  sent. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 


MusicDerivedOpenResFile 


Opens  the  music  resource  file  for  a  music  component. 

ComponentResul t  MusicDerivedOpenResFile  ( 

Musi cComponent  me  ); 


me 

A  music  component.  Your  software  obtains  this  reference  when  calling 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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MusicDerivedSetlnstrument 


Programming  Info 

C  interface  file:  QuickTimeMusic.h 


MusicDerivedSetlnstrument 


The  complete  instrument  defined  by  the  Part  structure  to  the  synthesizer. 

ComponentResul t  MusicDerivedSetlnstrument  ( 

Musi cComponent  me, 

long  partNumber, 

GCPart  *p  ); 


me 

The  instance  of  the  generic  music  component.  Your  software  obtains  this 
reference  when  calling  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent 
(11-1131). 

partNumber 

The  number  of  the  part  for  this  operation. 

P 

A  pointer  to  the  part  for  this  operation. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Calling  Generic  Music  Component  Clients"  (V-2925) 


MusicDerivedSetKnob 


Called  when  any  of  the  synthesizer's  knobs  are  altered. 


ComponentResul t  MusicDerivedSetKnob  ( 


Musi cComponent 
1  ong 
1  ong 
1  ong 
1  ong 
GCPart 

GenericKnobDescription 


me , 

knobType , 
knobNumber , 
knobVal ue , 
partNumber , 
*P. 

*gkd  ); 


11-976 


Inside  QuickTime:  Function  l-Q 


MusicDerivedSetKnob 


me 

The  instance  of  the  generic  music  component.  Your  software  obtains  this 
reference  when  calling  OpenComponent  (11-1130)  or  OpenDefaul  tComponent 
(11-1131). 

knobType 

The  type  of  knob  that  has  been  altered  (see  below). 
knobNumber 

The  number  of  the  knob  that  has  been  altered. 
knobVal ue 

The  new  value  of  the  altered  knob. 
partNumber 

The  number  of  the  part  whose  knob  has  been  altered. 

P 

A  pointer  to  the  part  whose  knob  has  been  altered, 
gkd 

A  Generi  cKnobDescri  pti  on  (IV-2267)  structure  for  the  knob. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

knobType  Constants 

kGeneri cMusi cKnob 
Value  is  1. 

kGeneri cMusi clnstrumentKnob 
Value  is  2. 

kGeneri cMusi cDrumKnob 
Value  is  3. 

Discussion 

This  function  is  called  when  any  knob  on  the  synthesizer  is  altered.  It  should  look 
at  the  GCPart  (IV-2263)  and  the  Generi  cKnobDescri  pti  on  (IV-2267)  structures  and 
address  the  synthesizer  hardware  appropriately  to  set  the  new  knob  value.  For  a 
MIDI  device,  this  means  to  construct  a  system-exclusive  MIDI  packet  and  send  it  to 
the  MIDI  routine  received  by  the  Musi  cDeri  vedSetMIDI  (11-978)  call. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Calling  Generic  Music  Component  Clients"  (V-2925) 


Inside  QuickTime:  Function  l-Q 


11-977 


MusicDerivedSetMIDI 


MusicDerivedSetMIDI 


Sets  the  MIDI  channel  and  other  MIDI  settings  for  MIDI  output  only. 

ComponentResul t  MusicDerivedSetMIDI  ( 

Musi cComponent  me, 

Musi cMIDISendUPP  midiProc, 
long  refcon, 

1 ong  mi dl Channel  ) ; 


me 

The  instance  of  the  generic  music  component.  Your  software  obtains  this 
reference  when  calling  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent 
(11-1131). 

mi di Proc 

A  pointer  to  the  Musi  cMIDISendProc  (III— 21 10)  callback  in  your  music 
component  for  performing  MIDI  output. 

refcon 

A  reference  constant  sent  to  the  callback  specified  by  the  mi  di  Proc  parameter. 
Use  this  parameter  to  point  to  a  data  structure  containing  any  information  your 
callback  needs, 
mi di Channel 

The  MIDI  channel  to  use  for  the  operation. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

A  derived  component  for  a  MIDI  synthesizer  receives  this  call  soon  after  it  is 
opened.  It  should  store  the  mi  di  Proc,  refCon,  and  mi  di  Channel  parameters  in  its 
global  variables.  When  the  derived  component  needs  to  communicate  with  the 
synthesizer,  it  calls  your  Musi  cMIDISendProc  (III— 21 10)  function  with  this  reference 
constant.  The  mi  di  Channel  variable  specifies  the  system  channel  of  the  device. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Calling  Generic  Music  Component  Clients"  (V-2925) 


11-978 


Inside  QuickTime:  Function  l-Q 


MusicDerivedSetPart 


MusicDerivedSetPart 


Sets  the  polyphony  for  the  part  specified  in  the  GCPart  (IV-2263)  structure. 

ComponentResul t  MusicDerivedSetPart  ( 

Musi cComponent  me, 

long  partNumber, 

GCPart  *p  ); 


me 

The  instance  of  the  generic  music  component.  Your  software  obtains  this 
reference  when  calling  OpenComponent  (11-1130)  or  OpenDefaul  tComponent 
(11-1131). 

partNumber 

The  number  of  the  part  for  this  operation. 

P 

A  pointer  to  the  part  for  this  operation. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Calling  Generic  Music  Component  Clients"  (V-2925) 


MusicDerivedSetPartlnstrumentNumber 


Sets  the  instrument  specified  in  the  GCPart  (IV-2263)  structure. 

ComponentResul t  Musi cDeri vedSetPartlnstrumentNumber  ( 

Musi cComponent  me, 

long  partNumber, 

GCPart  *p  ); 


me 

A  music  component.  Your  software  obtains  this  reference  when  calling 
OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

partNumber 

The  number  of  the  part  for  this  operation. 


Inside  QuickTime:  Function  l-Q 


11-979 


MusicDerivedStorePartlnstrument 


P 

A  pointer  to  the  part  for  this  operation. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 


MusicDerivedStorePartlnstrument 


Undocumented 

ComponentResul t  MusIcDeri vedStorePartlnstrument  ( 
Musi cComponent  me, 
long  partNumber, 

GCPart  *p, 

long  i nstrumentNumber  ); 


me 

An  instance  of  the  music  component.  Your  software  obtains  this  reference 
when  calling  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

partNumber 

The  number  of  the  part  for  this  operation. 

P 

A  pointer  to  the  part  for  this  operation. 

1 nstrumentNumber 

Number  of  the  instrument  for  this  part.  You  can  use  MusicFindTone  (11-981)  to 
get  an  instrument  number. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 


11-980 


Inside  QuickTime:  Function  l-Q 


MusicFindTone 


MusicFindTone 


Returns  the  number  of  the  best-matching  instrument  provided  by  a  specified  music 
component. 


ComponentResul t  Mus 
Musi cComponent 
ToneDescri pti on 
1  ong 

unsigned  long 


icFindTone  ( 
me , 

*td , 

*1 ibrarylndexOut, 
*fi  t  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi cDevi ce 
(11-1028). 
td 

Pointer  to  a  ToneDescri  pti  on  (IV-2487)  structure. 

1 i brarylndexOut 

On  return,  contains  the  number  of  the  best-matching  instrument.  Only  General 
MIDI  numbers  are  guaranteed  to  be  the  same  for  later  instantiations  of  the 
component, 
f  i  t 

On  return,  a  constant  (see  below)  that  indicates  how  well  an  instrument 
matches  the  tone  description. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

fit  Constants 

klnstrumentMatchSynthesi zerType 

The  requested  synthesizer  type  was  found. 
klnstrumentMatchSynthesi  zerName 

The  particular  instance  of  the  synthesizer  requested  was  found. 
klnstrumentMatchName 

The  instrument  name  in  the  tone  description  matched  an  appropriate 
instrument  on  the  synthesizer. 
klnstrumentMatchNumber 

The  instrument  number  in  the  tone  description  matched  an  appropriate 
instrument  on  the  synthesizer. 

klnstrumentMatchGMNumber 

The  General  MIDI  equivalent  was  used  to  find  an  appropriate  instrument  on 
the  synthesizer. 


Inside  QuickTime:  Function  l-Q 


11-981 


MusicGenericConfigure 


Discussion 

The  music  component  searches  for  an  instrument  as  follows: 

If  the  synthesi  zerType  field  of  the  td  parameter  matches  the  type  of  the  specified 
music  component,  it  first  tries  to  find  an  instrument  that  matches  the  value  of  the 
i  nstrumentNumber  field  of  the  td  parameter.  If  this  value  is  in  the  range  129-16512, 
which  specifies  a  GS  instrument,  and  the  GS  instrument  is  not  available,  it  tries  to 
find  the  General  MIDI  instrument  that  corresponds  to  it,  which  has  the  number 
( ( GS  1  nstrumentnumber  -  1)  &  0x7F)  +  1.  If  the  value  is  greater  than  16512,  which 
specifies  a  transient  ROM  instrument  or  internal  instrument  index  value,  it  tries  to 
find  an  instrument  that  matches  the  synthesi  zerName  field  of  the  td  parameter.  If 
that  fails,  it  tries  to  find  an  instrument  that  matches  the  value  of  the  gmNumber  field 
of  the  td  parameter. 

If  the  synthesi  zerType  field  of  the  td  parameter  does  not  match  the  type  of  the 
specified  music  component,  it  tries  to  find  an  instrument  that  matches  the  value  of 
the  gmNumber  field  of  the  td  parameter. 

If  none  of  these  rules  apply,  or  the  fields  are  blank  (0  for  the  type  or  numeric  fields, 
or  zero-length  for  the  strings),  then  the  call  returns  instrument  1  and  a  fit  parameter 
of  zero. 

The  synthesi  zerName  field  maybe  ignored  by  the  component;  it  is  used  by  the  note 
allocator  when  deciding  which  music  device  to  use. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Managing  Synthesizers"  (V-2920) 


MusicGenericConfigure 


Informs  the  generic  music  component  what  services  your  music  component 
requires  and  points  to  any  resources  that  are  necessary. 

ComponentResul t  MusicGenericConfigure  ( 

Musi cComponent  me, 
long  mode, 

long  flags, 

1 ong  baseResID  ) ; 


11-982 


Inside  QuickTime:  Function  l-Q 


MusicGenericConfigure 


me 

The  instance  of  the  generic  music  component.  Your  software  obtains  this 
reference  when  calling  the  Component  Manager's  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131)  function. 

mode 

Must  be  0. 
fl  ags 

Flags  (see  below)  that  control  the  importation  of  MIDI  files. 
baseResID 

The  resource  ID  of  the  lowest-numbered  resource  used  by  your  music 
component. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

kGeneri cMusi cDoMIDI 

Implement  normal  MIDI  messages  for  note,  controllers,  and  program  changes 
0-127. 

kGeneri cMusi cBankO . . . kGeneri cMusi  cBank32 

If  kGenericMusi  cBankO  is  set,  then  bank  changes  for  instruments  numbered 
above  127  will  be  sent  on  controller  zero;  if  kGeneri  cMusi  cBank32,  then  on 
controller  32.  If  both  flags  are  set,  then  the  bank  is  sent  on  controller  0,  and  then 
a  0  value  is  sent  to  controller  32. 
kGeneri cMusi cErsatzMIDI 

Some  musical  devices  may  internally  be  driven  by  a  MIDI  stream  but  should 
not  appear  to  the  user  to  be  an  external  MIDI  device.  The 
kGenericMusicErsatzMIDI  flag  instructs  the  generic  music  component  to  allocate 
channels  appropriately  and  construct  MIDI  packets.  The  MIDI  packets  are 
always  sent  to  the  routine  Musi  cDeri  vedMIDISend  (11-975),  and  never  to  an 
external  MIDI  port. 
kGeneri cMusi cCal 1  Knobs 

Specifies  that  your  music  component  should  receive  calls  to  its  routine 
Musi  cDeri  vedSetKnob  (11-976)  for  changes  to  global  or  part  knobs.  This  flag 
should  be  set  if  your  component  implements  any  knobs. 

kGeneri cMusi cCal 1  Parts 

Specifies  that  your  music  component  should  receive  calls  to  its  routine 
Musi  cDeri  vedSetPart  (11-979),  in  order  to  alter  a  specific  part's  polyphony  or,  in 
the  case  of  a  MIDI  device,  MIDI  channel  number. 


Inside  QuickTime:  Function  l-Q 


11-983 


MusicGenericGetKnobList 


kGeneri cMusi cCal 1  Instrument 

Specifies  that  your  music  component  should  receive  calls  to  its  routine 
Musi  cDeri  vedSetlnstrument  (11-976),  in  order  to  set  a  part  to  a  new  instrument. 
This  is  for  devices  that  support  complete  user-instruments  with  knob  lists.  If 
this  flag  is  not  set,  then  the  generic  music  component  calls  your  music 
component  many  times  to  set  the  value  of  each  knob  in  the  instrument. 
kGeneri cMusi cCal  1  Number 

Directs  the  generic  music  component  to  call  your  music  component's 
Musi  cDeri  vedSetPartlnstrumentNumber  (11-979)  function,  rather  than  sending 
standard  MIDI  program-change  and  bank-change  messages. 

kGeneri cMusi cCal 1 ROMInstrument 

Allows  instruments  that  appear  to  the  user  as  instruments  built  into  the 
synthesizer  to  be  stored  in  the  derived  component's  resource  file,  as  ’  ROMi ' 
resources.  The  derived  component  gets  a  call  to  Musi  cDeri  vedSetlnstrument 
(11-976)  when  one  of  these  instruments  is  requested. 

Discussion 

The  base  Res  I D  parameter  is  the  lowest  resource  ID  used  by  your  component  for  the 
standard  resources  described  above.  Since  the  resource  numbers  are  relative  to  this, 
you  can  include  several  music  components  in  a  single  system  extension. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Managing  the  Generic  Music  Component"  (V-2925) 


MusicGenericGetKnobList 


Gets  a  list  of  the  knobs  of  a  given  type  for  the  generic  music  component. 

ComponentResul t  MusicGenericGetKnobList  ( 

Musi cComponent  me, 

long  knobType, 

Generi cKnobDescri pti onLi stHandl e  *gkdlH  ); 


The  instance  of  the  generic  music  component.  Your  software  obtains  this 
reference  when  calling  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent 
(11-1131). 


11-984 


Inside  QuickTime:  Function  l-Q 


MusicGenericGetPart 


knobType 

A  constant  (see  below)  that  defines  the  type  of  knob, 
gkdl  H 

On  return,  a  pointer  to  a  handle  to  a  Generi  cKnobDescri  pti  on  Li  st  (IV-2268) 
structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

knobType  Constants 

kGeneri cMusi cKnob 
Value  is  1. 

kGeneri cMusi clnstrumentKnob 
Value  is  2. 

kGeneri cMusi cDrumKnob 
Value  is  3. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 


MusicGenericGetPart 


Gets  a  part  used  by  the  generic  music  component. 

ComponentResul t  MusicGenericGetPart  ( 

Musi cComponent  me, 

long  partNumber, 

GCPart  **part  ); 


me 

The  instance  of  the  generic  music  component.  Your  software  obtains  this 
reference  when  calling  OpenComponent  (11-1130)  or  OpenDefaul  tComponent 
(11-1131). 

partNumber 

The  number  of  the  part  for  this  operation. 

part 

A  handle  to  a  GCPart  (IV-2263)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Inside  QuickTime:  Function  l-Q 


11-985 


MusicGenericSetResourceNumbers 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi c .  h 


MusicGenericSetResourceNumbers 


Undocumented 

ComponentResul t  MusicGenericSetResourceNumbers  ( 
Musi cComponent  me, 

Hand! e  resourceIDH  ) ; 


me 

The  instance  of  the  generic  music  component.  Your  software  obtains  this 
reference  when  calling  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent 
(11-1131). 

resourceIDH 

A  handle  to  a  resource  ID. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 


MusicGetDescription 


Returns  a  structure  describing  the  synthesizer  controlled  by  the  music  component 
device. 

ComponentResul t  MusicGetDescription  ( 

Musi cComponent  me, 

Synthesi zerDescri pti on  *sd  ); 


Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 


11-986 


Inside  QuickTime:  Function  l-Q 


MusicGetDeviceConnection 


sd 

Pointer  to  a  SynthesizerDescription  (IV-2465)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusIc.h 

Programming  summary:  "Managing  Synthesizers"  (V-2920) 


MusicGetDeviceConnection 


Determines  how  many  hardware  synthesizers  are  available  to  a  music  component 
and  gets  the  IDs  for  those  devices. 

ComponentResul t  MusicGetDeviceConnection  ( 


Musi cComponent  me, 
long  index, 

long  *idl, 

long  * i d 2  ); 


me 

Music  component  returned  by  NAGetRegi  steredMusi  cDevi  ce  (11-1028). 
i  ndex 

Index  of  the  device  for  which  you  want  to  find  out  the  IDs.  Set  to  0  if  you  are 

calling  to  get  the  number  of  hardware  devices, 
i  dl 

On  return,  a  hardware  synthesizer  ID. 
id2 

On  return,  another  hardware  synthesizer  ID. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

To  get  the  number  of  hardware  synthesizers  available  to  the  music  component 
specified  in  the  me  parameter  and  an  index  you  can  use  to  request  ID  numbers  for  a 
specific  device,  call  this  function  with  a  value  of  0  for  the  i  ndex  parameter.  You  can 
then  pass  an  index  value  in  the  index  parameter,  and  the  function  returns  hardware 
synthesizer  IDs  in  the  i  dl  and  i  d2  parameters. 


Inside  QuickTime:  Function  l-Q 


11-987 


MusicGetDrumKnobDescription 


Special  Considerations 

This  function  is  implemented  only  for  hardware  synthesizers,  such  as  PCI  card 
devices. 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Managing  Synthesizers"  (V-2920) 


MusicGetDrumKnobDescription 


Returns  a  description  of  a  drum  kit  knob. 

ComponentResul t  MusicGetDrumKnobDescription  ( 
Musi cComponent  me, 

long  knoblndex, 

KnobDescri pti on  *mkd  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 
knoblndex 

A  knob  index  or  knob  ID. 
mkd 

A  pointer  to  a  KnobDescri  pti  on  (IV-2299)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Managing  Synthesizers"  (V-2920) 


MusicGetDrumKnobDescriptionObsolete 

Undocumented 

ComponentResul t  Musi cGetDrumKnobDescri pti onObsol  ete  ( 
Musi cComponent  me, 


11-988 


Inside  QuickTime:  Function  l-Q 


MusicGetDrumNames 


long  knoblndex, 

void  *mkd  ); 


Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 


knoblndex 

A  knob  index  or  knob  ID. 


mkd 

A  pointer  to  a  KnobDescri  pti  on  (IV-2299)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 


MusicGetDrumNames 


Undocumented 

cGetDrumNames  ( 
me , 

modi fi abl elnstruments , 
*i nstrumentNumbers , 

*i nstrumentNames  ); 


ComponentResul  t  Musi 
Musi cComponent 
1  ong 
Handl e 
Handl e 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 

modi fi abl elnstruments 
Undocumented 
i nstrumentNumbers 
Undocumented 
i nstrumentNames 

A  pointer  to  a  handle  to  the  requested  list  of  instrument  name  strings, 
formatted  as  a  short  integer  followed  by  packed  strings. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Inside  QuickTime:  Function  l-Q 


11-989 


MusicGetlnfoText 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi c .  h 


MusicGetlnf  oT  ext 


Undocumented 

ComponentResul t  MusicGetlnfoText  ( 
Musi cComponent  me, 
long  selector, 

Handle  *textH, 

Handle  *styleH  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 
sel ector 

Undocumented 

textH 

Undocumented 
styl eH 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 


MusicGetlnstrumentAboutlnfo 


Obtains  the  information  about  an  instrument  that  appears  in  its  About  box. 

ComponentResul t  MusicGetlnstrumentAboutlnfo  ( 

Musi cComponent  me, 

long  part, 

InstrumentAboutlnfo  *iai  ); 


11-990 


Inside  QuickTime:  Function  l-Q 


MusicGetlnstrumentlnfo 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi cDevi  ce 
(11-1028). 

part 

Number  of  the  part  containing  the  instrument  for  which  you  want  information, 
i  ai 

On  return,  a  pointer  to  an  InstrumentAboutlnfo  (IV-2293)  structure  for  the 
instrument  currently  on  the  specified  synthesizer  part. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusIc.h 

Programming  summary:  "Managing  Instruments  and  Parts"  (V-2921) 


MusicGetlnstrumentlnfo 


Obtains  a  list  of  instruments  supported  by  a  synthesizer. 

ComponentResul t  MusicGetlnstrumentlnfo  ( 

Musi cComponent  me, 

long  getlnstrumentlnfoFl ags , 

InstrumentlnfoLi stHandl e  *infoListH  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi cDevi ce 
(11-1028). 

getlnstrumentlnfoFl ags 

Flags  (see  below)  that  specify  limits  to  the  list  of  instruments, 
i  nf  oLi  stH 

On  return,  a  pointer  to  a  handle  to  an  InstrumentlnfoLi  st  (IV-2294)  structure 
that  contains  the  list  of  instruments.  This  handle  must  be  disposed  of  by  the 
caller. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

getlnstrumentlnfoFlags  Constants 

kGetlnstrumentlnfoNoBui 1  tin 

Don't  return  built-in  instruments. 


Inside  QuickTime:  Function  l-Q 


11-991 


MusicGetlnstrumentKnobDescription 


kGetlnstrumentlnfoMi diUserlnst 

Do  return  user  instruments  for  a  MIDI  device. 
kGet  I  instrument  I  nfoNoIText 

Don't  return  international  text  strings. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Managing  Instruments  and  Parts"  (V-2921) 


MusicGetlnstrumentKnobDescription 


Obtains  the  description  of  an  instrument  knob. 

ComponentResul t  Musi cGetlnstrumentKnobDescri pti on  ( 
Musi cComponent  me, 

long  knoblndex, 

KnobDescri pti on  *mkd  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 
knoblndex 

A  knob  index  or  knob  ID. 
mkd 

On  return,  a  KnobDescri  pti  on  (IV-2299)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Managing  Synthesizers"  (V-2920) 


MusicGetlnstrumentKnobDescriptionObsolete 

Undocumented 


11-992 


Inside  QuickTime:  Function  l-Q 


MusicG  etlnstrumentN  ames 


ComponentResul t  Musi cGetlnstrumentKnobDescriptionObsol ete  ( 
Musi cComponent  me, 

long  knoblndex, 

void  *mkd  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 

knoblndex 

A  knob  index  or  knob  ID. 
mkd 

On  return,  a  KnobDescri  pti  on  (IV-2299)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 


MusicGetlnstrumentNames 


Undocumented 

ComponentResul t  MusicGetlnstrumentNames  ( 

Musi cComponent  me, 

long  modi fi abl elnstruments , 

Handle  *i nstrumentNames , 

Handl e  *i nstrumentCategoryLasts , 

Handle  *i nstrumentCategoryNames  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 

modi fi abl elnstruments 
Undocumented 
i nstrumentNames 

A  pointer  to  a  handle  to  the  requested  list  of  instrument  name  strings, 
formatted  as  a  short  integer  followed  by  packed  strings. 


Inside  QuickTime:  Function  l-Q 


11-993 


MusicGetKnob 


i ns trument Category  Lasts 

A  pointer  to  a  handle  to  a  group  of  short  integers,  the  first  of  which  contains  the 
number  of  integers  to  follow. 

1  ns trument Category Names 

A  pointer  to  a  handle  to  the  requested  list  of  instrument  category  name  strings, 
formatted  as  a  short  integer  followed  by  packed  strings. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi c .  h 


MusicGetKnob 


Returns  the  value  of  the  specified  global  synthesizer  knob. 

ComponentResul t  MusicGetKnob  ( 

Musi cComponent  me, 

1 ong  knobID  ) ; 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 

knobID 

Knob  index  or  ID. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

A  global  knob  controls  an  aspect  of  the  entire  synthesizer.  It  is  not  specific  to  a  part 
within  the  synthesizer. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Managing  Synthesizers"  (V-2920) 

See  Also 

For  the  corresponding  set  function,  see  Musi  cSetKnob  (11-1007). 


11-994 


Inside  QuickTime:  Function  l-Q 


MusicGetKnobDescription 


MusicGetKnobDescription 


Returns  a  pointer  to  an  initialized  knob  description  structure  describing  a  global 
synthesizer  knob. 

ComponentResul t  MusicGetKnobDescription  ( 

Musi cComponent  me, 

long  knoblndex, 

KnobDescri pti on  *mkd  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi cDevi ce 
(11-1028). 
knoblndex 

Knob  index  or  ID. 
mkd 

Pointer  to  a  KnobDescri  pti  on  (IV-2299)  structure.  The  initialized  structure 
provides  default  values  associated  with  the  particular  knob. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

A  global  knob  controls  an  aspect  of  the  entire  synthesizer;  it  is  not  limited  to  a  part 
within  the  synthesizer.  You  can  use  the  information  returned  by  a  call  to  this 
function  to  reset  a  knob  to  some  known,  usable  value. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Managing  Synthesizers"  (V-2920) 


MusicGetKnobDescriptionObsolete 


Undocumented 

ComponentResul t  Musi cGetKnobDescri pti onObsol ete  ( 
Musi cComponent  me, 

long  knoblndex, 

void  *mkd  ); 


Inside  QuickTime:  Function  l-Q 


11-995 


MusicGetKnobSettingStrings 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 
knoblndex 

Knob  index  or  ID. 
mkd 

Pointer  to  a  KnobDescri  pti  on  (IV-2299)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c . h 


MusicGetKnobSettingStrings 


Returns  a  list  of  knob  setting  names  known  by  the  specified  music  component. 

ComponentResul t  MusicGetKnobSettingStrings  ( 

Musi cComponent  me, 
long  knoblndex, 

1 ong  i sGl obal  , 

Handle  *setti ngsNames , 

Handle  *setti ngsCategory Lasts , 

Handle  *setti ngsCategoryNames  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 
knoblndex 

The  knob  index  or  knob  ID. 
i sGl obal 

If  a  knob  index  is  used,  indicates  whether  the  specified  knob  is  a  global  knob, 
setti ngsNames 

The  requested  list  of  knob  setting  strings  formatted  as  a  short  followed  by 
packed  strings, 
setti ngsCategory Lasts 

A  group  of  short  integers,  the  first  of  which  contains  the  number  of  shorts  to 
follow. 


11-996 


Inside  QuickTime:  Function  l-Q 


MusicGetMasterTune 


setti ngsCategory Names 

Knob  setting  category  names  formatted  as  a  short  integer  followed  by  a  list  of 
names. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

All  handles  must  be  disposed  of  by  the  caller. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Managing  Synthesizers"  (V-2920) 


MusicGetMasterTune 


Returns  the  synthesizer's  master  tuning  as  a  fixed-point  value  in  semitones. 

ComponentResul t  MusicGetMasterTune  ( 

Musi cComponent  me  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 

function  result  A  fixed-point  value  representing  the  synthesizer's  master  tuning. 

The  value  is  a  fixed  16.16  number,  allowing  shifts  by  fractional 
values. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Miscellaneous  Music  Component  Functions"  (V-2922) 

See  Also 

For  the  corresponding  set  function,  see  Musi  cSetMasterTune  (11-1008). 


MusicGetMIDIPorts 


Returns  the  number  of  input  and  output  ports  a  MIDI  device  has. 


Inside  QuickTime:  Function  l-Q 


11-997 


MusicGetMIDIProc 


ComponentResul t  Musi cGetMIDI Ports  ( 

Musi cComponent  me, 

long  *i nputPortCount , 

long  *outputPortCount  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 

i nputPortCount 

On  return,  the  number  of  input  MIDI  ports  available  to  the  music  component. 
outputPortCount 

On  return,  the  number  of  output  MIDI  ports  available  to  the  music  component. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

This  call  is  implemented  only  for  hardware  synthesizers,  such  as  PCI  card  devices. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Managing  Synthesizers"  (V-2920) 


MusicGetMIDIProc 


Returns  a  pointer  to  the  procedure  a  music  component  is  using  to  process  external 
MIDI  notes. 

ComponentResul t  MusicGetMIDIProc  ( 

Musi cComponent  me, 

MusicMIDISendUPP  *midiSendProc, 

1 ong  *refCon  ) ; 


Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 


mi di SendProc 

Pointer  to  a  MIDI  serial  port  Musi  cMIDISendProc  (III— 21 10)  callback  that 
processes  external  MIDI  notes.  This  function  was  set  by  a  previous  call  to 
Musi  cSetMIDI  Proc  (11-1009).  If  no  function  has  been  set  with  Musi  cSetMIDI  Proc, 
this  parameter  returns  0. 


11-998 
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MusicGetPart 


refCon 

A  reference  constant.  The  Movie  Toolbox  passes  this  reference  constant  to  your 
MusicMIDISendProc  each  time  it  calls  it.  Use  this  parameter  to  point  to  a  data 
structure  containing  any  information  your  callback  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Q  u  i  c  kT i me  M  u  s i c .  h 

Programming  summary:  "Managing  Synthesizers"  (V-2920) 

See  Also 

For  the  corresponding  set  function,  see  MusicSetMIDIProc  (11-1009). 


MusicGetPart 


Returns  the  MIDI  channel  and  maximum  polyphony  for  a  particular  part. 

ComponentResul t  MusicGetPart  ( 

Musi cComponent  me, 
long  part, 

1 ong  *mi di Channel , 

long  *polyphony  ); 

me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi cDevi ce 
(11-1028). 

part 

The  music  component  part  requested, 
mi di Channel 

On  return,  a  pointer  to  a  MIDI  channel.  For  non-MIDI  devices,  the  MIDI 
channel  pointed  to  by  this  parameter  is  0. 

polyphony 

On  return,  a  pointer  to  the  maximum  number  of  voices  or  polyphony  for  the 
part.. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Function  l-Q 


11-999 


MusicGetPartAtomicInstrument 


Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c . h 

Programming  summary:  "Managing  Instruments  and  Parts"  (V-2921) 

See  Also 

For  the  corresponding  set  function,  see  Musi cSetPart  (II— 1010). 


MusicGetPartAtomicInstrument 


Returns  the  atomic  instrument  currently  in  a  part. 

ComponentResul t  MusicGetPartAtomicInstrument  ( 
Musi cComponent  me, 

long  part, 

Atomi clnstrument  *ai  , 

1 ong  f 1 ags  ) ; 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 

part 

The  part  with  the  atomic  instrument, 
ai 

On  return,  an  atomic  instrument, 
fl  ags 

A  constant  (see  below)  that  specifies  what  pieces  of  information  about  an 
atomic  instrument  the  caller  is  interested  in. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

kGet Atomi clnstNoExpandedSampl  es 
Eliminate  the  expanded  samples. 
kGet Atomi clnstNoOriginal Samples 
Eliminate  the  original  samples. 
kGet Atomi clnstNoSamples 

Eliminate  both  the  original  and  expanded  samples. 
kGet Atomi clnstNoknobList 
Eliminate  the  knob  list. 
kGet Atomi c Inst No  Instrument  Info 

Eliminate  the  About  box  information. 
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MusicGetPartController 


kGetAtomi clnstOri gi nal KnobLi  st 
Include  the  original  knob  list. 
kGetAtomi clnstAl 1  Knobs 

Include  the  current  knob  list. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Managing  Instruments  and  Parts"  (V-2921) 

See  Also 

For  the  corresponding  set  function,  see  Musi  cSetPartAtomi  clnstrument  (II— 1011). 


MusicGetPartController 


Returns  the  value  of  a  specified  controller  on  a  specified  part. 

ComponentResul t  MusicGetPartController  ( 

Musi cComponent  me, 

long  part, 

Musi cControl 1 er  control  1 erNumber  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi cDevi ce 
(11-1028). 

part 

Part  whose  controller  value  you  want  to  get. 
control  1 erNumber 

On  return,  the  controller  number;  see  "Music  Controllers"  (IV-2682). 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Managing  Instruments  and  Parts"  (V-2921) 

See  Also 

For  the  corresponding  set  function,  see  Musi  cSetPartControl  1  er  (11-1012). 


Inside  QuickTime:  Function  l-Q 


11-1001 


MusicGetPartlnstrumentNumber 


MusicGetPartlnstrumentNumber 


Returns  the  instrument  number  currently  assigned  to  a  part. 

ComponentResul t  MusicGetPartlnstrumentNumber  ( 

Musi cComponent  me, 

1 ong  part  ) ; 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 

part 

Part  number  containing  the  instrument. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Managing  Instruments  and  Parts"  (V-2921) 

See  Also 

For  the  corresponding  set  function,  see  Musi cSetPartlnstrumentNumber  (11-1013). 


MusicGetPartKnob 


Retrieves  the  current  value  of  a  knob  for  a  part. 

ComponentResul t  MusicGetPartKnob  ( 

Musi cComponent  me, 

long  part, 

1 ong  knobID  ) ; 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 

part 

The  part  number. 
knobID 

The  knob  index  or  ID. 


11-1002 


Inside  QuickTime:  Function  l-Q 


MusicGetPartName 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Managing  Instruments  and  Parts"  (V-2921) 

See  Also 

For  the  corresponding  set  function,  see  Musi  cSetPartKnob  (11-1014). 


MusicGetPartName 


Returns  the  string  name  of  a  part. 

ComponentResul t  MusicGetPartName  ( 
Musi cComponent  me, 

long  part, 

StringPtr  name  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi cDevi ce 
(11-1028). 

part 

Part  to  get  the  name  of. 

name 

On  return,  a  string  containing  the  part  name. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  name  string  is  used  by  selection  dialog  boxes  or  configuration  information. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Managing  Instruments  and  Parts"  (V-2921) 

See  Also 

For  the  corresponding  set  function,  see  Musi  cSetPartName  (11-1015). 
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11-1003 


MusicMediaGetlndexedTunePlayer 


MusicMediaGetlndexedT  unePlayer 


Undocumented 

ComponentResul t  MusicMediaGetlndexedTunePlayer  ( 
Componentlnstance  ti  , 

long  sampl eDescIndex , 

Componentlnstance  *tp  ); 

ti 

Undocumented 
sampl eDescIndex 
Undocumented 


tp 

A  pointer  to  a  tune  player  component  instance. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Related  Java  Methods 

qu ickti me. std. mo vies. media. MusicMediaHandler. getlndexedT  unePl ayer ( ) , 
quicktime.std.music.TunePl ayer . f romMusi cMediaHandlert ) 


MusicPlayNote 


Plays  a  note  on  a  specified  part  at  a  specified  pitch  and  velocity. 

ComponentResul t  MusicPlayNote  ( 

Musi cComponent  me, 
long  part, 

long  pitch, 

1 ong  vel oci ty  ) ; 

me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 


11-1004 
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MusicReceiveMIDI 


part 

The  part  to  play  the  note  on. 
pi  tch 

The  pitch  at  which  to  play  the  note.  If  the  pitch  is  specified  by  a  number  from  0 
to  127,  it  is  a  MIDI  pitch,  where  60  is  middle  C.  If  the  pitch  is  a  positive  number 
above  65535,  the  value  is  a  fixed-point  pitch  value.  Thus,  microtonal  values  may 
be  specified. 

vel oci ty 

How  hard  to  strike  the  key.  Values  are  0-127  where  0  is  silence.  Velocity  refers 
to  how  hard  the  key  is  struck  (if  performed  on  a  keyboard-instrument); 
typically,  this  translates  directly  to  volume,  but  on  many  synthesizers  this  also 
subtly  alters  the  timbre  of  the  tone. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  current  note  continues  to  play  until  aMusicPlayNote  function  with  the  same 
pitch  and  velocity  of  0  turns  the  note  off. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusIc.h 

Programming  summary:  "Managing  Synthesizers"  (V-2920) 


MusicReceiveMIDI 


Undocumented 

ComponentResul t  MusicReceiveMIDI  ( 
Musi cComponent  me, 

MusicMIDIReadHookUPP  readHook, 

long  refCon  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 

readHook 

A  Universal  Procedure  Pointer  that  accesses  aMusicMIDIReadHookProc 
(III— 2109)  callback. 


Inside  QuickTime:  Function  l-Q 


11-1005 


MusicResetPart 


refCon 

A  reference  constant  to  be  passed  to  your  callback.  Use  this  constant  to  point  to 
a  data  structure  containing  any  information  your  callback  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi c . h 


MusicResetPart 


Silences  all  sounds  on  a  specified  part  and  resets  all  controllers  on  that  part  to  their 
default  values. 

ComponentResul t  MusicResetPart  ( 

Musi cComponent  me, 

1 ong  part  ) ; 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 

part 

The  number  of  the  part. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  default  value  to  which  controllers  on  the  part  are  set  is  0  for  all  controllers 
except  volume.  Volume  is  set  to  its  maximum,  32767  (0x7  FFF). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Managing  Instruments  and  Parts"  (V-2921) 


MusicSendMIDI 


Sends  a  MIDI  packet  to  a  specified  port. 


11-1006 


Inside  QuickTime:  Function  l-Q 


MusicSetKnob 


ComponentResul t  Musi cSendMIDI  ( 
Musi cComponent  me, 

long  portlndex, 

MusicMIDIPacket  *mp  ); 


me 

Music  component  instance  returned  by  NAGetRegi  steredMusi  cDevi  ce  (11-1028). 
portlndex 

The  index  of  the  port  to  send  the  MIDI  packet  to.  The  index  value  is  1  through 
the  port  count  returned  by  MusicGetMIDIPorts  (11-997). 
mp 

A  pointer  to  the  music  MIDI  packet  to  be  sent.  The  function  sends  the  MIDI 
music  packet  specified  by  this  parameter  to  the  specified  port. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

This  call  is  implemented  only  for  hardware  synthesizers,  such  as  PCI  card  devices. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusIc.h 

Programming  summary:  "Managing  Synthesizers"  (V-2920) 


MusicSetKnob 


Modifies  the  value  of  the  specified  global  synthesizer  knob. 

ComponentResul t  MusicSetKnob  ( 

Musi cComponent  me, 

long  knobID, 

long  knobValue  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi cDevi ce 
(11-1028). 

knobID 

Knob  index  or  ID. 
knobVal ue 

Value  for  specified  knob. 


Inside  QuickTime:  Function  l-Q 


11-1007 


MusicSetMasterTune 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

A  global  knob  controls  an  aspect  of  the  entire  synthesizer;  it  is  not  limited  to  a  part 
within  the  synthesizer. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Managing  Synthesizers"  (V-2920) 

See  Also 

For  the  corresponding  get  function,  see  Musi  cGetKnob  (11-994). 


MusicSetMasterTune 


Alters  a  synthesizer's  master  tuning. 

ComponentResul t  MusicSetMasterTune  ( 
Musi cComponent  me, 

1 ong  masterT une  ) ; 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 
masterT  une 

The  amount  by  which  to  transpose  the  entire  synthesizer  in  pitch.  The  value  is 
a  fixed  16.16  number,  allowing  shifts  by  fractional  values. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Miscellaneous  Music  Component  Functions"  (V-2922) 

See  Also 

For  the  corresponding  get  function,  see  Musi  cGetMasterTune  (11-997). 


11-1008 


Inside  QuickTime:  Function  l-Q 


MusicSetMIDIProc 


MusicSetMIDIProc 


Informs  the  music  component  what  procedure  to  call  when  it  needs  to  send  MIDI 
data. 

ComponentResul t  MusicSetMIDIProc  ( 

Musi cComponent  me, 

Musi cMIDI Send UP P  mi di Send P roc , 

long  refCon  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi cDevi ce 
(11-1028). 
mi  di SendProc 

A  pointer  to  the  MusicMIDISendProc  (III— 21 10)  callback  to  use  when  sending 
MIDI  data. 
refCon 

A  reference  constant  value.  The  Movie  Toolbox  passes  this  reference  constant 
to  your  callback  each  time  it  calls  it.  Use  this  parameter  to  point  to  a  data 
structure  containing  any  information  your  callback  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  call  is  implemented  only  by  music  components  for  MIDI  synthesizers. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Managing  Synthesizers"  (V-2920) 

See  Also 

For  the  corresponding  get  function,  see  Musi  cGetMIDI  Proc  (11-998). 


MusicSetOf  f  lineT  imeT  o 


Advances  the  synthesizer  clock  when  the  synthesizer  is  not  running  in  real  time. 

ComponentResul t  Musi cSetOf f 1 i neTimeTo  ( 

Musi cComponent  me, 

long  newTimeStamp  ); 


Inside  QuickTime:  Function  l-Q 


11-1009 


MusicSetPart 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 
newT i meStamp 

The  number  of  samples  to  synthesize. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  synthesizer  may  not  be  running  in  real  time  due  to  a  call  to  Musi  cStartOf  f  1  i  ne 
(11-1016).  Setting  the  time  generates  audio  output  from  the  synthesizer. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Miscellaneous  Music  Component  Functions"  (V-2922) 

MusicSetPart 

Sets  the  MIDI  channel  and  maximum  polyphony  for  a  specified  part. 

ComponentResul t  MusicSetPart  ( 

Musi cComponent  me, 
long  part, 

1 ong  mi di Channel , 

1 ong  polyphony  ) ; 

me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 

part 

Part  whose  MIDI  channel  and  polyphony  are  to  be  set. 
mi di Channel 

The  MIDI  channel  to  set  the  part  to.  For  non-MIDI  devices,  set  this  parameter 
to  0. 

polyphony 

The  maximum  number  of  voices  or  polyphony  for  the  part. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


11-1010 


Inside  QuickTime:  Function  l-Q 


MusicSetPartAtomicInstrument 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Q  u  i  c  kT i me  M  u  s i c .  h 

Programming  summary:  "Managing  Instruments  and  Parts"  (V-2921) 

See  Also 

For  the  corresponding  get  function,  see  MusicGetPart  (11-999). 


MusicSetPartAtomicInstrument 


Initializes  a  part  with  an  atomic  instrument. 
ComponentResul t  MusicSetPartAtomicInstrument  ( 


Musi cComponent  me, 

long  part, 

Atomi clnstrumentPtr  aiP, 
long  flags  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi cDevi ce 
(11-1028). 

part 

The  part  to  initialize  with  the  atomic  instrument  to. 

aiP 

The  atomic  instrument, 
fl  ags 

Constants  (see  below)  that  specify  details  of  initializing  a  part  with  an  atomic 
instrument. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

kGetAtomi clnstNoExpandedSampl  es 
Eliminate  the  expanded  samples. 
kGetAtomi clnstNoOri gi nal Sampl es 
Eliminate  the  original  samples. 
kGetAtomi clnstNoSamples 

Eliminate  both  the  original  and  expanded  samples. 
kGetAtomi clnstNoKnobLi  st 
Eliminate  the  knob  list. 


Inside  QuickTime:  Function  l-Q 


11-1011 


MusicSetPartController 


kGetAtomi c Inst No  Instrument  Info 

Eliminate  the  About  box  information. 
kGetAtomi clnstOriginalKnobList 
Include  the  original  knob  list. 
kGetAtomi clnstAl  1  Knobs 

Include  the  current  knob  list. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Managing  Instruments  and  Parts"  (V-2921) 

See  Also 

For  the  corresponding  get  function,  see  Musi  cGetPartAtomi  clnstrument  (II— 1000). 


MusicSetPartController 


Initializes  the  value  of  a  specified  controller  on  a  specified  part. 

ComponentResul t  MusicSetPartController  ( 

Musi cComponent  me, 

long  part, 

MusicController  control  1 er Number , 

long  control  1 erVal ue  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 

part 

Part  whose  controller  value  you  want  to  set. 
control  1 erNumber 

Controller  number;  see  "Music  Controllers"  (IV-2682). 
control  1 erVal ue 

Value  for  controller. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


11-1012 


Inside  QuickTime:  Function  l-Q 


MusicSetPartlnstrumentNumber 


Programming  Info 

C  interface  file:  QuickTimeMusIc.h 

Programming  summary:  "Managing  Instruments  and  Parts"  (V-2921) 

See  Also 

For  the  corresponding  get  function,  see  MusicGetPartController  (II— 1 001). 


MusicSetPartlnstrumentNumber 


Superseded  by  Musi  cSetPartlnstrumentNumberlnterruptSafe  (11-1013). 

ComponentResul t  MusicSetPartlnstrumentNumber  ( 

Musi cComponent  me, 

long  part, 

long  i nstrumentNumber  ); 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Managing  Instruments  and  Parts"  (V-2921) 


MusicSetPartlnstrumentNumberlnterruptSafe 


Initializes  a  part  with  a  particular  instrument. 

ComponentResul t  Musi cSetPartlnstrumentNumberlnterruptSafe  ( 
Musi cComponent  me, 

long  part, 

long  i nstrumentNumber  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi cDevi ce 
(11-1028). 

part 

Part  to  be  initialized, 
i nstrumentNumber 

Number  of  instrument  to  initialize  part  with.  You  can  use  Musi  cFi  ndTone 
(11-981)  to  get  an  instrument  number. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Inside  QuickTime:  Function  l-Q 


11-1013 


MusicSetPartKnob 


Special  Considerations 

You  can  call  this  function  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Managing  Instruments  and  Parts"  (V-2921) 

See  Also 

For  the  corresponding  get  function,  see  Musi  cGetPartlnstrumentNumber  (11-1002). 


MusicSetPartKnob 


Sets  a  knob  for  a  specified  part. 

ComponentResul t  MusicSetPartKnob  ( 

Musi cComponent  me, 
long  part, 

long  knobID, 

1 ong  knobVal  ue  ) ; 

me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 

part 

The  part  number. 
knobID 

The  index  or  ID  of  the  knob  to  be  set. 
knobVal ue 

The  value  to  set  the  knob  to. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Managing  Instruments  and  Parts"  (V-2921) 

See  Also 

For  the  corresponding  get  function,  see  Musi  cGetPartKnob  (11-1002). 


11-1014 


Inside  QuickTime:  Function  l-Q 


MusicSetPartName 


MusicSetPartName 


Changes  the  name  of  an  instrument  in  a  specified  part. 

ComponentResul t  MusicSetPartName  ( 

Musi cComponent  me, 

long  part, 

StringPtr  name  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi cDevi ce 
(11-1028). 

part 

Part  to  apply  name  to. 

name 

A  pointer  to  the  name  to  apply  to  part. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  might  want  to  change  the  name  of  a  modified  instrument  before  saving  it.  The 
instrument  name  string  is  used  by  selection  dialog  and  configuration  information 
boxes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Managing  Instruments  and  Parts"  (V-2921) 

See  Also 

For  the  corresponding  get  function,  see  MusicGetPartName  (11-1003). 


MusicSetPartSoundLocalization 


Passes  sound  localization  data  to  a  specified  synthesizer  part. 

ComponentResul t  MusicSetPartSoundLocalization  ( 

Musi cComponent  me, 

long  part. 

Handle  data  ); 


Inside  QuickTime:  Function  l-Q 


11-1015 


MusicStartOffline 


me 

Music  component  instance  identifier. 

part 

The  part  to  pass  the  data  to. 

data 

The  sound  localization  data. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Use  the  functions  described  in  this  section  to  get  and  modify  the  master  tuning  of 
the  synthesizer,  to  play  off  line,  and  to  allow  the  music  component  to  perform  tasks 
it  must  perform  at  foreground  task  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c . h 

Programming  summary:  "Managing  Instruments  and  Parts"  (V-2921) 


MusicStartOffline 


Informs  the  QuickTime  music  synthesizer  that  the  music  will  not  be  played  through 
the  speakers. 


ComponentResul t  MusicStartOffline  ( 


Musi cComponent 
unsigned  long 
Unsi gnedFi xed 
unsigned  short 
Musi cOff 1 i neDataUPP 
1  ong 


me , 

*numChannel s , 
*sampl eRate , 
*sampl eSi ze , 
dataProc , 
dataProcRefCon 


) : 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 

numChannel s 

Number  of  channels  in  the  music  sample;  1  indicates  monaural,  2  indicates 
stereo, 
sampl eRate 

The  number  of  samples  per  second. 


11-1016 


Inside  QuickTime:  Function  l-Q 


MusicStorePartlnstrument 


sampl eSi ze 

The  size  of  the  music  sample:  8-bit  or  16-bit. 
dataProc 

A  pointer  to  a  Musi  cOff  1  i  neDataProc  (III— 21 10)  callback  to  handle  the  audio 
data. 

dataProcRefCon 

A  reference  constant  to  pass  to  the  Musi  cOffli neDataProc  callback.  Use  this 
parameter  to  point  to  a  data  structure  containing  any  information  your  callback 
needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Audio  data  will  be  sent  to  a  function  that  will  create  a  sound  file  to  be  played  back 
later.  You  pass  this  function  the  requested  values  for  the  numChannei  s,  sampl  eRate, 
and  sampl  eSi  ze  parameters.  When  the  function  returns,  those  parameters  contain 
the  actual  values  used. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Miscellaneous  Music  Component  Functions"  (V-2922) 


MusicStorePartlnstrument 


Puts  whatever  instrument  is  on  the  specified  part  into  the  synthesizer's  instrument 
store. 

ComponentResul t  MusicStorePartlnstrument  ( 

Musi cComponent  me, 

long  part, 

long  i nstrumentNumber  ); 


Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi cDevi ce 
(11-1028). 


part 

Part  containing  the  instrument  to  be  stored. 


Inside  QuickTime:  Function  l-Q 


11-1017 


MusicTask 


i nstrumentNumber 

Instrument  number  at  which  to  store  the  part.  The  value  must  be  between  1  and 
the  synthesizer's  modifiable  instrument  count,  as  defined  by  the 
modi fi  abl  elnstrumentCount  field  of  the  synthesizer's  Synthesi  zerDescri pti on 
(IV-2465)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  lets  you  store  modified  instruments. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c . h 

Programming  summary:  "Managing  Instruments  and  Parts"  (V-2921) 


MusicTask 


Allows  a  music  component  to  perform  tasks  it  must  perform  at  foreground  task 
time. 

ComponentResul t  MusicTask  ( 

Musi cComponent  me  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  must  be  called  periodically.  In  the  case  of  the  QuickTime  music 
synthesizer,  instruments  cannot  be  loaded  from  disk  at  interrupt  time,  so  if  the 
NASetlnstrumentNumberlnterruptSafe  (11-1044)  function  is  called,  the  instrument  is 
loaded  during  the  next  Musi  cTask  call. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Miscellaneous  Music  Component  Functions"  (V-2922) 


11-1018 


Inside  QuickTime:  Function  l-Q 


MusicUseDeviceConnection 


MusicUseDeviceConnection 


Tells  a  music  component  which  hardware  synthesizer  to  talk  to. 

ComponentResul t  MusicUseDeviceConnection  ( 

Musi cComponent  me, 

long  idl, 

long  i d 2  ); 


me 

Music  component  instance  identifier  returned  by  NAGetRegi  steredMusi  cDevi  ce 
(11-1028). 
i  dl 

The  ID  of  the  device  returned  in  the  i  dl  parameter  of  Musi  cGetDevi  ceConnecti  on 
(11-987). 
id2 

The  ID  of  the  device  returned  in  the  i  d2  parameter  of  Musi  cGetDevi  ceConnecti  on 
(11-987). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

This  call  is  implemented  only  for  hardware  synthesizers,  such  as  PCI  card  devices. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Managing  Synthesizers"  (V-2920) 


NACopyrightDialog 


Displays  a  copyright  dialog  box  with  information  specific  to  a  music  device. 

ComponentResul t  NACopyrightDialog  ( 

NoteAl 1 ocator  na, 

PicHandle  p, 

StringPtr  author. 


Inside  QuickTime:  Function  l-Q 


11-1019 


NADisposeN  oteChannel 


Stri ngPtr 
Stri ngPtr 
Stri ngPtr 
Modal Fi 1 terUPP 
1  ong 


copy ri ght , 
other , 
title, 
f i 1 terProc , 
refCon  ) ; 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 

P 

Ahandle  to  a  Pi  cture  (IV-2331)  structure  containing  the  image  resource  for  the 
dialog  box. 
author 

A  pointer  to  a  string  containing  author  information, 
copy ri ght 

A  pointer  to  a  string  containing  copyright  information, 
other 

A  pointer  to  a  string  containing  any  additional  information, 
ti  tl  e 

A  pointer  to  a  string  containing  title  information, 
f  i  1 terProc 

Pointer  to  a  Modal  Fi  1  terProc  (III— 2098)  callback. 
refCon 

A  reference  constant  value.  The  Movie  Toolbox  passes  this  reference  constant 
to  your  Modal  Fi  1  terProc  each  time  it  calls  it.  Use  this  parameter  to  point  to  a 
data  structure  containing  any  information  your  callback  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Note  Allocator  Interface  Tools"  (V-2918) 

Related  Java  Methods 

qu i c kti me. std. music. Not eAllocator. copy rightDialogt) 


NADisposeNoteChannel 

Deletes  a  specified  note  channel. 


11-1020 


Inside  QuickTime:  Function  l-Q 


NAFindNoteChannelTone 


ComponentResul t  NADi sposeNoteChannel  ( 
NoteAl 1 ocator  na, 

NoteChannel  noteChannel  ); 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 
noteChannel 

Note  channel  to  be  disposed.  You  obtain  the  note  channel  identifier  from 
NANewNoteChannel  (11-1030)  or  NANewNoteChannel  FromAtomi  clnstrument  (11-1031). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Q  u  i  c  kT i me  M  u  s i c .  h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 


NAFindNoteChannelT  one 


Locates  the  instrument  that  best  fits  a  requested  tone  description  for  a  specific 
channel. 


ComponentResul t  NAFindNoteChannelTone  ( 
NoteAl 1 ocator  na, 

NoteChannel  noteChannel  , 

ToneDescri pti on  *td, 

long  *i nstrumentNumber 


): 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 
noteChannel 

The  note  channel  for  which  you  want  an  instrument.  You  obtain  the  note 
channel  identifier  from  NANewNoteChannel  (11-1030)  or 
NANewNoteChannel  FromAtomi  clnstrument  (11-1031). 

td 

A  ToneDescri  pti  on  (IV-2487)  structure  that  describes  the  instrument  fit. 
i nstrumentNumber 

On  return,  the  number  of  the  instrument  that  best  fits  the  tone  description. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Inside  QuickTime:  Function  l-Q 


11-1021 


NAGetController 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 

Related  Java  Methods 

quickti me. std. music. NoteChannel .  findTonet ) 


NAGetController 


Retrieves  the  controller  settings  for  a  note  channel. 


ComponentResul t  NAGetController  ( 
NoteAl 1 ocator  na, 

NoteChannel  noteChannel , 

long  control  1 erNumber 

long  *control 1 erVal ue 


) : 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 
noteChannel 

Note  channel  for  which  to  get  controller  settings.  You  obtain  the  note  channel 
identifier  from  NANewNoteChannel  (11-1030)  or 
NANewNoteChannel  FromAtomi  clnstrument  (11-1031). 

control  1 erNumber 

The  controller  for  which  to  get  settings;  see  "Music  Controllers"  (IV-2682). 
control  1 erVal ue 

On  return,  the  value  for  the  controller  setting,  typically  0  (0x00 . 00)  to  32767 
(0x7F.FF). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 

Related  Java  Methods 

quickti me. std. music. NoteChannel. getControllert) 


11-1022 


Inside  QuickTime:  Function  l-Q 


NAGetDefaultMIDIInput 


See  Also 

For  the  corresponding  set  function,  see  NASetControl  1  er  (11-1042). 


NAGetDefaultMIDIInput 


Obtains  external  MIDI  connection  information. 

ComponentResul t  NAGetDefaultMIDIInput  ( 
NoteAl 1 ocator  na, 

Synthesi zerConnecti ons  *sc  ); 


na 

You  obtain  the  note  allocator  identifier  from  OpenComponent  (11-1130). 

sc 

On  return,  an  initialized  Synthesi  zerConnecti  ons  (IV-2464)  structure 
containing  information  about  the  external  MIDI  device  attached  to  the  system 
that  has  been  selected  as  the  default  MIDI  input  device. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  routine  calls  the  QuickTime  MIDI  components  to  query  them.  The  external 
MIDI  device  provides  note  input  directly  to  the  note  allocator. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusIc.h 

Programming  summary:  "Note  Allocator  Configuration  and  Utilities"  (V-2919) 

Related  Java  Methods 

qui cktime . std .  musi c . NoteAl 1 ocator. get DefaultM I DI Input!) 


See  Also 

For  the  corresponding  set  function,  see  NASetDefaul  tMIDI  Input  (11-1043). 


N  AGetlndN  oteChannel 


Returns  the  number  of  note  channels  handled  by  the  specified  note  allocator 
instance. 

ComponentResul t  NAGetlndNoteChannel  ( 

NoteAl 1 ocator  na. 


Inside  QuickTime:  Function  l-Q 


11-1023 


NAGetKnob 


1  ong 

NoteChannel 
1  ong 


i ndex , 
*nc , 

*seed  )  ; 


na 

You  obtain  the  note  allocator  identifier  from  the  Component  Manager's 
OpenComponent  (11-1130)  function, 
i  ndex 

The  index  of  the  note  channel.  If  0,  the  result  is  still  the  number  of  note  channels, 
but  the  nc  parameter  is  not  filled  out. 

nc 

The  note  channel  requested. 

seed 

A  number  that  changes  on  successive  calls  if  anything  significant  changes  about 
a  note  channel;  for  example,  if  the  note  channel  has  been  reallocated  or  released. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  can  also  return  a  requested  note  channel.  To  get  a  count  of  the  note 
channels,  pass  0  in  the  i  ndex  parameter.  To  get  a  specific  note  channel,  pass  the 
index  value  returned  by  a  previous  call  to  NAGetlndNoteChannel. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 

Related  Java  Methods 

quickti me. std. music. Not eAllocator.numNoteChannelsO, 
quickti me. std. music. Not eAllocator.getlndNoteChannelt) 


NAGetKnob 


Obtains  the  value  of  a  knob  for  a  given  note  channel. 

ComponentResul t  NAGetKnob  ( 

NoteAl 1 ocator  na, 

NoteChannel  noteChannel  , 

long  knobNumber, 

1 ong  *knobVal ue  ) ; 


11-1024 


Inside  QuickTime:  Function  l-Q 


NAGetMIDIPorts 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 
noteChannel 

The  note  channel  whose  knob  value  you  want  to  get.  You  obtain  the  note 
channel  identifier  from  NANewNoteChannel  (11-1030)  or 
NANewNoteChannel  FromAtomi  clnstrument  (11-1031). 

knobNumber 

The  index  or  ID  of  the  knob  whose  value  you  want  to  get. 
knobVal ue 

On  return,  a  pointer  to  the  value  of  the  knob. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 

Related  Java  Methods 

qui cktime . std .musi c . NoteChannel . get Knob ( ) 

See  Also 

For  the  corresponding  set  function,  see  NASetKnob  (11-1045). 


NAGetMIDIPorts 


The  MIDI  input  and  output  ports  available  to  a  note  allocator. 

ComponentResul t  NAGetMIDIPorts  ( 

NoteAl 1 ocator  na, 

QTMIDIPortLi stHandle  *inputPorts, 

QTMIDIPortListHandl e  *outputPorts  ); 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 
i nputPorts 

On  return,  a  handle  giving  the  number  of  input  ports  (the  first  two  bytes) 
followed  by  a  list  of  QTMIDI  Port  (IV-2357)  structures. 
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11-1025 


NAGetNoteChannellnfo 


outputPorts 

On  return,  a  handle  giving  the  number  of  output  ports  (the  first  two  bytes) 
followed  by  a  list  of  QTMIDI  Port  (IV-2357)  structures. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  routine  calls  the  QuickTime  MIDI  components  to  query  them. 

Special  Considerations 

NAGetMIDIPorts  is  the  correct  call  for  applications  to  make.  They  should  not  call 
QTMIDIGetMIDI Ports. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Note  Allocator  Configuration  and  Utilities"  (V-2919) 

Related  Java  Methods 

quickti me. std. music. Not eAllocator.getMIDIInPortsO, 
quickti me. std. music. Not eAllocator.getMIDIOutPortsO 


NAGetNoteChannellnfo 


Returns  the  index  of  the  music  component  for  the  allocated  channel  and  its  part 
number  on  that  music  component. 

ComponentResul t  NAGetNoteChannellnfo  ( 

NoteAl 1 ocator  na, 

NoteChannel  noteChannel  , 

long  *index, 

1 ong  *part  ) ; 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 
noteChannel 

Note  channel  to  get  information  about.  You  obtain  the  note  channel  identifier 
from  NANewNoteChannel  (11-1030)  or  NANewNoteChannel  FromAtomi  clnstrument 
(11-1031). 


i  ndex 

Music  component  index. 


11-1026 


Inside  QuickTime:  Function  l-Q 


NAGetNoteRequest 


part 

Music  component  part  pointer. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  NAGetNoteChannellnfo  function  allows  direct  access  to  the  music  component 
allocated  to  the  note  channel  by  the  note  allocator.  The  index  returned  becomes 
invalid  if  music  components  are  subsequently  registered  or  unregistered. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 

Related  Java  Methods 

qui ckti me . std .musi c . NoteCh a nnel . get  Index  Inf o( ) , 
qui cktime . std .musi c . NoteCh a nnel . get Part  Inf o( ) 


NAGetNoteRequest 


Retrieves  the  NoteRequest  (IV-2323)  structure  that  was  passed  to  a  note  channel. 

ComponentResul t  NAGetNoteRequest  ( 

NoteAl 1 ocator  na, 

NoteChannel  noteChannel  , 

NoteRequest  *nrOut  ); 


na 

You  obtain  the  note  allocator  identifier  from  the  Component  Manager's 
OpenComponent  (11-1130)  function. 
noteChannel 

The  note  channel  whose  note  request  you  want  to  get.  You  obtain  the  note 
channel  identifier  from  NANewNoteChannel  (11-1030)  or 
NANewNoteChannel  FromAtomi  clnstrument  (11-1031). 

nrOut 

On  return,  the  NoteRequest  (IV-2323)  structure  that  was  used  when  the 
specified  note  channel  was  allocated. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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11-1027 


NAGetRegisteredMusicDevice 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 

Related  Java  Methods 

quickti me. std. music. NoteChannel. get Note Request ( ) 


NAGetRegisteredMusicDevice 


Returns  details  about  music  components  registered  to  the  specified  note  allocator 
instance. 

ComponentResul t  NAGetRegisteredMusicDevice  ( 

NoteAl 1 ocator  na, 

long  index, 

OSType  *synthType, 

Str31  name, 

SynthesizerConnections  Connections, 

Musi cComponent  *mc  ); 


na 

You  obtain  the  note  allocator  identifier  from  the  Component  Manager's 
OpenComponent  (11-1130)  function, 
i  ndex 

The  index  of  the  music  component  to  get  information  about.  To  get  a  count  of 
the  registered  music  components,  pass  0  in  the  index  parameter.  The  return 
value  is  the  count  of  components.  To  get  information  about  one  of  the  music 
components  registered  with  the  note  allocator,  pass  the  music  component 
index  in  the  i  ndex  parameter.  The  index  value  can  be  1  through  the  number  of 
registered  components  returned  by  a  previous  call  to 
NAGetRegi steredMusi cDevi ce. 

synthType 

Synthesizer  type. 

name 

Synthesizer  name  as  a  text  string, 
connecti ons 

A  synthesizer  connections  for  MIDI  devices  structure. 


11-1028 
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NALoseDefaultMIDIInput 


me 

Music  component  instance  identifier. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

If  you  request  information  about  a  specific  registered  music  component,  this 
function  returns  the  type  of  synthesizer  the  component  supports  in  the  synthType 
parameter,  the  name  of  the  synthesizer  in  the  name  parameter,  and  the  music 
component  identifier  in  the  me  parameter.  For  MIDI  devices,  it  returns  a  pointer  to 
a  MIDI  devices  structure  with  information  about  the  synthesizer  connections. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Note  Allocator  Configuration  and  Utilities"  (V-2919) 

Related  Java  Methods 

qui cktime . std .musi c . NoteAl locator. numMusi  cComponents ( ) , 
qui cktime . std .musi c . NoteAl 1  oca tor . getRegi steredMusi cDevI  ce( ) 


NALoseDefaultMIDIInput 


Removes  the  external  default  MIDI  service  procedure  call,  if  previously  defined  by 
NAUseDefaul  tMIDI  Input  (11-1052). 

ComponentResul t  NALoseDefaultMIDIInput  ( 

NoteAl 1 ocator  na  ); 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 

Related  Java  Methods 

qui cktime . std .musi c . NoteAl locator. loseDefaultMIDIInputl) 


Inside  QuickTime:  Function  l-Q 


11-1029 


N  ANe  wN  oteChannel 


NANewNoteChannel 


Requests  a  new  note  channel  with  the  qualities  described  in  a  NoteRequest  (IV-2323) 
structure. 

ComponentResul t  NANewNoteChannel  ( 

NoteAl 1 ocator  na, 

NoteRequest  *noteRequest , 

NoteChannel  *outChannel  ) ; 


na 

You  obtain  the  note  allocator  identifier  from  the  Component  Manager's 
OpenComponent  (11-1130)  function. 
noteRequest 

A  pointer  to  a  NoteRequest  (IV-2323)  structure. 
outChannel 

On  return,  a  pointer  to  an  identifier  for  a  new  note  channel  or  N I L  if  the  function 
fails  to  create  a  note  channel. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  searches  all  available  music  components  for  the  instrument  that  best 
matches  the  specifications  in  the  ToneDescri  pti  on  (IV-2487)  structure  that  is 
contained  within  the  noteRequest  parameter.  If  an  error  occurs,  the  new  note 
channel  is  initialized  to  NIL.  The  caller  can  request  an  instrument  that  is  not 
currently  allocated  to  a  part.  In  that  case,  this  function  may  return  a  value  in 
outChannel,  even  though  the  request  cannot  initially  be  satisfied.  The  note  channel 
may  become  valid  at  a  later  time,  as  other  note  channels  are  released  or  other  music 
components  are  registered. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c . h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 

Related  Java  Methods 

qu i ckti me. std. music. NoteChannel .NoteChannel ( ) 


11-1030 
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N  AN  e  wN  oteChannelFrom  Atomiclnstrument 


NANewNoteChannelFromAtomicInstrument 


Requests  a  new  note  channel  for  an  atomic  instrument. 

ComponentResul t  NANewNoteChannel FromAtomi clnstrument  ( 
NoteAl 1 ocator  na, 

Atomi  clnstrumentPtr  i  instrument , 
long  flags, 

NoteChannel  *outChannel  ); 


na 

You  obtain  the  note  allocator  identifier  from  the  Component  Manager's 
OpenComponent  (11-1130)  function, 
i nstrument 

A  pointer  to  the  atomic  instrument.  This  may  be  a  dereferenced  locked  QT  atom 
container. 

fl  ags 

Flags  (see  below)  that  specify  details  of  initializing  a  part  with  an  atomic 
instrument. 
outChannel 

On  return,  a  pointer  to  an  identifier  for  a  new  note  channel  or  N I L  if  the  function 
fails  to  create  a  note  channel. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Conmstants 

kSet Atomi clnstKeepOri ginal Instrument 
Keep  original  sample  after  expansion. 
kSetAtomi clnstShareAcrossParts 

Remove  the  instrument  when  the  application  quits. 
kSetAtomi clnstCal 1 erTosses 

The  caller  isn't  keeping  a  copy  of  the  atomic  instrument  for  later  calls  to 
NASetAtomi  clnstrument  (11-1041). 
kSetAtomi clnstDontPreprocess 

Don't  expand  the  sample.  You  would  only  set  this  bit  if  you  know  the 
instrument  is  digitally  clean  or  you  got  it  from  a  Musi  cGet  Part  Atomi  clnstrument 
(11-1000)  call. 

Discussion 

This  function  takes  a  note  allocator  identifier  in  the  na  parameter  and  a  pointer  to 
the  atomic  instrument  you  are  requesting  a  new  channel  for  in  the  i  nstrument 
parameter.  Among  other  things,  you  can  specify  how  to  handle  the  expanded 
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11-1031 


N  APick  Arrangement 


sample  with  the  flags  parameter.  The  function  returns  the  note  channel  allocated 
for  the  instrument  in  the  outChannel  parameter,  or  NI L  if  an  error  occurs. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 

Related  Java  Methods 

qui ckti me . std .musi c . Atomi c Instrument . newNoteChannel ( ) 


NAPickArrangement 


Displays  a  dialog  box  to  allow  instrument  selection. 


ComponentResul t  NAPickArrangement  ( 


NoteAl 1 ocator 
Modal  Fi  1  terllPP 
Stri ngPtr 
1  ong 
1  ong 
T  rack 
Stri ngPtr 


na , 

f  i  1 terProc , 
prompt , 
zerol , 
zero2 , 
t. 

songName  ) ; 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 
f  i  1 terProc 

A  Universal  Procedure  Pointer  to  a  Modal  Fi  1  terProc  (III— 2098)  callback, 
prompt 

A  pointer  to  a  dialog  box  prompt  string, 
zerol 

Must  be  0. 
zero2 

Must  be  0. 
t 

The  arrangement  movie  track  number. 
songName 

A  pointer  to  the  name  of  a  song  to  display  in  the  dialog  box. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


11-1032 
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NAPickEditlnstrument 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Q  u  i  c  kT i me  M  u  s i c .  h 

Programming  summary:  "Note  Allocator  Interface  Tools"  (V-2918) 

Related  Java  Methods 

qui cktime . std .musi c . NoteAl 1  oca tor . pi ckArrangementl ) 


NAPickEditlnstrument 


Presents  a  user  interface  for  changing  the  instrument  in  a  live  note  channel  or 
modifying  an  atomic  instrument. 


Component Res ul t  NAPi ckEdi t Instrument 


NoteAl 1 ocator 
Modal Fi 1 terUPP 
Stri ngPtr 
1  ong 

NoteChannel 
Atomi clnstrument 
1  ong 


na , 

fi  1 terProc , 
prompt , 
refCon , 
nc , 
ai  , 

flags  ); 


( 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 
fi 1 terProc 

Pointer  to  a  Modal  Fi  1  terProc  (III— 2098)  callback, 
prompt 

Dialog  box  prompt  "New  Instrument". 
refCon 

A  reference  constant  value.  The  Movie  Toolbox  passes  this  reference  constant 
to  your  Modal  Fi  1  terProc  callback  each  time  it  calls  it.  Use  this  parameter  to 
point  to  a  data  structure  containing  any  information  your  callback  needs. 

nc 

The  live  note  channel  that  appears  in  the  dialog  box.  If  you  specify  a  note 
channel,  set  the  ai  parameter  to  0.  You  obtain  the  note  channel  identifier  from 
NANewNoteChannel  (11-1030)  or  NANewNoteChannel  FromAtomi  clnstrument  (11-1031). 
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11-1033 


NAPickEditlnstrument 


ai 

The  atomic  instrument  that  appears  in  the  dialog  box.  If  you  specify  an  atomic 
instrument,  set  the  nc  parameter  to  0.  You  obtain  the  atomic  instrument  from 
InstrumentGetlnst  (11-767). 
fl  ags 

Flags  (see  below)  that  limit  the  instruments  presented.  If  the  kPi  ckDontMi  x  flag 
is  set,  the  dialog  box  does  not  display  a  mix  of  synthesizer  part  types.  For 
example,  if  the  current  instrument  is  a  drum,  only  available  drums  appear  in 
the  dialog  box.  The  kPi  ckSameSynth  flag  allows  selections  only  within  the 
current  synthesizer.  The  kPi  ckUserlnsts  flag  allows  user  modifiable 
instruments  to  appear.  If  the  kPi  ckEdi  tAl  1  owPi  ck  flag  is  not  set,  no  dialog  box 
appears. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

kPi ckDontMi x 

Show  either  all  drum  kits  or  all  instruments  depending  on  the  current 
instrument.  For  example,  if  it's  a  drum  kit,  show  only  drum  kits. 
kPi ckSameSynth 

Show  only  instruments  from  the  current  synthesizer. 
kPi ckUserlnsts 

Show  modifiable  instruments  in  addition  to  ROM  instruments. 
kPi ckEdi tAl 1 owPi ck 

Present  the  instrument  picker  dialog  box.  Used  only  with 
NAPi ckEdi t Instrument. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Note  Allocator  Interface  Tools"  (V-2918) 

Related  Java  Methods 

qui ckti me . std .musi c . Atomi c Instrument . pi ckEdi t Instrument! ) , 
quicktime.std.music.NoteChannel.pickEdi t Instrument! ) 


See  Also 

See  NAPi cklnstrument  (11-1035). 


11-1034 


Inside  QuickTime:  Function  l-Q 


N  APicklnstrument 


NAPicklnstrument 


Presents  a  user  interface  for  picking  an  instrument. 


ComponentResul t  NAPicklnstrument  ( 


puiicM  u\cou  i  u  nr 

NoteAl 1 ocator 
Modal Fi 1 terUPP 
Stri ngPtr 
ToneDescri pti on 
unsigned  long 
1  ong 
1  ong 
1  ong 


na , 

fi  1 terProc 
prompt , 

*sd , 
f 1 ags , 
refCon , 
reservedl , 
reserved2 


); 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 
fi  1 terProc 

Pointer  to  a  Modal  Fi  1  terProc  (III— 2098)  callback, 
prompt 

A  pointer  to  the  dialog  box  prompt  "New  Instrument", 
sd 

On  entry,  the  tone  description  of  the  instrument  that  appears  in  the  picker 
dialog  box.  On  return,  a  tone  description  of  the  instrument  the  user  selected. 

fl  ags 

Flags  (see  below)  that  determine  whether  to  display  the  picker  dialog  box  and 
what  instruments  appear  for  selection.  If  the  kPi  ckDontMi  x  flag  is  set,  the  dialog 
box  does  not  display  a  mix  of  synthesizer  part  types.  For  example,  if  the  current 
instrument  is  a  drum,  only  available  drums  appear  in  the  dialog  box.  The 
kPi  ckSameSynth  flag  allows  selections  only  within  the  current  synthesizer.  The 
kPi  ckUserlnsts  flag  allows  user  modifiable  instruments  to  appear.  The 
kPi  ckEdi  tAl  1  owPi  ck  flag  is  used  only  with  NAPi  ckEdi  tlnstrument  (11-1033). 
refCon 

A  reference  constant  value.  The  Movie  Toolbox  passes  this  reference  constant 
to  your  Modal  Fil  terProc  callback  each  time  it  calls  it.  Use  this  parameter  to 
point  to  a  data  structure  containing  any  information  your  callback  needs, 
reservedl 

Must  contain  0. 
reserved2 

Must  contain  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Inside  QuickTime:  Function  l-Q 


11-1035 


NAPlayNote 


flags  Constants 

kPi ckDontMi x 

Show  either  all  drum  kits  or  all  instruments  depending  on  the  current 
instrument.  For  example,  if  it's  a  drum  kit,  show  only  drum  kits. 

kPi ckSameSynth 

Show  only  instruments  from  the  current  synthesizer. 
kPi  ckllserlnsts 

Show  modifiable  instruments  in  addition  to  ROM  instruments. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Note  Allocator  Interface  Tools"  (V-2918) 

Related  Java  Methods 

qu i c kt i me. std. music. Tone Description. pi cklnstrument ( ) 


See  Also 

For  a  similar  function  that  includes  the  kPi  ckEdi  tAl  1  owPi  ck  flag,  see 
NAPi  ckEdi  tlnstrument  (11-1033). 


NAPlayNote 


Plays  a  note  with  a  specified  pitch  and  velocity  on  the  specified  note  channel. 


ComponentResul t  NAPlayNote  ( 
NoteAl 1 ocator  na, 

NoteChannel  noteChannel 

long  pitch, 

1 ong  vel oci ty  ) ; 


na 

You  obtain  the  note  allocator  identifier  from  OpenComponent  (11-1130). 
noteChannel 

The  note  channel  to  play  the  note.  You  obtain  the  note  channel  identifier  from 
the  NANewNoteChannel  (11-1030)  or  the  NANewNoteChannel  FromAtomi  clnstrument 
(11-1031)  function, 
pi  tch 

The  pitch  at  which  to  play  the  note.  You  can  specify  values  as  integer  pitch 
values  (0-127  where  60  is  middle  C)  or  fractional  pitch  values  (256  (0x1 . 00) 


11-1036 


Inside  QuickTime:  Function  l-Q 


NAPrerollNoteChannel 


through  32767  (0x7  F .  FF)).  If  the  pitch  is  a  number  from  0  to  127,  then  it  is  the 
MIDI  pitch,  where  60  is  middle  C.  If  the  pitch  is  a  positive  number  above  65535, 
then  the  value  is  a  fixed-point  pitch  value.  Thus,  microtonal  values  can  be 
specified.  Negative  values  are  not  defined  and  should  not  be  used. 

vel oci ty 

The  velocity  with  which  the  key  is  struck.  Typically,  this  translates  directly  to 
volume,  but  on  many  synthesizers  this  also  subtly  alters  the  timbre  of  the  tone. 
A  value  of  0  is  silence;  a  value  of  127  is  maximum  force. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusIc.h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 

Related  Java  Methods 

qui ckti me . std .musi c . NoteChannel . pi ayNoteRaw( ) , 
qui cktime . std .musi c . NoteChannel . pi ayNoteCents ( ) , 
qui ckti me . std .musi c . NoteChannel . pi ayNote( ) 


NAPrerollNoteChannel 


Attempts  to  reallocate  the  note  channel  if  it  was  invalid  previously. 

ComponentResul t  NAPrerollNoteChannel  ( 

NoteAl 1 ocator  na, 

NoteChannel  noteChannel  ); 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 
noteChannel 

Note  channel  to  be  re-allocated.  You  obtain  the  note  channel  identifier  from 
NANewNoteChannel  (11-1030)  or  NANewNoteChannel  FromAtomi  clnstrument  (11-1031). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  NAPrerollNoteChannel  function  attempts  to  reallocate  the  note  channel,  if  it  was 
invalid  previously.  It  could  have  been  invalid  if  there  were  no  available  voices  on 
any  registered  music  components  when  the  note  channel  was  created. 


Inside  QuickTime:  Function  l-Q 


11-1037 


NARegisterMusicDevice 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 

Related  Java  Methods 

quickti me. std. music. NoteChannel .preroll ( ) 


NARegisterMusicDevice 


Registers  a  music  component  with  the  note  allocator. 

ComponentResul t  NARegisterMusicDevice  ( 

NoteAl 1 ocator  na, 

OSType  synthType, 

Str31  name, 

Synthesi  zerConnecti  ons  Connections  ); 


na 

You  obtain  the  note  allocator  identifier  from  OpenComponent  (11-1130). 
synthType 

Subtype  of  the  music  component. 

name 

The  synthesizer  name.  This  parameter  provides  a  means  of  distinguishing 
multiple  instances  of  the  same  type  of  device  and  is  a  string  that  can  be 
displayed  to  the  user.  If  no  value  is  passed  in  the  name  parameter,  the  name 
defaults  to  the  name  of  the  music  component  type.  The  name  appears  in  the 
instrument  picker  dialog  box. 
connecti ons 

A  Synthesi  zerConnecti  ons  (IV-2464)  structure  that  describes  the  hardware 
connections  to  a  MIDI  device. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Note  Allocator  Configuration  and  Utilities"  (V-2919) 


11-1038 


Inside  QuickTime:  Function  l-Q 


NAResetNoteChannel 


Related  Java  Methods 

qui cktime . std .musi c . NoteAl locator. regi sterMusi cDevi ce( ) 


NAResetNoteChannel 


Turns  off  all  currently  "on"  notes  on  the  note  channel  and  resets  all  controllers  to 
their  default  values. 

ComponentResul t  NAResetNoteChannel  ( 

NoteAl 1 ocator  na, 

NoteChannel  noteChannel  ); 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 
noteChannel 

The  note  channel  to  reset.  You  obtain  the  note  channel  identifier  from 
NANewNoteChannel  (11-1030)  or  NANewNoteChannel  FromAtomi  clnstrument  (11-1031). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  resets  the  specified  note  channel  by  turning  "off"  any  note  currently 
playing.  All  controllers  are  reset  to  their  default  state.  The  effects  of  the 
NAResetNoteChannel  call  are  propagated  down  to  the  allocated  part  within  the 
appropriate  music  component. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Q  u  i  c  kT i me  M  u  s i c .  h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 

Related  Java  Methods 

qui cktime . std .musi c . NoteChannel .reset! ) 


NASaveMusicConfiguration 

Saves  the  current  list  of  registered  devices  to  a  file. 

ComponentResul t  NASaveMusicConfiguration  ( 
NoteAl 1 ocator  na  ); 


Inside  QuickTime:  Function  l-Q 


11-1039 


NASendMIDI 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  NASaveMusi  cConf  i  gurati  on  function  saves  the  current  list  of  registered  devices 
to  a  file.  This  file  is  read  whenever  a  note  allocator  connection  is  opened,  restoring 
the  previously  configured  list  of  devices.  The  list  is  saved  in  the  QuickTime 
Preferences  file. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi c . h 

Programming  summary:  "Note  Allocator  Configuration  and  Utilities"  (V-2919) 

Related  Java  Methods 

quickti me. std. music. Not eAllocator.saveMusicConfigurationt) 


NASendMIDI 


Sends  a  MIDI  music  packet  to  a  synthesizer  that  contains  a  specific  note  channel. 

ComponentResul t  NASendMIDI  ( 

NoteAl 1 ocator  na, 

NoteChannel  noteChannel  , 

MusicMIDIPacket  *mp  ); 


na 

You  obtain  the  note  allocator  identifier  from  the  Component  Manager's 
OpenComponent  (11-1130)  function. 
noteChannel 

The  function  sends  the  packet  to  the  synthesizer  that  contains  this  note  channel. 
You  obtain  the  note  channel  identifier  from  the  NANewNoteChannel  (11-1030)  or 
the  NANewNoteChannel  FromAtomi  clnstrument  (11-1031)  function. 

mp 

The  music  packet  to  be  sent. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


11-1040 


Inside  QuickTime:  Function  l-Q 


NASetAtomicInstrument 


Discussion 

This  function  sends  the  MIDI  music  packet  pointed  to  by  the  mp  parameter  to  the 
synthesizer  that  contains  the  note  channel  identified  by  the  noteChannel  parameter. 
The  na  parameter  specifies  the  note  allocator  instance  to  use. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusIc.h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 

Related  Java  Methods 

qui cktime . std .musi c . NoteChannel . sendMIDI ( ) 


NASetAtomicInstrument 


Initializes  a  synthesizer  part  with  an  atomic  instrument. 


Component  Res ul t  NASetAtomi c Instrument 
NoteAl 1 ocator  na, 

NoteChannel  noteChannel 

Atomi clnstrumentPtr  i nstrument , 
long  flags  ); 


( 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 
noteChannel 

The  note  channel  to  apply  the  atomic  instrument  to.  You  obtain  the  note 
channel  identifier  from  NANewNoteChannel  (11-1030)  or 
NANewNoteChannel  FromAtomi  clnstrument  (11-1031). 
i nstrument 

A  pointer  to  the  atomic  instrument.  This  can  be  a  locked,  dereferenced  atomic 
instrument. 

fl  ags 

Flags  (see  below)  that  detail  how  to  initialize  the  part. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

kSetAtomi clnstKeepOri gi nal  Instrument 
Keep  original  sample  after  expansion. 


Inside  QuickTime:  Function  l-Q 


11-1041 


NASetController 


kSetAtomi clnstShareAcrossParts 

Remove  the  instrument  when  the  application  quits. 
kSetAtomi clnstCallerTosses 

The  caller  isn't  keeping  a  copy  of  the  atomic  instrument  for  later  calls  to 
NASetAtomi clnstrument. 

kSetAtomi clnstDontPreprocess 

Don't  expand  the  sample.  You  would  only  set  this  bit  if  you  know  the 
instrument  is  digitally  clean  or  you  got  it  from  Musi  cGetPartAtomi  clnstrument 
(11-1000). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 

Related  Java  Methods 

quickti me. std. music. NoteChannel . setAtomi clnstrument ( ) 


NASetController 


Changes  the  controller  setting  on  a  note  channel  to  a  specified  value. 

ComponentResul t  NASetController  ( 

NoteAl 1 ocator  na, 

NoteChannel  noteChannel  , 

long  controll erNumber , 

long  control  1 erVal ue  ); 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 
noteChannel 

Note  channel  on  which  to  change  controller.  You  obtain  the  note  channel 
identifier  from  NANewNoteChannel  (11-1030)  or 
NANewNoteChannel  FromAtomi  clnstrument  (11-1031). 
control  1 erNumber 

The  controller  to  set;  see  "Music  Controllers"  (IV-2682). 
control  1 erVal ue 

Value  for  controller  setting;  typically  0  (0x00 . 00)  to  32767  (0x7F .  FF). 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


11-1042 


Inside  QuickTime:  Function  l-Q 


NASetDefaultMIDIInput 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 

Related  Java  Methods 

qui cktime . std .musi c . NoteChannel . setControl 1 erRaw( ) , 
qui cktime . std .musi c . NoteChannel . setControl 1 er( ) 

See  Also 

For  the  corresponding  get  function,  see  NAGetController  (11-1022). 


NASetDefaultMIDIInput 


Initializes  an  external  MIDI  device  used  to  receive  an  external  note  input. 

ComponentResul t  NASetDefaultMIDIInput  ( 

NoteAl 1 ocator  na, 

Synthes! zerConnecti ons  *sc  ); 


na 

You  obtain  the  note  allocator  identifier  from  the  Component  Manager's 
OpenComponent  (11-1130)  function, 
sc 

A  Synthes i  zerConnecti  ons  (IV-2464)  structure  that  describes  how  a  MIDI 
device  is  connected.  The  Synthes!  zerConnecti  ons  fields  cl  i  entID,  i  nputPortID, 
and  outputPortID  are  MIDI  Manager  identifiers.  The  midi  Channel  field  is  the 
MIDI  system  channel  value. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Note  Allocator  Configuration  and  Utilities"  (V-2919) 

Related  Java  Methods 

qui cktime . std .musi c . NoteAl 1 ocator. s etDefaultM I DI Input!) 


See  Also 

For  the  corresponding  get  function,  see  NAGetDefaultMIDIInput  (II— 1 023) . 


Inside  QuickTime:  Function  l-Q 


11-1043 


NASetlnstrumentNumber 


NASetlnstrumentNumber 


Initializes  initializes  a  synthesizer  part  with  the  specified  instrument. 

ComponentResul t  NASetlnstrumentNumber  ( 

NoteAl 1 ocator  na, 

NoteChannel  noteChannel  , 

long  i nstrumentNumber  ); 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 
noteChannel 

Note  channel  to  initialize  with  the  instrument.  You  obtain  the  note  channel 
identifier  from  NANewNoteChannel  (11-1030)  or 
NANewNoteChannel  FromAtoml  clnstrument  (11-1031). 
i nstrumentNumber 

Number  of  the  instrument  to  initialize  the  part  with.  This  number  is  unique  to 
each  synthesizer.  General  MIDI  synthesizers  all  share  the  range  1-128  and 
16365  to  kLastDrumKi  t. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 

Related  Java  Methods 

qu ickti me. std. music. NoteChannel . set  Inst  rumen t Number ( ) 


NASetlnstrumentNumberlnterruptSafe 


Initializes  a  synthesizer  part  with  the  specified  instrument  during  interrupt  time. 

ComponentResul t  NASetlnstrumentNumberlnterruptSafe  ( 

NoteAl 1 ocator  na, 

NoteChannel  noteChannel  , 

long  i nstrumentNumber  ); 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 


11-1044 


Inside  QuickTime:  Function  l-Q 


NASetKnob 


noteChannel 

Note  channel  to  initialize  with  the  instrument.  You  obtain  the  note  channel 
identifier  from  NANewNoteChannel  (11-1030)  or 
NANewNoteChannel  FromAtomi  clnstrument  (11-1031). 
i nstrumentNumber 

Number  of  the  instrument  to  initialize  the  part  with. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

If  the  instrument  is  not  already  loaded  when  you  call 

NASetlnstrumentNumberlnterruptSafe,  you  have  to  wait  for  the  next  call  to  NATask 
(11-1049)  for  the  instrument  to  become  available. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 


NASetKnob 


Sets  a  note  channel  knob  to  a  particular  value. 

ComponentResul t  NASetKnob  ( 

NoteAl 1 ocator  na, 

NoteChannel  noteChannel  , 

long  knobNumber, 

long  knobValue  ); 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 
noteChannel 

Note  channel  on  which  to  set  the  knob  value.  You  obtain  the  note  channel 
identifier  from  NANewNoteChannel  (11-1030)  or 
NANewNoteChannel  FromAtomi  clnstrument  (11-1031). 

knobNumber 

Index  or  ID  of  the  knob  to  be  set. 
knobVal ue 

Value  to  set  knob  to. 


Inside  QuickTime:  Function  l-Q 


11-1045 


NASetNoteChannelBalance 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c . h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 

Related  Java  Methods 

qu i ckti me. std. music. NoteChannel  .setKnob( ) 


See  Also 

For  the  corresponding  get  function,  see  NAGetKnob  (11-1024). 


NASetNoteChannelBalance 


Modifies  the  pan  controller  setting  for  a  note  channel. 

ComponentResul t  NASetNoteChannelBalance  ( 

NoteAl 1 ocator  na, 

NoteChannel  noteChannel  , 

1 ong  bal ance  ) ; 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 
noteChannel 

The  note  channel  to  be  balanced.  You  obtain  the  note  channel  identifier  from 
NANewNoteChannel  (11-1030)  or  NANewNoteChannel  FromAtomi  clnstrument  (11-1031). 

bal ance 

Specifies  how  to  modify  the  pan  controller  setting.  Valid  values  are  from  -128 
to  128  for  left  to  right  balance. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 

Related  Java  Methods 

qu ickti me. std. music. NoteChannel .setBalancet ) 


11-1046 


Inside  QuickTime:  Function  l-Q 


NASetNoteChannelSoundLocalization 


NASetNoteChannelSoundLocalization 


Passes  sound  localization  data  to  a  note  channel. 

ComponentResul t  NASetNoteChannel SoundLocal i zati on  ( 
NoteAl 1 ocator  na, 

NoteChannel  noteChannel  , 

Handle  data  ); 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 
noteChannel 

The  note  channel  to  pass  the  data  to.  You  obtain  the  note  channel  identifier  from 
NANewNoteChannel  (11-1030)  or  NANewNoteChannel  FromAtomi  clnstrument  (11-1031). 

data 

Sound  localization  data. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Q  u  i  c  kT i me  M  u  s i c .  h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 

Related  Java  Methods 

qui ckti me . std .  musi c . NoteChannel . set Sound  Local i zati on ( ) 


NASetNoteChannelV  olume 


Sets  the  volume  on  the  specified  note  channel. 

ComponentResul t  NASetNoteChannel Vol ume  ( 
NoteAl 1 ocator  na, 

NoteChannel  noteChannel  , 

Fixed  volume  ); 


You  obtain  the  note  allocator  identifier  from  the  Component  Manager's 
OpenComponent  (11-1130)  function. 
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11-1047 


NAStuffToneDescription 


noteChannel 

The  note  channel  to  reset.  You  obtain  the  note  channel  identifier  from  the 
NANewNoteChannel  (11-1030)  or  the  NANewNoteChannel FromAtomi c Instrument 
(11-1031)  function, 
vol ume 

A  fixed  16.16  number.  NASetNoteChannel  Vol  ume  sets  the  volume  for  the  note 
channel,  which  is  different  from  a  kControllerVolume  setting.  Both  volume 
settings  allow  fractional  values  of  0.0  to  1.0.  Each  value  modifies  the  other.  For 
example,  a  kControl  1  erVol  ume  value  of  0.5  and  a  NASetNoteChannel  Vol  ume  value 
of  0.5  result  in  a  0.25  volume  level. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 

Related  Java  Methods 

qu ickti me. std. music. NoteChannel. setVol ume( ) 


N  AStuf  f  T  oneDescription 


Initializes  a  tone  description  structure  with  the  details  of  a  General  MIDI  note 
channel. 

ComponentResul t  NAStuffToneDescription  ( 

NoteAl 1 ocator  na, 

long  gmNumber, 

ToneDescription  *td  ); 


na 

You  obtain  the  note  allocator  identifier  from  the  Component  Manager's 
OpenComponent  (11-1130)  function. 
gmNumber 

A  General  MIDI  instrument  number, 
td 

On  return,  an  initialized  tone  description.  The  instrument  name  field  will  be 
filled  in  with  the  string  name  for  the  instrument. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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NATask 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Note  Allocator  Interface  Tools"  (V-2918) 

Related  Java  Methods 

qui cktime . std .musi c .ToneDescri pti on . ToneDescri pti on( ) , 
qui cktime . std .musi c .ToneDescri pti on . stuf f ( ) , 
qui cktime . std .musi c . NoteChannel . NoteChannel ( ) 


NATask 


Called  periodically  to  allow  the  note  allocator  to  perform  tasks  in  foreground  task 
time. 

ComponentResul t  NATask  ( 

NoteAl 1 ocator  na  ); 


na 

You  obtain  the  note  allocator  identifier  from  the  Component  Manager's 
OpenComponent  (11-1130)  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  NATask  function  calls  each  registered  music  component's  Musi  cTask  (11-1018) 
function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Note  Allocator  Configuration  and  Utilities"  (V-2919) 

Related  Java  Methods 

qui cktime . std .musi c . NoteAl locator. t a  s  k ( ) 


Native  EventT  oMacEvent 


Converts  Win32  messages  to  Macintosh  events. 


Inside  QuickTime:  Function  l-Q 
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N  ativePathN  ameToFS  Spec 


long  Nati veEventToMacEvent  ( 

void  *nati veEvent , 

EventRecord  *macEvent  ); 

nati veEvent 

A  pointer  to  a  Windows  32  message. 
macEvent 

A  pointer  to  Macintosh  EventRecord  (IV-2246)  structure  to  be  filled  in. 
function  result  Returns  noErr  if  the  translation  succeeded. 

Discussion 

This  function  translates  Win32  message  types  into  Macintosh  event  types  and  fills 
in  the  various  other  EventRecord  (IV-2246)  fields  based  on  the  source  Win32  MSG. 
Typically,  when  your  application  hosts  a  movie  controller,  it  should  call  this 
function  to  translate  a  Win32  MSG  to  an  EventRecord,  and  then  pass  the  resulting 
EventRecord  to  MCIsPl  ayerEvent  (11-819)  for  processing.  You  should  never  call  this 
function  and  then  exit  early  from  your  WndProc  without  calling  the  Windows 
function  DefWi  ndowProc  or  returning  an  appropriate  result  code  from  your  WndProc. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML.h 


NativePathNameToFSSpec 


Returns  an  FSSpec  (IV-2262)  structure  for  a  file  from  a  Windows  native  pathname. 

OSErr  NativePathNameToFSSpec  ( 
char  *inName, 

FSSpec  *outFile, 

1 ong  f 1 ags  ) ; 

i nName 

A  pointer  to  the  Windows  native  C  string  pathname. 
outFi  1  e 

A  pointer  to  FSSpec  (IV-2262)  structure, 
fl  ags 

Contains  flags  that  control  the  conversion.  There  are  no  flags  currently  defined, 
so  you  should  pass  0. 
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NAUnregisterMusicDevice 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error.  This 
function  returns  noErr  even  if  the  file  does  not  currently  exist;  in  this 
case,  the  resulting  FSSpec  (IV-2262)  structure  is  valid  for  creating  the 
file. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier.  Note  that  earlier  documentation  incorrectly 
stated  that  if  the  file  does  not  currently  exist,  the  error  fnf  Err  is  returned.  This  is 
only  true  for  QuickTime  4.0.  QuickTime  4.01  and  later  (as  well  as  all  versions  of 
QuickTime  3)  return  noErr  even  if  the  file  does  not  currently  exist. 

Programming  Info 

C  interface  file:  QTML .  h 


NAUnregisterMusicDevice 


Removes  a  previously  registered  music  component  from  the  note  allocator. 

ComponentResul t  NAUnregisterMusicDevice  ( 

NoteAl 1 ocator  na, 

long  index  ); 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 
i  ndex 

Synthesizer  to  unregister.  The  value  is  1  through  the  registered  music 
component  count  returned  by  NAGetRegi  steredMusi  cDevi  ce  (11-1028). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Note  Allocator  Configuration  and  Utilities"  (V-2919) 

Related  Java  Methods 

qui cktime . std .musi c . NoteAl locator. unregi s terMu si cDevi ce( ) 


NAUnrollNoteChannel 


Marks  a  note  channel  as  available  to  be  stolen. 


Inside  QuickTime:  Function  l-Q 
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NAUseDefaultMIDIInput 


ComponentResul t  NAUnrol 1 NoteChannel  ( 
NoteAl 1 ocator  na, 

NoteChannel  noteChannel  ) ; 


na 

You  obtain  the  note  allocator  identifier  by  calling  OpenComponent  (11-1130). 
noteChannel 

Note  channel  to  be  unrolled.  You  obtain  the  note  channel  identifier  from 
NANewNoteChannel  (11-1030)  or  NANewNoteChannel  FromAtomi  clnstrument  (11-1031). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 

Related  Java  Methods 

quickti me. std. music. NoteChannel. unroll!) 


NAUseDefaultMIDIInput 


Defines  an  entry  point  to  service  external  MIDI  device  events. 


ComponentResul t  NAUseDefaul tMIDI Input 
NoteAl 1 ocator  na, 

Musi cMIDI ReadHookUPP  readHook, 
long  refCon, 

unsi gned  1 ong  f 1 ags  ) ; 


( 


na 

You  obtain  the  note  allocator  identifier  from  OpenComponent  (11-1130). 
readHook 

A  pointer  toaMusicMIDIReadHookProc  (III— 2109)  callback. 
refCon 

A  reference  constant  value.  The  Movie  Toolbox  passes  this  reference  constant 
to  your  MusicMIDIReadHookProc  callback  each  time  it  calls  it.  Use  this  parameter 
to  point  to  a  data  structure  containing  any  information  your  callback  needs, 
fl  ags 

Must  contain  0. 
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N  e  wActionsUPP 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

NAUseDefaultMIDI  Input  specifies  an  application's  procedure  to  service  external 
MIDI  events.  The  specified  application's  procedure  call,  defined  by  readHook,  is 
called  when  the  external  default  MIDI  device  has  incoming  MIDI  data  for  the 
application. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Allocating  and  Using  Note  Channels"  (V-2916) 


NewActionsUPP 


Allocates  a  Universal  Procedure  Pointer  for  Acti  onsProc  (III— 2075). 

ActionsUPP  NewActionsUPP  ( 

Acti onsProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PoiverPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewActi  onsProc. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


NewCallBack 


Creates  a  new  callback  event. 

QTCallBack  NewCallBack  ( 
TimeBase  tb, 
short  cbType  ); 


Inside  QuickTime:  Function  l-Q 


11-1053 


NewCallBack 


tb 

The  callback  event's  time  base.  You  obtain  this  identifier  from  NewTimeBase 
(11-1119). 

cbType 

Constants  (see  below)  that  specify  when  the  callback  event  is  to  be  invoked. 
The  value  of  this  field  governs  how  the  Movie  Toolbox  interprets  the  data 
supplied  in  the  paraml,  param2,  and  param3  parameters  to  the  Cal  1  MeWhen  (1-67) 
function.  In  addition,  if  the  high-order  bit  of  the  cbType  parameter  is  set  to  1 
(this  bit  is  defined  by  the  call  BackAt  I  interrupt  flag),  the  event  can  be  invoked 
at  interrupt  time. 

function  result 

cbType  Constants 

cal  1 BackAtT ime 

Indicates  that  the  event  is  to  be  invoked  at  a  specified  time, 
cal  1 BackAtRate 

Indicates  that  the  event  is  to  be  invoked  when  the  rate  for  the  time  base  reaches 
a  specified  value, 
cal  1  BackAtTimeJump 

Indicates  that  the  event  is  to  be  invoked  when  the  time  base's  time  value 
changes  by  an  amount  that  differs  from  its  rate. 

call BackAt Extremes 

Indicates  that  the  event  is  to  be  invoked  when  the  time  base  reaches  its  start 
time  or  its  stop  time.  If  the  start  or  stop  time  of  the  time  base  changes,  the  call 
back  is  automatically  rescheduled.  This  is  very  useful  for  looping  or 
determining  when  a  movie  is  complete.  You  determine  when  the  callback  is  to 
be  fired  with  the  tri  ggerAtStart  and  tri  ggerAtStop  constants  (see  below).  Both 
flags  may  be  set. 
call  BackAt  I  interrupt 

Indicates  that  the  event  can  be  invoked  at  interrupt  time. 

callBackAtExtremes  Constants 

tri ggerAtStart 

Call  callback  at  time  base  start  time, 
tri ggerAtStop 

Call  callback  at  time  base  stop  time. 

Special  Considerations 

The  callback  event  created  is  not  active  until  you  schedule  it  by  calling  the 
Cal  1  MeWhen  (1-67)  function.  You  must  not  call  this  function  at  interrupt  time. 
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N  e  wCharDataHandlerUPP 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Time  Base  Callback  Functions"  (V-2763) 

Related  Java  Methods 

qui  cktime .  std  .  cl  ocks  .  RateCal  IBack.RateCallBackO, 
qui cktime . std . cl ocks .Ti meCal 1 Back.Ti meCal 1 Back( ) , 
qui cktime . std . cl ocks .Ti meJumpCal 1 Back.Ti meJumpCal 1 Back( ) , 
qui cktime . std . cl ocks . Ext remesCal 1  Back. Ext remesCal  1  Back( ) 

NewCharDataHandlerUPP 

Undocumented 

CharDataHandl  erLIPP  NewCharDataHandlerUPP  ( 

CharDataHandl er  userRoutine  ); 

userRouti ne 

Undocumented 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


NewCommentHandlerUPP 

Undocumented 

CommentHandl erUPP  NewCommentHandlerUPP  ( 

CommentHandl er  userRoutine  ); 

userRouti ne 

Undocumented 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 


Inside  QuickTime:  Function  l-Q 
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N  e  wComponentFunctionUPP 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


NewComponentFunctionUPP 

Helps  native  component  writers  easily  write  Carbon-compliant  components. 

ComponentFuncti on U P P  NewComponentFunctionUPP  ( 

ProcPtr  userRoutine, 

ProcInfoType  proclnfo  ); 

userRouti ne 

A  pointer  to  generic  callback  function;  see  Proc  (III— 2112). 
proclnfo 

The  routine's  procedure  information. 
function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Components .  h 


NewComponentMPWorkFunctionUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  ComponentMPWorkFuncti  onProc 
(III— 2077)  callback. 

ComponentMPWorkFuncti onUPP  NewComponentMPWorkFunctionUPP  ( 
ComponentMPWorkFuncti onProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 


11-1056 
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N  e  wComponentRoutineUPP 


Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewComponentMPWorkFuncti  onProc. 

Programming  Info 

C  interface  file:  Components .  h 


NewComponentRoutineUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  ComponentRouti  neProc  (III— 2077) 
callback. 

ComponentRouti neUPP  NewComponentRoutineUPP  ( 

ComponentRouti neProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewComponentRouti  neProc. 

Programming  Info 

C  interface  file:  Components .  h 


NewDataHCompletionUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  DataHCompl  eti  onProc  (III— 2078) 
callback. 

DataHCompl eti onUPP  NewDataHCompletionUPP  ( 

DataHCompl eti onProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 


Inside  QuickTime:  Function  l-Q 
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NewDoMCActionUPP 


function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PozverPC  System  Softivare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewDataHCompl  eti  onProc. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


NewDoMCActionUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  DoMCActi  onProc  (III— 2082)  callback. 

DoMCActi  onllPP  NewDoMCActionUPP  ( 

DoMCActi onProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PozverPC  System  Softzvare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewDoMCActi  onProc. 

Programming  Info 

C  interface  file:  Movi  es .  h 


NewEndDocumentHandlerUPP 

Undocumented 

EndDocumentHandl erUPP  NewEndDocumentHandlerUPP  ( 

EndDocumentHandl er  userRoutine  ); 

userRouti ne 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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N  e  wEndElementHandlerUPP 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


NewEndElementHandlerUPP 


Undocumented 

EndEl ementHandl erUPP  NewEndElementHandlerUPP  ( 

EndEl ementHandl er  userRoutine  ); 

userRouti ne 

Undocumented 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 


NewFilePlayCompletionUPP 

Obsolete. 

Fi  1  ePl  ayCompl  eti  onUPP  NewFilePlayCompletionUPP  ( 
Fi 1 ePl ayCompl eti onProcPtr  userRoutine  ); 


Version  Notes 

Introduced  in  QuickTime  4.1  to  replace  NewFi  1  ePl  ayCompl  eti  onProc.  Macintosh 
Note:  Not  supported  by  CarbonLib. 

Programming  Info 

C  interface  file:  Sound .  h 


NewGetMissingComponentResourceUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  GetMi  ssi  ngComponentResourceProc 
(III— 2084)  callback. 


Inside  QuickTime:  Function  l-Q 
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NewGetMovieUPP 


GetMi ssi ngComponentResourceUPP  NewGetMi ssi ngComponentResourceUPP  ( 

GetMi ssi ngComponentResourceProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewGetMi  ssi  ngComponentResourceProc. 

Programming  Info 

C  interface  file:  Components .  h 


NewGetMovieUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  GetMovi  eProc  (III— 2085)  callback. 

GetMovieUPP  NewGetMovieUPP  ( 

GetMovi eProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewGetMovi  eProc. 

Programming  Info 

C  interface  file:  Movi  es .  h 


NewICMAlignmentUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  ICMA1  i  gnmentProc  (III— 2086) 
callback. 
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NewICMCompletionUPP 


ICMAl i gnmentUPP  NewICMAl i gnmentUPP  ( 

ICMA1 i gnmentProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewICMAl  i  gnmentProc. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


NewICMCompletionUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  ICMCompl  eti  onProc  (III— 2087) 
callback. 

ICMCompl eti onUPP  NewICMCompletionUPP  ( 

ICMCompl eti onProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewICMCompl  eti  onProc. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


NewICMConvertDataFormatUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  ICMConvertDataFormatProc 
(III— 2088)  callback. 


Inside  QuickTime:  Function  l-Q 
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NewICMCursorShieldedUPP 


ICMConvertDataFormatUPP  NewICMConvertDataFormatUPP  ( 
ICMConvertDataFormatProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewICMConvertDataFormatProc. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


NewICMCursorShieldedUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  ICMCursorShi  el  dedProc  (III— 2089) 
callback. 

ICMCursorShi el dedUPP  NewICMCursorShieldedUPP  ( 

ICMCursorShi el dedProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewICMCursorShi  el  dedProc. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


NewICMDataUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  ICMDataProc  (III— 2090)  callback. 
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NewICMFlushUPP 


ICMDataUPP  NewICMDataUPP  ( 

ICMDataProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewICMDataProc. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


NewICMFlushUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  I  CM  FI  ushProc  (III— 2091)  callback. 

ICMF1 ushUPP  NewICMFlushUPP  ( 

ICMF1 ushProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewICMFlushProc. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


NewICMMemoryDisposedUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  ICMMemoryDi  sposedProc  (III— 2092) 
callback. 
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NewICMProgressUPP 


ICMMemoryDi sposedUPP  NewICMMemoryDi sposedUPP  ( 

ICMMemoryDi sposedProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewICMMemoryDi  sposedProc. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


NewICMProgressUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  ICMProgressProc  (III— 2093) 
callback. 

ICMProgressUPP  NewICMProgressUPP  ( 

ICMProgressProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewICMProgressProc. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


NewImageCodecDrawBandCompleteUPP 


Allocates  a  Universal  Procedure  Pointer  for  an  ImageCodecDrawBandCompl  eteProc 
(III— 2094)  callback. 
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NewImageCodecMPDrawBandUPP 


ImageCodecDrawBandCompl  eteUPP  New ImageCodecDrawBandCompl  etellPP  ( 
ImageCodecDrawBandCompl  eteProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  ImageCodec.h 


NewImageCodecMPDrawBandUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  ImageCodecMPDrawBandProc 
(III— 2095)  callback. 

ImageCodecMPDrawBandUPP  NewImageCodecMPDrawBandUPP  ( 
ImageCodecMPDrawBandProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewImageCodecMPDrawBandProc. 

Programming  Info 

C  interface  file:  ImageCodec.h 


Ne  wlmageCodecT  imeT  riggerUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  ImageCodecTimeTriggerProc 
(III— 2096)  callback. 

ImageCodecTimeTri ggerUPP  NewImageCodecTimeTriggerUPP  ( 
ImageCodecTimeTriggerProcPtr  userRoutine  ); 
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N  ewImageG  World 


userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewImageCodecTi  meT ri  ggerProc. 

Programming  Info 

C  interface  file:  ImageCodec.  h 


NewImageGWorld 

Creates  an  offscreen  graphics  world. 

OSErr  NewImageGWorld  ( 

GWorl dPtr 

ImageDescri pti onHandl e 
GWorl  d FI  ags 

gworl d 

A  pointer  to  a  graphic  world  created  using  the  width,  height,  depth,  and  color 
table  specified  in  the  ImageDescri  pti  on  (IV-2285)  structure  pointed  to  in  the  i  dh 
parameter. 

i  dh 

A  handle  to  an  ImageDescri  pti  on  (IV-2285)  structure  that  contains  information 
for  the  graphics  world  pointed  to  by  the  gworl  d  parameter, 
fl  ags 

Graphics  world  creation  flags  (see  below).  The  pixPurge,  noNewDevice, 
useTempMem,  keep  Local,  pixel  sPurgeabl  e,  and  pixel  s  Locked  flags  are  commands 
to  this  function;  the  others  are  returned  by  this  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

pi xPurge 

Make  the  base  address  for  the  offscreen  pixel  image  purgeable. 


*gworl d , 
i  dh , 

f 1 ags  ) ; 
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noNewDevi ce 

Do  not  create  a  new  offscreen  GDevi  ce  (IV-2264)  structure;  instead,  use  either 
the  GDevi  ce  record  you  specify  or  the  GDevi  ce  record  for  a  video  card  on  the 
user's  system. 
useTempMem 

Create  the  base  address  for  an  offscreen  pixel  image  in  temporary  memory.  You 
generally  should  not  use  this  flag.  You  should  use  temporary  memory  only  for 
fleeting  purposes. 

keepLocai 

Create  a  pixel  image  in  main  memory  where  it  cannot  be  cached  to  a  graphics 
accelerator  card, 
pixel sPurgeabl e 

Make  the  base  address  for  an  offscreen  pixel  map  purgeable.  If  you  use  this 
function  without  passing  it  this  flag,  it  makes  the  base  address  for  an  offscreen 
pixel  map  unpurgeable. 
pixel  sLocked 

Lock  the  base  address  for  an  offscreen  pixel  image.  If  you  use  this  function 
without  passing  it  this  flag,  it  unlocks  the  offscreen  pixel  image. 

mapPix 

Returned  if  this  function  remapped  the  colors  in  the  offscreen  pixel  map  to  a 
new  color  table. 
newDepth 

Returned  if  this  function  translated  the  offscreen  pixel  map  to  a  different  pixel 
depth, 
al  i  gnPi x 

Returned  if  this  function  realigned  the  offscreen  pixel  image  to  an  onscreen 
window. 

newRowBytes 

Returned  if  this  function  changed  the  rowBytes  field  of  the  Pi  xMap  record  for  the 
offscreen  graphics  world 
real  1 ocPi x 

Returned  if  this  function  reallocated  the  base  address  for  the  offscreen  pixel 
image.  Your  application  should  then  reconstruct  the  pixel  image  or  draw 
directly  in  a  window  instead  of  preparing  the  image  in  an  offscreen  graphics 
world, 
cl i pPi x 

Returned  if  this  function  clipped  the  pixel  image. 
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stretchPi x 

Returned  if  this  function  stretched  or  shrank  the  offscreen  image, 
d  i  t  h  e  r  P  i  x 

Returned  if  this  function  dithered  the  offscreen  image. 
gwFl  agErr 

Returned  if  this  function  was  unsuccessful  and  the  offscreen  graphics  world 
was  left  unchanged. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Graphics  Devices  and  Graphics  Worlds" 
(V-2798) 

Related  Java  Methods 

qui cktime.qd .QDGraphi cs .QDGraphi cs ( ) , 

qui ckti me . std . i mage . ImageDescri pti on . newGWorl d( ) 


NewMCActionFilterUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  MCActi  onFi  1  terProc  (III— 2096) 
callback. 

MCActi  onFi  1  terLIPP  NewMCActionFilterUPP  ( 

MCActionFi 1 terProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PozverPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewMCActionFi  1  terProc. 

Programming  Info 

C  interface  file:  Movi  es .  h 
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NewMCActionFilterWithRefConUPP 


NewMCActionFilterWithRefConUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  MCActi  onFi  1  terWi  thRefConProc 
(III— 2097)  callback. 

MCActi  onFi  1  terWi  thRefConUPP  NewMCActi  onFi  1  terWi  thRefConllPP  ( 

MCActi onFi 1 terWi thRefConProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Softzvare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewMCActi  onFi  1  terWi  thRefConProc. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


NewMovie 


Creates  a  new  movie  in  memory. 

Movie  NewMovie  ( 

long  flags  ); 

fl  ags 

Flags  (see  below)  that  specify  control  information  for  the  new  movie.  Be  sure  to 
set  unused  flags  to  0. 

function  result  The  identifier  for  the  new  movie.  If  NewMovi  e  fails,  the  returned 

identifier  is  set  to  NIL.  You  can  use  GetMoviesError  (1-492)  to  obtain 
the  error  result,  or  noErr  if  there  was  no  error.  See  "Error  Codes" 
(IV-2663). 

Flags  Constants 

newMovi eActi ve 

Controls  whether  the  new  movie  is  active.  Set  this  flag  to  1  to  make  the  new 
movie  active.  A  movie  that  does  not  have  any  tracks  can  still  be  active.  When 
the  Movie  Toolbox  tries  to  play  the  movie,  no  images  are  displayed,  because 
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there  is  no  movie  data.  You  can  make  a  movie  active  or  inactive  by  calling 
SetMovI  eActi  ve  (III — 1609). 

newMovi eDontAutoAlternate 

Controls  whether  the  Movie  Toolbox  automatically  selects  enabled  tracks  from 
alternate  track  groups.  If  you  set  this  flag  to  1,  the  Movie  Toolbox  does  not 
automatically  select  tracks  for  the  movie;  you  must  enable  tracks  yourself. 

Discussion 

You  can  use  NewMovi  e  to  create  a  new  empty  movie,  which  contains  no  tracks.  The 
Movie  Toolbox  initializes  the  data  structures  for  the  new  movie.  Your  application 
assigns  the  data  to  the  movie  by  calling  the  functions  that  are  described  in 
NewMovi  eT rack  (11-1092). 

The  Movie  Toolbox  sets  many  movie  characteristics  to  default  values.  If  you  want 
to  change  these  defaults,  your  application  must  call  other  Movie  Toolbox  functions. 
For  example,  the  Movie  Toolbox  sets  the  movie's  graphics  world  to  the  one  that  is 
active  when  you  call  NewMovi  e.  To  change  the  graphics  world  for  the  new  movie, 
your  application  should  use  SetMovi  eGWorl  d  (III— 1619).  The  default  QuickTime 
movie  time  scale  is  600  units  per  second;  however,  this  number  may  change  in  the 
future.  The  default  time  scale  was  chosen  because  it  is  convenient  for  working  with 
common  video  frame  rates  of  30,  25, 24, 15, 12, 10,  and  8. 

Special  Considerations 

The  Movie  Toolbox  automatically  sets  the  movie's  graphics  world  based  upon  the 
current  graphics  port.  Be  sure  that  your  application's  graphics  port  is  valid  before 
you  call  this  function.  Use  this  function  only  if  you  have  not  created  a  new  movie 
and  movie  file  by  calling  CreateMovi  eFi  1  e  (1-145). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Movie  Functions"  (V-2713) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . Movi e( ) 


See  Also 

If  your  application  is  loading  a  movie  from  an  existing  file,  use  either 
NewMovi  eFromFi  1  e  (11-1080)  or  NewMovi  eFromDataFork  (11-1075).  NewMovi  eFromFi  1  e 
works  with  the  file  reference  number  you  obtain  from  OpenMovi  eFi  1  e  (11-1133); 
NewMovi  eFromDataFork  works  with  movies  stored  in  a  Macintosh  document  file's 
data  fork. 
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NewMovieController 


Locates  a  movie  controller  component  and  assigns  a  movie  to  that  controller. 

Componentlnstance  NewMovieController  ( 

Movie  theMovie, 

const  Rect  *movieRect, 

long  someFlags  ); 

theMovi e 

The  movie  to  be  associated  with  the  movie  controller, 
movi eRect 

A  pointer  to  the  Rect  (IV-2399)  structure  that  is  to  define  the  display  boundaries 
of  the  movie  and  its  controller. 
someFl  ags 

Contains  flags  (see  below)  that  control  the  operation.  If  you  set  these  flags  to  0, 
the  movie  controller  component  centers  the  movie  in  the  rectangle  specified  by 
the  movi  eRect  parameter  and  scales  the  movie  to  fit  in  that  rectangle.  The 
control  portion  of  the  controller  is  also  placed  within  that  rectangle.  You  may 
control  how  the  movie  and  the  control  are  drawn  by  setting  one  or  more  flags 
to  1. 

function  result  The  ID  of  the  new  controller. 

someFlags  Constants 

mcTopLeftMovi e 

If  this  flag  is  set  to  1,  the  movie  controller  component  places  the  movie  into  the 
upper-left  comer  of  the  display  rectangle  specified  by  the  mov  i  eRect  parameter. 
The  component  scales  the  movie  to  fit  into  the  rectangle.  Note  that  the  control 
portion  of  the  controller  may  fall  outside  of  the  rectangle,  depending  upon  the 
results  of  the  scaling  operation. 
mcScal eMovi eToFi t 

If  this  flag  is  set  to  1,  the  movie  controller  component  resizes  the  movie  to  fit 
into  the  display  rectangle  specified  by  the  movi  eRect  parameter  after  it  places 
the  control  portion  of  the  controller  into  the  rectangle.  If  you  set  this  flag  and 
the  mcScal  eMovi  eToFi  t  flag  to  1,  the  movie  controller  component  resizes  the 
movie  to  fit  into  the  specified  rectangle  and  places  the  control  portion  of  the 
controller  outside  of  the  rectangle. 
mcWi thBadge 

Controls  whether  the  movie  controller  uses  a  badge.  If  you  set  this  flag  to  1,  the 
movie  controller  component  displays  the  movie  with  a  badge  whenever  the 
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controller  portion  is  not  displayed.  If  you  set  this  flag  to  0,  the  movie  controller 
component  does  not  use  a  badge. 

mcNotVi si bl e 

Controls  whether  the  controller  portion  is  visible.  If  you  set  this  flag  to  0,  the 
movie  controller  component  displays  the  controller  along  with  the  movie.  If 
you  set  this  flag  to  1,  the  component  does  not  display  the  controller.  If  you  have 
set  the  mcWithBadge  flag  to  1,  specifying  that  the  component  uses  a  badge,  the 
component  displays  a  badge  whenever  the  controller  is  not  visible. 

mcWi thFrame 

Specifies  whether  the  component  displays  a  frame  around  the  movie  as  part  of 
the  controller.  If  you  set  this  flag  to  1,  the  component  displays  a  frame  around 
the  movie,  including  the  movie's  name.  If  you  set  this  flag  to  0,  the  component 
does  not  display  a  frame  as  part  of  the  controller. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Associating  Movies  With  Controllers"  (V-2774) 

Related  Java  Methods 

quicktime.std.movies.MovieController.MovieControllerO, 
quickti  me.  std.  mo  vies.  Multi  Mo  vieController.  Multi  Mo  vieControllerO 


NewMovieDrawingCompleteUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  Movi  eDrawi  ngCompl  eteProc 
(III— 2100)  callback. 

Movi eDrawi ngCompl eteUPP  NewMovieDrawingCompleteUPP  ( 

Movi eDrawi ngCompl eteProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewMovi  eDrawi  ngCompl  eteProc. 
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Programming  Info 

C  interface  file:  Movi  es  .  h 


NewMovieEditState 


Creates  an  edit  state. 

Movi eEdi tState  NewMovieEditState  ( 

Movie  theMovie  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  A  pointer  to  a  Movi  eEdi  tStateRecord  (IV-2313)  structure.  The  edit 
state  contains  all  the  information  describing  a  movie's  content, 
including  the  current  selection,  the  movie's  tracks,  and  the  media 
data  associated  with  those  tracks. 


Special  Considerations 

You  must  dispose  of  a  movie's  Movi  eEdi  tStateRecord  structures,  using 
Di  sposeMovi  eEdi  tState  (1-273),  before  you  dispose  of  the  movie  itself. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Undo  for  Movies"  (V-2748) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . newEdi tState ( ) 


NewMovieExecuteWiredActionsUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  Movi  eExecuteWi  redActi  onsProc 
(III— 2101)  callback. 

Movi  eExecuteWi  redActi  onsLIPP  NewMovi  eExecuteWi  redActi  onsUPP  ( 

Movi eExecuteWi redActi onsProcPtr  userRoutine  ); 
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userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewMovi  eExecuteWi  redActi  onsProc. 

Programming  Info 

C  interface  file:  Movi  es .  h 


NewMovieExportGetDataUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  Movi  eExportGetDataProc  (III— 2101) 
callback. 

Movi eExportGetDataUPP  NewMovieExportGetDataUPP  ( 

Movi eExportGetDataProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Softzvare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewMovi  eExportGetDataProc. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


NewMovieExportGetPropertyUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  Movi  eExportGetPropertyProc 
(III— 2102)  callback. 

Movi eExportGetPropertyUPP  NewMovieExportGetPropertyUPP  ( 

Movi eExportGetPropertyProcPtr  userRoutine  ); 
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userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewMovi  eExportGetPropertyProc. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


NewMovieFromDataFork 


Retrieves  a  movie  that  is  stored  anywhere  in  the  data  fork  of  a  specified  Macintosh 
file. 

OSErr  NewMovieFromDataFork  ( 

Movie  *theMovie, 

short  fRefNum, 

long  fileOffset, 

short  newMovi eFl ags  , 

Boolean  *dataRefWasChanged  ); 

theMovi e 

A  pointer  to  a  field  that  is  to  receive  the  new  movie's  identifier.  If  the  function 
cannot  load  the  movie,  the  returned  identifier  is  set  to  NIL. 

fRefNum 

A  file  reference  number  to  a  file  that  is  already  open, 
f i 1 eOf f set 

The  starting  file  offset  of  the  atom  in  the  data  fork  of  the  file  specified  by  the 
fRefNum  parameter. 
newMovi eFl ags 

Flags  (see  below)  that  control  characteristics  of  the  new  movie. 
dataRefWasChanged 

A  pointer  to  a  Bool  ean  value.  The  Movie  Toolbox  sets  the  value  to  TRUE  if  any  of 
the  movie's  data  references  were  changed.  Use  UpdateMovi  eResource  (III— 1983) 
to  preserve  these  changes.  If  you  do  not  want  to  receive  this  information,  set  the 
dataRefWasChanged  parameter  to  NIL. 
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function  result  If  the  Movie  Toolbox  cannot  completely  resolve  all  data  references,  it 
sets  the  current  error  value  to  coul  dNotResol  veDataRef.  You  can 
access  error  returns  such  as  this  through  GetMovi  esError  (1-492)  and 
GetMovi  esSti  cky  Error  (1-494),  as  well  as  in  the  function  result.  See 
"Error  Codes"  (IV-2663). 

newMovieFlags  Constants 

newMovi eActi ve 

Controls  whether  the  new  movie  is  active.  Set  this  flag  to  1  to  make  the  new 
movie  active.  A  movie  that  does  not  have  any  tracks  can  still  be  active.  When 
the  Movie  Toolbox  tries  to  play  the  movie,  no  images  are  displayed,  because 
there  is  no  movie  data.  You  can  make  a  movie  active  or  inactive  by  calling  the 
SetMovi  eActi  ve  (III— 1609)  function. 
newMovi eDontAutoAlternate 

Controls  whether  the  Movie  Toolbox  automatically  selects  enabled  tracks  from 
alternate  track  groups.  If  you  set  this  flag  to  1,  the  Movie  Toolbox  does  not 
automatically  select  tracks  for  the  movie;  you  must  enable  tracks  yourself. 
newMovi e Don t Res o 1 ve Data  Refs 

Controls  how  completely  the  Movie  Toolbox  resolves  data  references  in  the 
movie  resource.  If  you  set  this  flag  to  0,  the  Movie  Toolbox  tries  to  completely 
resolve  all  data  references  in  the  resource.  This  may  involve  searching  for  files 
on  remote  volumes.  If  you  set  this  flag  to  1,  the  Movie  Toolbox  only  looks  in  the 
specified  file.  If  the  Movie  Toolbox  cannot  completely  resolve  all  the  data 
references,  it  still  returns  a  valid  movie  identifier.  In  this  case,  the  Movie 
Toolbox  also  sets  the  current  error  value  to  coul  dNotResol  veDataRef. 

newMovi  e  Don  t  As  kiln  resol  ved  Data  Refs 

Controls  whether  the  Movie  Toolbox  asks  the  user  to  locate  files.  If  you  set  this 
flag  to  0,  the  Movie  Toolbox  asks  the  user  to  locate  files  that  it  cannot  find  on 
available  volumes.  If  the  Movie  Toolbox  cannot  locate  a  file  even  with  the  user's 
help,  the  function  returns  a  valid  movie  identifier  and  sets  the  current  error 
value  to  coul  dNotResol  veDataRef. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Saving  Movies"  (V-2715) 

Related  Java  Methods 

quicktime.std.movies.Movie.fromDataForkO 


11-1076 


Inside  QuickTime:  Function  l-Q 


NewMovieFromDataFork64 


NewMovieFromDataFork64 


Provides  a  64-bit  version  of  NewMovi  eFromDataFork  (11-1075). 


OSErr  NewMovieFromDataFork64  ( 


Movi  e 
1  ong 

const  wide 
short 
Bool ean 


*theMovi e , 
f RefNum, 

*fi 1 eOf f set , 
newMovi eFl ags , 
*dataRefWasChanged  ); 


theMovi e 

A  pointer  to  a  field  that  is  to  receive  the  new  movie's  identifier.  If  the  function 
cannot  load  the  movie,  the  returned  identifier  is  set  to  NIL. 

f Ref Num 

A  file  reference  number  to  a  file  that  is  already  open, 
f i 1 eOf f set 

A  pointer  to  the  starting  file  offset  of  the  atom  in  the  data  fork  of  the  file 
specified  by  the  f  Ref  Num  parameter. 
newMovi eFl ags 

Flags  (see  below)  that  control  characteristics  of  the  new  movie. 
dataRefWasChanged 

A  pointer  to  a  Bool  ean  value.  The  Movie  Toolbox  sets  the  value  to  TRUE  if  any  of 
the  movie's  data  references  were  changed.  Use  UpdateMovi  eResource  (III— 1983) 
to  preserve  these  changes.  If  you  do  not  want  to  receive  this  information,  set  the 
dataRefWasChanged  parameter  to  NIL. 

function  result  If  the  Movie  Toolbox  cannot  completely  resolve  all  data  references,  it 
sets  the  current  error  value  to  coul  dNotResol  veDataRef.  You  can 
access  error  returns  such  as  this  through  GetMoviesError  (1-492)  and 
GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function  result.  See 
"Error  Codes"  (IV-2663). 

newMovieFlags  Constants 

newMovi eActi ve 

Controls  whether  the  new  movie  is  active.  Set  this  flag  to  1  to  make  the  new 
movie  active.  A  movie  that  does  not  have  any  tracks  can  still  be  active.  When 
the  Movie  Toolbox  tries  to  play  the  movie,  no  images  are  displayed,  because 
there  is  no  movie  data.  You  can  make  a  movie  active  or  inactive  by  calling  the 
SetMovi  eActi  ve  (III— 1609)  function. 
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newMovi eDontAutoAlternate 

Controls  whether  the  Movie  Toolbox  automatically  selects  enabled  tracks  from 
alternate  track  groups.  If  you  set  this  flag  to  1,  the  Movie  Toolbox  does  not 
automatically  select  tracks  for  the  movie;  you  must  enable  tracks  yourself. 
newMovi e Don t Res o 1 ve Data  Refs 

Controls  how  completely  the  Movie  Toolbox  resolves  data  references  in  the 
movie  resource.  If  you  set  this  flag  to  0,  the  Movie  Toolbox  tries  to  completely 
resolve  all  data  references  in  the  resource.  This  may  involve  searching  for  files 
on  remote  volumes.  If  you  set  this  flag  to  1,  the  Movie  Toolbox  only  looks  in  the 
specified  file.  If  the  Movie  Toolbox  cannot  completely  resolve  all  the  data 
references,  it  still  returns  a  valid  movie  identifier.  In  this  case,  the  Movie 
Toolbox  also  sets  the  current  error  value  to  coul  dNotResol  veDataRef. 

newMovi  e  Don  t  As  kiln  resol  ved  Data  Refs 

Controls  whether  the  Movie  Toolbox  asks  the  user  to  locate  files.  If  you  set  this 
flag  to  0,  the  Movie  Toolbox  asks  the  user  to  locate  files  that  it  cannot  find  on 
available  volumes.  If  the  Movie  Toolbox  cannot  locate  a  file  even  with  the  user's 
help,  the  function  returns  a  valid  movie  identifier  and  sets  the  current  error 
value  to  coul  dNotResol  veDataRef. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es .  h 


NewMovieFromDataRef 


Creates  a  movie  from  any  device  with  a  corresponding  data  handler. 


■r  NewMov 

i eFromDataRef  ( 

Movi  e 

*m , 

short 

fl ags , 

short 

*i  d , 

Handl e 

dataRef , 

OSType 

dataRefType  ) 

A  pointer  to  a  field  that  is  to  receive  the  new  movie's  identifier.  If  the  function 
cannot  load  the  movie,  the  returned  identifier  is  set  to  NIL. 
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fl  ags 

Flags  (see  below)  that  control  the  operation  of  this  function.  Be  sure  to  set 
unused  flags  to  0. 
i  d 

A  pointer  to  the  field  that  specifies  the  resource  containing  the  movie  data  that 
is  to  be  loaded.  If  the  field  referred  to  by  the  i  d  parameter  is  set  to  0,  the  Movie 
Toolbox  loads  the  first  movie  resource  it  finds  in  the  specified  file.  The  toolbox 
then  returns  the  movie's  resource  ID  number  in  the  field  referred  to  by  the  i  d 
parameter.  An  enumerated  constant  (see  below)  is  available. 

dataRef 

The  default  data  reference.  This  parameter  contains  a  handle  to  the  information 
that  identifies  the  file  to  be  used  to  resolve  any  data  references  and  as  a  starting 
point  for  any  Alias  Manager  searches.  The  type  of  information  stored  in  the 
handle  depends  upon  the  value  of  the  dataRefType  parameter.  For  example,  if 
your  application  is  loading  the  movie  from  a  file,  you  would  refer  to  the  file's 
alias  in  this  parameter  and  set  the  dataRefType  parameter  to  rAl  i  asType.  If  you 
do  not  want  to  identify  a  default  data  reference,  set  the  parameter  to  NIL. 
dataRefType 

The  type  of  data  reference.  If  the  data  reference  is  an  alias,  you  must  set  the 
parameter  to  rAl  i  asType,  indicating  that  the  reference  is  an  alias. 

function  result  If  the  Movie  Toolbox  cannot  completely  resolve  all  data  references,  it 
sets  the  current  error  value  to  coul  dNotResol  veDataRef.  You  can 
access  error  returns  such  as  this  through  GetMovi  esError  (1-492)  and 
GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function  result.  See 
“Error  Codes"  (IV-2663). 

flags  Constants 

newMovi eActi ve 

Controls  whether  the  new  movie  is  active.  Set  this  flag  to  1  to  make  the  new 
movie  active.  You  can  make  a  movie  active  or  inactive  by  calling  the 
SetMovi  eActi  ve  (III— 1609)  function. 

newMovi eDontResolveDataRefs 

Controls  how  completely  the  Movie  Toolbox  resolves  data  references  in  the 
movie  resource.  If  you  set  this  flag  to  0,  the  toolbox  tries  to  completely  resolve 
all  data  references  in  the  resource.  This  may  involve  searching  for  files  on 
remote  volumes.  If  you  set  this  flag  to  1,  the  toolbox  only  looks  in  the  specified 
data  reference.  If  the  toolbox  cannot  completely  resolve  all  the  data  references, 
it  still  returns  a  valid  movie  identifier.  In  this  case,  the  toolbox  also  sets  the 
current  error  value  to  coul  dNotResol  veDataRef. 
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newMovi eDontAskUn resol ved Data  Refs 

Controls  whether  the  Movie  Toolbox  asks  the  user  to  locate  files.  If  you  set  this 
flag  to  0,  the  toolbox  asks  the  user  to  locate  files  that  it  cannot  find  on  available 
volumes.  If  the  toolbox  cannot  locate  a  file,  even  with  the  user's  help,  the 
function  returns  a  valid  movie  identifier  and  sets  the  current  error  value  to 
couldNotResol  ve  Data  Ref. 
newMovi eDontAutoAlternate 

Controls  whether  the  Movie  Toolbox  automatically  selects  enabled  tracks  from 
alternate  track  groups.  If  you  set  this  flag  to  1,  the  Movie  Toolbox  does  not 
automatically  select  tracks  for  the  movie;  you  must  enable  and  disable  tracks 
yourself. 

id  Constants 

movielnDataForkResID 

The  movie  was  loaded  from  the  data  fork.  If  the  resource  was  stored  in  the  file's 
data  fork,  the  Movie  Toolbox  sets  the  returned  value  to  this  constant.  In  this 
case,  you  cannot  add  a  movie  resource  to  the  file  unless  you  create  a  resource 
fork  in  the  movie  file. 

Discussion 

This  function  is  intended  for  use  by  specialized  applications  that  need  to  instantiate 
movies  from  devices  not  visible  to  the  file  system.  Most  applications  should 
continue  to  use  NewMovi  eFromFi  1  e  (11-1080).  You  are  not  restricted  to  instantiating  a 
movie  from  a  file  stored  on  a  Macintosh  HFS  volume.  With  this  function,  you  can 
instantiate  a  movie  from  any  device. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Movie  Functions"  (V-2713) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . from Data  Ref ( ) 


NewMovieFromFile 


Creates  a  new  movie  from  certain  file  types  that  do  not  contain  movie  resources 
(AIFF,  MPEG,  etc). 

OSErr  NewMovieFromFile  ( 

Movie  *theMovie, 

short  resRefNum, 
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short  *resld, 

StringPtr  resName, 

short  newMovi eFl ags  , 

Boolean  *dataRefWasChanged  ); 

theMovi e 

A  pointer  to  a  field  that  is  to  receive  the  new  movie's  identifier.  If  the  function 
cannot  load  the  movie,  the  returned  identifier  is  set  to  NIL. 

resRefNum 

The  movie  file  from  which  the  movie  is  to  be  loaded.  Your  application  obtains 
this  value  from  the  OpenMovieFile  (11-1133)  function, 
res  Id 

A  pointer  to  a  field  that  specifies  the  resource  containing  the  movie  data  that  is 
to  be  loaded.  If  the  field  referred  to  by  the  res  I  d  parameter  is  set  to  0,  the  Movie 
Toolbox  loads  the  first  movie  resource  it  finds  in  the  specified  file.  The  Movie 
Toolbox  then  returns  the  movie's  resource  ID  number  in  the  field  referred  to  by 
the  res  Id  parameter.  An  enumerated  constant  (see  below)  is  available. 
resName 

A  pointer  to  a  character  string  that  is  to  receive  the  name  of  the  movie  resource 
that  is  loaded.  If  you  set  the  resName  parameter  to  N I L,  the  Movie  Toolbox  does 
not  return  the  resource  name. 

newMovi eFl ags 

Flags  (see  below)  that  control  the  operation  of  NewMovi  eFromFi  1  e.  Be  sure  to  set 
unused  flags  to  0. 
dataRefWasChanged 

A  pointer  to  a  Bool  ean  value.  The  Movie  Toolbox  sets  the  value  to  TRUE  if  any 
references  were  changed.  Use  UpdateMovi eResource  (III— 1983)  to  preserve  these 
changes.  Set  this  parameter  to  N I L  if  you  don't  want  to  receive  this  information. 
See  NewMovi  eTrack  (11-1092)  for  more  information  about  data  references. 

function  result  If  the  Movie  Toolbox  cannot  completely  resolve  all  data  references,  it 
sets  the  current  error  value  to  coul  dNotResol  veDataRef.  You  can 
access  error  returns  such  as  this  through  GetMoviesError  (1-492)  and 
GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function  result.  See 
"Error  Codes"  (IV-2663). 

resld  Constant 

movielnDataForkResID 

Forces  the  movie  to  come  out  of  the  data  fork.  If  the  resource  was  stored  in  the 
file's  data  fork,  the  Movie  Toolbox  sets  the  returned  value  to  this  constant.  In 
this  case,  you  can  only  add  a  movie  to  the  data  fork  of  the  file  if  you  create  a 
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resource  fork  in  the  movie  file.  If  the  res  I  d  parameter  is  set  to  NIL,  the  Movie 
Toolbox  loads  the  first  movie  resource  it  finds  in  the  specified  file  and  does  not 
return  that  resource's  ID  number. 

newMovieFlags  Constants 

newMovi eActi ve 

Controls  whether  the  new  movie  is  active.  Set  this  flag  to  1  to  make  the  new 
movie  active.  You  can  make  a  movie  active  or  inactive  by  calling 
SetMovi  eActi  ve  (III — 1609). 

newMovi e Don t Res o 1 ve Data  Refs 

Controls  how  completely  the  Movie  Toolbox  resolves  data  references  in  the 
movie  resource.  If  you  set  this  flag  to  0,  the  Movie  Toolbox  tries  to  completely 
resolve  all  data  references  in  the  resource.  This  may  involve  searching  for  files 
on  multiple  volumes.  If  you  set  this  flag  to  1,  the  Movie  Toolbox  only  looks  in 
the  specified  file.  If  the  Movie  Toolbox  cannot  completely  resolve  all  the  data 
references,  it  still  returns  a  valid  movie  identifier.  In  this  case,  the  Movie 
Toolbox  also  sets  the  current  error  value  to  coul  dNotResol  veDataRef. 
newMovi  e  Don  t  As  kiln  resol  ved  Data  Refs 

Controls  whether  the  Movie  Toolbox  asks  the  user  to  locate  files.  If  you  set  this 
flag  to  0,  the  Movie  Toolbox  asks  the  user  to  locate  files  that  it  cannot  find.  If  the 
Movie  Toolbox  cannot  locate  a  file  even  with  the  user's  help,  the  function 
returns  a  valid  movie  identifier  and  sets  the  current  error  value  to 
coul  dNotResol  veDataRef. 
newMovi eDontAutoAlternate 

Controls  whether  the  Movie  Toolbox  automatically  selects  enabled  tracks  from 
alternate  track  groups.  If  you  set  this  flag  to  1,  the  Movie  Toolbox  does  not 
automatically  select  tracks  for  the  movie;  you  must  enable  tracks  yourself. 

Discussion 

The  Movie  Toolbox  sets  many  movie  characteristics  to  default  values.  If  you  want 
to  change  these  defaults,  your  application  must  call  other  Movie  Toolbox  functions. 
For  example,  the  Movie  Toolbox  sets  the  movie's  graphics  world  to  the  one  that  is 
active  when  you  call  NewMovi  eFromFi  1  e.  To  change  the  graphics  world  for  the  new 
movie,  your  application  should  use  SetMovi  eGWorl  d  (III— 1619). 

The  following  is  an  example  of  using  this  function: 

//  NewMovieFromFile  coding  example 
//  See  “Discovering  QuickTime,”  page  385 
Movie  MyGetMovie  (void) 

{ 

OSErr  nErr; 
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SFTypeLi st 
StandardFi 1 eReply 
Movi  e 
short 


types  =  (Movi eFi 1 eType ,  0,  0,  0}  ; 
sf  r ; 

movie  =  NIL; 
n  F i 1 eRefNum; 


StandardGetFi 1 ePrevi ew( NI L,  1,  types,  &sfr); 
if  (sfr.sfGood)  { 

nErr  =  OpenMovi eFi 1 e(&sf r . sf Fi 1 e ,  &n Fi 1 eRefNum,  fsRdPerm); 
if  (nErr  ==  noErr)  { 

short  nResID  =  0;  //We  want  the  first  movie. 

Str255  strName; 

Boolean  bWasChanged; 

nErr  =  NewMovi eFromFi 1 e(&movi e ,  nFileRefNum,  &nResID,  strName, 

newMovi eActi ve ,  &bWasChanged ) ; 

Cl  oseMovi eFi  1  e(nFi  1  eRefNum) ; 

} 

} 

return  movie; 

} 

Special  Considerations 

This  function  works  with  some  files  that  don't  contain  movie  resources.  When  it 
encounters  a  file  that  does  not  contain  a  movie  resource,  it  tries  to  find  a  movie 
import  component  that  can  understand  the  data  and  create  a  movie.  It  also  works 
for  MPEG,  uLaw  (.AU),  and  Wave  (.WAV)  file  types.  In  some  cases,  the  data  in  a  file 
is  already  sufficiently  well  formatted  for  QuickTime  or  its  components  to 
understand.  For  example,  the  AIFF  movie  data  import  component  can  understand 
AIFF  sound  files  and  import  the  sound  data  into  a  QuickTime  movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Movie  Functions"  (V-2713) 

Related  Java  Methods 

qui cktime . std .movi es . Movi e . f romFi 1 e( ) 


See  Also 

Your  application  can  use  NewMovi  eFromHandl  e  (11-1084)  to  load  a  movie  from  a 
handle. 
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NewMovieFromHandle 


Creates  a  movie  in  memory  from  a  movie  resource  or  a  handle  you  obtained  from 
PutMovi  elntoHandl  e  (11-1151). 

OSErr  NewMovieFromHandle  ( 

Movie  *theMovie, 

Handle  h, 

short  newMovi e  FI ags , 

Boolean  *dataRefWasChanged  ); 

theMovi e 

A  pointer  to  a  field  that  is  to  receive  the  new  movie's  identifier.  If  the  function 
cannot  load  the  movie,  the  returned  identifier  is  set  to  NIL. 
h 

A  handle  to  the  movie  resource  from  which  the  movie  is  to  be  loaded. 
newMovi eFl ags 

Flags  (see  below)  that  control  the  operation  of  NewMovi  eFromHandl  e.  Be  sure  to 
set  unused  flags  to  0. 
dataRefWasChanged 

A  pointer  toaBoolean  value.  The  toolbox  sets  the  value  to  T  RU  E  if  any  references 
were  changed.  Set  the  dataRefWasChanged  parameter  to  N I L  if  you  don't  want  to 
receive  this  information. 

function  result  If  the  Movie  Toolbox  cannot  completely  resolve  all  data  references,  it 
sets  the  current  error  value  to  coul  dNotResol  veDataRef.  You  can 
access  error  returns  such  as  this  through  GetMovi  esError  (1-492)  and 
GetMovi  esSti  cky  Error  (1-494),  as  well  as  in  the  function  result.  See 
"Error  Codes"  (IV-2663). 

newMovieFlags  Constants 

newMovi eActi ve 

Controls  whether  the  new  movie  is  active.  Set  this  flag  to  1  to  make  the  new 
movie  active.  You  can  make  a  movie  active  or  inactive  by  calling 
SetMovi  eActi  ve  (III — 1609). 

newMovi e Don t Res o 1 ve Data  Refs 

Controls  how  completely  the  Movie  Toolbox  resolves  data  references  in  the 
movie  resource.  If  you  set  this  flag  to  0,  the  toolbox  tries  to  completely  resolve 
all  data  references  in  the  resource.  This  may  involve  searching  for  files  on 
remote  volumes.  If  you  set  this  flag  to  1,  the  Movie  Toolbox  only  looks  in  the 
specified  file.  If  the  Movie  Toolbox  cannot  completely  resolve  all  the  data 
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references,  it  still  returns  a  valid  movie  identifier.  In  this  case,  the  Movie 
Toolbox  also  sets  the  current  error  value  to  coul  dNotResol  veDataRef. 

newMovi eDontAs kUn resol ved Data  Refs 

Controls  whether  the  Movie  Toolbox  asks  the  user  to  locate  files.  If  you  set  this 
flag  to  0,  the  Movie  Toolbox  asks  the  user  to  locate  files  that  it  cannot  find  on 
available  volumes.  If  the  Movie  Toolbox  cannot  locate  a  file  even  with  the  user's 
help,  the  function  returns  a  valid  movie  identifier  and  sets  the  current  error 
value  to  coul  dNotResol  veDataRef. 

newMovi eDontAutoAl  ternate 

Controls  whether  the  Movie  Toolbox  automatically  selects  enabled  tracks  from 
alternate  track  groups.  If  you  set  this  flag  to  1,  the  Movie  Toolbox  does  not 
automatically  select  tracks  for  the  movie;  you  must  enable  tracks  yourself. 

Discussion 

The  Movie  Toolbox  sets  many  movie  characteristics  to  default  values.  If  you  want 
to  change  these  defaults,  your  application  must  call  other  Movie  Toolbox  functions. 
For  example,  the  Movie  Toolbox  sets  the  movie's  graphics  world  to  the  one  that  is 
active  when  you  call  NewMovi  eFromHandle.  To  change  the  graphics  world  for  the  new 
movie,  your  application  should  use  SetMovi  eGWorl  d  (III— 1619). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Movie  Functions"  (V-2713) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . f romHandi e( ) 


See  Also 

Your  application  can  use  NewMovi  eFromFi  1  e  (11-1080)  to  load  a  movie  from  a  movie 
file  that  was  opened  with  OpenMovi  eFi  1  e  (11-1133). 


NewMovieFromScrap 


Creates  a  movie  from  the  contents  of  the  scrap. 

Movie  NewMovieFromScrap  ( 
long  newMovi eFi ags  ); 
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NewMovieFromScrap 


newMovi eFl ags 

Flags  (see  below)  that  control  the  operation  of  the  NewMovieFromScrap  function. 
Be  sure  to  set  unused  flags  to  0. 

function  result  The  identifier  for  the  new  movie.  If  NewMovi  eFromScrap  fails,  or  if 
there  is  no  movie  in  the  scrap,  the  returned  identifier  is  set  to  NIL. 
You  can  use  GetMoviesError  (1-492)  to  obtain  the  error  result,  or 
noErr  if  there  was  no  error.  See  "Error  Codes"  (IV-2663). 

newMovieFlags  Constants 

newMovi eActi ve 

Controls  whether  the  new  movie  is  active.  Set  this  flag  to  1  to  make  the  new 
movie  active.  A  movie  that  does  not  have  any  tracks  can  still  be  active.  When 
the  Movie  Toolbox  tries  to  play  the  movie,  no  images  are  displayed,  because 
there  is  no  movie  data.  Unless  you  set  this  flag,  you  should  call  the 
SetMovi  eActi  ve  (III— 1609)  function  to  play  a  movie. 

newMovi e Don t Res o 1 ve Data  Refs 

Controls  how  completely  the  Movie  Toolbox  resolves  data  references  in  the 
movie  resource.  If  you  set  this  flag  to  0,  the  toolbox  tries  to  completely  resolve 
all  data  references  in  the  resource.  This  may  involve  searching  for  files  on 
remote  volumes.  If  you  set  this  flag  to  1,  the  Movie  Toolbox  only  looks  in  the 
specified  file.  If  the  Movie  Toolbox  cannot  completely  resolve  all  the  data 
references,  it  still  returns  a  valid  movie  identifier.  In  this  case,  the  Movie 
Toolbox  also  sets  the  current  error  value  to  coul  dNotResol  veDataRef. 
newMovi  e  Don  t  As  kiln  resol  ved  Data  Refs 

Controls  whether  the  Movie  Toolbox  asks  the  user  to  locate  files.  If  you  set  this 
flag  to  0,  the  Movie  Toolbox  asks  the  user  to  locate  files  that  it  cannot  find  on 
available  volumes.  If  the  Movie  Toolbox  cannot  locate  a  file  even  with  the  user's 
help,  the  function  returns  a  valid  movie  identifier  and  sets  the  current  error 
value  to  coul  dNotResol  veDataRef. 
newMovi eDontAutoAlternate 

Controls  whether  the  Movie  Toolbox  automatically  selects  enabled  tracks  from 
alternate  track  groups.  If  you  set  this  flag  to  1,  the  Movie  Toolbox  does  not 
automatically  select  tracks  for  the  movie;  you  must  enable  tracks  yourself. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "High-Level  Movie  Editing  Functions"  (V-2746) 
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NewMovieFromUserProc 


Related  Java  Methods 

qui cktime . std .movi es . Movi e . f romScrapI ) 


NewMovieFromUserProc 


Creates  a  movie  from  data  that  you  provide. 


OSErr  NewMovieFromUserProc  ( 


Movi  e 
short 
Bool ean 
GetMovi eUPP 
voi  d 
Handl e 
OSType 


*m, 

f 1 ags , 

*dataRefWasChanged , 
getProc , 

*refCon , 
defaul tDataRef , 
dataRefType  ); 


m 

A  pointer  to  a  field  that  is  to  receive  the  new  movie's  identifier.  If  the  function 
cannot  load  the  movie,  the  returned  identifier  is  set  to  NIL. 

fl  ags 

Flags  (see  below)  that  control  the  operation  of  the  NewMovieFromUserProc 
function.  Be  sure  to  set  unused  flags  to  0. 
dataRefWasChanged 

A  pointer  toaBoolean  value.  The  Toolbox  sets  the  value  to  TRU  E  if  any  references 
were  changed.  Use  UpdateMovi  eResource  (III— 1983)  to  preserve  these  changes. 
Set  the  dataRefWasChanged  parameter  to  N I L  if  you  don't  want  to  receive  this 
information. 

getProc 

A  Universal  Procedure  Pointer  that  accesses  a  GetMovi  eProc  (III— 2085)  callback, 
which  is  responsible  for  providing  the  movie  data  to  the  Movie  Toolbox. 

refCon 

A  reference  constant  (defined  as  a  void  pointer).  This  is  the  same  value  you 
provided  to  the  Movie  Toolbox  when  you  called  NewMovieFromUserProc.  Use 
this  parameter  to  point  to  a  data  structure  containing  any  information  your 
callback  needs, 
defaul tDataRef 

The  default  data  reference.  This  parameter  contains  a  handle  to  the  information 
that  identifies  the  file  to  be  used  to  resolve  any  data  references  and  as  a  starting 
point  for  any  Alias  Manager  searches.  The  type  of  information  stored  in  the 
handle  depends  upon  the  value  of  the  dataRefType  parameter.  For  example,  if 
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NewMovieFromUserProc 


your  application  is  loading  the  movie  from  a  file,  you  would  refer  to  the  file's 
alias  in  the  defaul  tDataRef  parameter,  and  set  the  dataRefType  parameter  to 
rAl  i  asType.  If  you  don't  want  to  identify  a  default  data  reference,  set  the 
parameter  to  NIL. 

dataRefType 

The  type  of  data  reference.  If  the  data  reference  is  an  alias,  you  must  set  the 
parameter  to  rAl  i  asType,  indicating  that  the  reference  is  an  alias. 

function  result  If  the  Movie  Toolbox  cannot  completely  resolve  all  data  references,  it 
sets  the  current  error  value  to  coul  dNotResol  veDataRef.  You  can 
access  error  returns  such  as  this  through  GetMovi esError  (1-492)  and 
GetMovi  esSti  cky  Error  (1-494),  as  well  as  in  the  function  result.  See 
"Error  Codes"  (IV-2663). 

flags  Constants 

newMovi eActi ve 

Controls  whether  the  new  movie  is  active.  Set  this  flag  to  1  to  make  the  new 
movie  active.  You  can  make  a  movie  active  or  inactive  by  calling 
SetMovi  eActi  ve  (III — 1609). 
newMovi e Don t Res o 1 ve Data  Refs 

Controls  how  completely  the  Movie  Toolbox  resolves  data  references  in  the 
movie  resource.  If  you  set  this  flag  to  0,  the  toolbox  tries  to  completely  resolve 
all  data  references  in  the  resource.  This  may  involve  searching  for  files  on 
remote  volumes.  If  you  set  this  flag  to  1,  the  toolbox  only  looks  in  the  specified 
data  reference.  If  the  toolbox  cannot  completely  resolve  all  the  data  references, 
it  still  returns  a  valid  movie  identifier.  In  this  case,  the  toolbox  also  sets  the 
current  error  value  to  coul  dNotResol  veDataRef. 

newMovi  e  Don  t  As  kiln  resol  ved  Data  Refs 

Controls  whether  the  Movie  Toolbox  asks  the  user  to  locate  files.  If  you  set  this 
flag  to  0,  the  toolbox  asks  the  user  to  locate  files  that  it  cannot  find  on  available 
volumes.  If  the  toolbox  cannot  locate  a  file  even  with  the  user's  help,  the 
function  returns  a  valid  movie  identifier  and  sets  the  current  error  value  to 
coul  dNotResol  veDataRef. 

newMovi eDontAutoAlternate 

Controls  whether  the  Movie  Toolbox  automatically  selects  enabled  tracks  from 
alternate  track  groups.  If  you  set  this  flag  to  1,  the  toolbox  does  not 
automatically  select  tracks  for  the  movie;  you  must  enable  and  disable  tracks 
yourself. 
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N  e  wMoviePrePrerollCompleteUPP 


Discussion 

Normally,  when  a  movie  is  loaded  from  a  file  (for  example,  by  means  of 
NewMovi  eFromFi  1  e  (11-1080)),  the  Movie  Toolbox  uses  that  file  as  the  default  data 
reference.  Since  this  function  does  not  require  a  file  specification,  your  application 
should  specify  the  file  to  be  used  as  the  default  data  reference  using  the 
defaul  tDataRef  and  dataRefType  parameters. 

Special  Considerations 

The  Movie  Toolbox  automatically  sets  the  movie's  graphics  world  based  upon  the 
current  graphics  port.  Be  sure  that  your  application's  graphics  world  is  valid  before 
you  call  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movl  es  .  h 

Programming  summary:  "Movie  Functions"  (V-2713) 


NewMoviePrePrerollCompleteUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  Movi  ePrePrerol  1  Compl  eteProc 
(III— 2104)  callback. 

Movi  ePrePrerol  1  Compl  etellPP  NewMoviePrePrerollCompleteUPP  ( 

Movi ePrePrerol 1 Compl eteProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewMovi  ePrePrerol  1  Compl  eteProc. 

Programming  Info 

C  interface  file:  Movi  es  .  h 
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N  e  wMoviePrevie  wCallOutUPP 


NewMoviePreviewCallOutUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  Movl  ePrevI  ewCal  1  OutProc  (III— 2105) 
callback. 

Movi ePrevi ewCal 1 OutUPP  NewMoviePreviewCallOutUPP  ( 

Movi ePrevi ewCal 1 OutProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PozverPC  System  Softivare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewMovi  ePrevi  ewCal  1  OutProc. 

Programming  Info 

C  interface  file:  Movi  es . h 


NewMovieProgressUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  Movi eProgressProc  (III— 2105) 
callback. 

Movi eProgressUPP  NewMovieProgressUPP  ( 

Movi eProgressProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PozverPC  System  Softzvare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewMovieProgressProc. 

Programming  Info 

C  interface  file:  Movi  es .  h 
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N  e wMovieRgnCoverUPP 


NewMovieRgnCoverUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  Movi  eRgnCoverProc  (III— 2108) 
callback. 

Movi eRgnCoverUPP  NewMovieRgnCoverUPP  ( 

Movi eRgnCoverProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Softzvare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewMovi  eRgnCoverProc. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


NewMoviesErrorUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  Movi  esErrorProc  (III— 2109) 
callback. 

MoviesErrorUPP  NewMoviesErrorUPP  ( 

MoviesErrorProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewMovi  esErrorProc. 

Programming  Info 

C  interface  file:  Movi  es  .  h 
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N  e  wMovieTrack 


NewMovieTrack 


Creates  a  new  movie  track,  without  a  media. 

Track  NewMovieTrack  ( 

Movie  theMovie, 

Fixed  width, 

Fixed  height, 

short  trackVol ume  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
wi  dth 

A  fixed  number  denoting  the  display  width  of  the  track,  in  pixels, 
hei ght 

A  fixed  number  denoting  the  display  height  of  the  track,  in  pixels.  Together,  the 
height  and  width  parameters  define  the  track's  display  rectangle.  The 
upper-left  comer  of  this  rectangle  lies  at  (0,0)  in  the  movie's  rectangle.  The 
height  and  width  parameters  therefore  establish  the  lower-right  comer  of  the 
track's  display  rectangle.  If  you  are  creating  a  track  that  is  not  displayed,  such 
as  a  sound  track,  set  the  height  and  width  parameters  to  0. 
trackVol ume 

The  volume  setting  of  the  track  as  a  16-bit,  fixed-point  number.  The  high-order 
8  bits  specify  the  integer  portion;  the  low-order  8  bits  specify  the  fractional  part. 
Volume  values  range  from  -1.0  to  1.0.  Negative  values  play  no  sound  but 
preserve  the  absolute  value  of  the  volume  setting.  Set  this  parameter  to 
kFul  1  Vol  ume  to  play  the  track  at  its  full,  natural  volume.  Set  this  parameter  to 
kNoVol  ume  to  set  the  volume  to  0. 

function  result  The  identifier  of  the  new  track. 

trackVolume  Constants 

kFul 1 Vol ume 

Sets  the  track  to  full  volume  (constant  value  is  1.0). 
kNoVol ume 

Sets  the  track  to  no  volume  (constant  value  is  0.0). 

Discussion 

Immediately  after  creating  a  new  track,  you  should  call  NewT rackMedi  a  (11-1120)  to 
create  a  media  for  the  track;  a  track  without  a  media  is  of  no  use.  The  following  code 
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NewMusicMIDIReadHookUPP 


sample  creates  a  new  sprite  track  and  media,  then  calls  Begi  nMedi  a  Ed i  ts  (1-56)  to 
prepare  to  add  samples  to  the  media: 

//  NewMovi eTrack  coding  example 

//  See  “Discovering  QuickTime,"  page  349 

#define  kSpri teMedi aTimeScal e  600 

track  =  NewMovi eTrackimovi e ,  ( ( 1 ong )1 TrackWi dth  <<  16), 

( ( 1 ong )1 TrackHei ght  <<  16),  0); 
media  =  NewTrackMediaitrack,  Spri teMedi aType , 

kSpri teMedi aTimeScal e ,  NIL,  0); 

Fai 1 0SErr( Begi nMedi a  Ed i ts (medi a ) ) ; 

Special  Considerations 

When  you  add  a  track  to  a  movie,  the  Movie  Toolbox  automatically  adjusts  the 
display  Rect  (IV-2399)  structure  of  the  movie.  You  may  want  to  detect  these 
changes  by  calling  GetMovi  eBox  (1-460)  so  that  you  can  adjust  the  size  of  the  movie's 
display  window. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Creating  Tracks  and  Media  Structures"  (V-2726) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . newT  rack( ) , 
qui ckti me . std .movi es . Movi e . addTrack( ) 


NewMusicMIDIReadHookUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  Musi  cMIDIReadHookProc  (III— 2109) 
callback. 

MusicMIDIReadHookUPP  NewMusicMIDIReadHookUPP  ( 

MusicMIDIReadHookProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 
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NewMusicMIDISendUPP 


Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Softzvare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewMusicMIDIReadHookProc. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 


NewMusicMIDISendUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  Musi  cMIDISendProc  (III— 2110) 
callback. 

Musi cMIDISendUPP  NewMusicMIDISendUPP  ( 

Musi cMIDISendProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PozverPC  System  Softzvare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewMusi  cMIDISendProc. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 


NewMusicOfflineDataUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  Musi  cOffl  i neDataProc  (III— 2110) 
callback. 

Musi cOffl i neDataUPP  NewMusicOfflineDataUPP  ( 

Musi cOffl i neDataProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 
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N  e  wPrePrerollCompleteUPP 


function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewMusi  cOff  1  i  neDataProc. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 


NewPrePrerollCompleteUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  PrePrerol  1  Compl  eteProc  (III— 21 11) 
callback. 

PrePrerol 1 Compl eteUPP  NewPrePrerollCompleteUPP  ( 

PrePrerol 1 Compl eteProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PoiverPC  System  Softivare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewPrePrerol  1  Compl  eteProc. 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 


NewPreprocessInstructionHandlerUPP 


Undocumented 

P reprocess  Instruct! onHandlerUPP  NewPreprocessInstructionHandlerUPP  ( 
Preprocess Instructi onHandl er  userRoutine  ); 

userRouti ne 

Undocumented 
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function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

NewQDPixUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  QDPixProc  (III— 2117)  callback. 

QDPixUPP  NewQDPixUPP  ( 

QDPixProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PoiverPC  System  Softzvare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewQDPixProc. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

NewQTBandwidthNotificationUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  QTBandwi  dthNoti  f  i  cati  onProc 
(III— 2124)  callback. 

QTBandwi dthNoti fi cati onUPP  NewQTBandwidthNotificationUPP  ( 

QTBandwi dthNoti fi cati onProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 
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Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewQTBandwi  dthNoti  f  i  cati  onProc. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


NewQTCallBackUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  QTCal  1  BackProc  (III— 2124)  callback. 

QTCal 1 BackUPP  NewQTCallBackUPP  ( 

QTCal 1 BackProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewQTCal  1  BackProc. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


NewQTSModalFilterUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  QTSModal  Fi  1  terProc  (III— 2125) 
callback. 

QTSModal FilterUPP  NewQTSModalFilterUPP  ( 

QTSModal Fi 1 terProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 


Inside  QuickTime:  Function  l-Q 


11-1097 


NewQTSNotificationUPP 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


NewQTSNotificationUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  QTSNoti  fi  cati  onProc  (III— 2126) 
callback. 

QTSNoti fi cati on U P P  NewQTSNotificationUPP  ( 

QTSNoti fi cati onProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Softivare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewQTSNoti  fi  cati  onProc. 

Programming  Info 

C  interface  file:  Qui  ckT i  meStreami  ng .  h 


NewQTSPanelFilterUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  QTSPanel  Fi  1  terProc  (III— 2126) 
callback. 

QTSPanel  FilterUPP  NewQTSPanelFilterUPP  ( 

QTSPanel Fi 1 terProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Version  Notes 

Introduced  in  QuickTime  5. 


11-1098 


Inside  QuickTime:  Function  l-Q 


NewQTSyncTaskUPP 


Programming  Info 

C  interface  file:  Qui ckTi  meStreami  ng .  h 


NewQTSyncTaskUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  QTSyncTaskProc  (III— 2127)  callback. 

QTSyncTaskUPP  NewQTSyncTaskUPP  ( 

QTSyncTaskProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PoiverPC  System  Softivare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewQTSyncTaskProc. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


NewQTVRBackBufferlmagingUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  QTVRBackBufferlmagingProc 
(III— 2127)  callback. 

QTVRBackBuf f erlmagi ngUPP  NewQTVRBackBufferlmagingUPP  ( 

QTVRBackBuf f erlmagi ngProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PoiverPC  System  Softivare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewQTVRBackBufferlmagi  ngProc. 


Inside  QuickTime:  Function  l-Q 


11-1099 


N  e  wQTVREnteringNodeUPP 


Programming  Info 

C  interface  file:  Qui  ckTimeVR.  h 


NewQTVREnteringNodeUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  QTVREnteri  ngNodeProc  (III— 2128) 
callback. 

QTVREnteri ngNodeUPP  NewQTVREnteringNodeUPP  ( 

QTVREnteri ngNodeProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewQTVREnteri  ngNodeProc. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 


NewQTVRImagingCompleteUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  QTVRImagi  ngCompl  eteProc  (III— 2129) 
callback. 

QTVRImagi ngCompl eteUPP  NewQTVRImagingCompleteUPP  ( 

QTVRImagi ngCompl eteProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 


11-1100 


Inside  QuickTime:  Function  l-Q 


N  e  wQTVRInterceptUPP 


Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewQTVRImagi  ngCompl  eteProc. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 


NewQTVRInterceptUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  QTVRInterceptProc  (III— 2130) 
callback. 

QTVRInterceptUPP  NewQTVRInterceptUPP  ( 

QTVRInterceptProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewQTVRInterceptProc. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 


NewQTVRLeavingNodeUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  QTVRLeavi  ngNodeProc  (III— 2130) 
callback. 

QTVRLeavi ngNodeUPP  NewQTVRLeavingNodeUPP  ( 

QTVRLeavi ngNodeProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 


Inside  QuickTime:  Function  l-Q 


11-1101 


NewQTVRMouseOverHotSpotUPP 


Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Softzvare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewQTVRLeavi  ngNodeProc. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 


NewQTVRMouseOverHotSpotUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  QTVRMouseOverHotSpotProc 
(III— 2131)  callback. 

QTVRMouseOverHotSpotUPP  NewQTVRMouseOverHotSpotUPP  ( 
QTVRMouseOverHotSpotProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PozverPC  System  Softzvare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewQTVRMouseOverHotSpotProc. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 


NewRTPMPDataReleaseUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  RTPMPDataRel  easeProc  (III— 2132) 
callback. 

RTPMPDataRel easeUPP  NewRTPMPDataReleaseUPP  ( 

RTPMPDataRel easeProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 


11-1102 


Inside  QuickTime:  Function  l-Q 


N  e  wRTPPB  Callb  ackUPP 


function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewRTPMPDataRel  easeProc. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


NewRTPPBCallbackUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  RTPPBCall  backProc  (III— 2133) 
callback. 

RTPPBCal 1 backUPP  NewRTPPBCallbackUPP  ( 

RTPPBCal 1 backProcPtr  userRouti ne  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PoiverPC  System  Softivare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewRTPPBCallbackProc. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


NewSCModalFilterUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  SCModal  Fi  1  terProc  (III— 2133) 
callback. 

SCModal Fi 1 terUPP  NewSCModalFilterUPP  ( 

SCModal Fi 1 terProcPtr  userRoutine  ); 


Inside  QuickTime:  Function  l-Q 


11-1103 


NewSCModalHookUPP 


userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewSCModal  Fi  1  terProc. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


NewSCModalHookUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  SCModal  HookProc  (III— 2134) 
callback. 

SCModal HookUPP  NewSCModalHookUPP  ( 

SCModal HookProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Softzvare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewSCModal  HookProc. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 


NewSGAddFrameBottleUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  SGAddFrameBottl  eProc  (III— 2136) 
callback. 

SGAddFrameBottl eUPP  NewSGAddFrameBottleUPP  ( 

SGAddFrameBottl eProcPtr  userRoutine  ); 


11-1104 


Inside  QuickTime:  Function  l-Q 


NewSGCompressBottleUPP 


userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewSGAddFrameBottl  eProc. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


NewSGCompressBottleUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  SGCompressBottl  eProc  (III— 2137) 
callback. 

SGCompressBottl eUPP  NewSGCompressBottleUPP  ( 

SGCompressBottl eProcPtr  userRouti ne  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewSGCompressBottl  eProc. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 


NewSGCompressCompleteBottleUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  SGCompressCompl  eteBottl  eProc 
(III— 2138)  callback. 

SGCompressCompl eteBottl eUPP  NewSGCompressCompleteBottleUPP  ( 
SGCompressCompl eteBottl eProcPtr  userRoutine  ); 


Inside  QuickTime:  Function  l-Q 


11-1105 


NewSGDataUPP 


userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewSGCompressCompl  eteBottl  eProc. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


NewSGDataUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  SGDataProc  (III— 2139)  callback. 

SGDataUPP  NewSGDataUPP  ( 

SGDataProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewSGDataProc. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 


NewSGDisplayBottleUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  SGDi  s pi  ayBottl  eProc  (III— 2140) 
callback. 

SGDi spl ayBottl eUPP  NewSGDisplayBottleUPP  ( 

SGDi spl ayBottl eProcPtr  userRoutine  ); 


11-1106 


Inside  QuickTime:  Function  l-Q 


NewSGDisplayCompressBottleUPP 


userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewSGDi  spl  ayBottl  eProc. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


NewSGDisplayCompressBottleUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  SGDi  spl  ayCompressBottl  eProc 
(III— 2141)  callback. 

SGDi  spl  ayCompressBottl  ellPP  NewSGDi  spl  ayCompressBottl  eUPP  ( 

SGDi spl ayCompressBottl eProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewSGDi  spl  ayCompressBottl  eProc. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 


NewSGGrabBottleUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  SGGrabBottl  eProc  (III— 2142) 
callback. 

SGGrabBottl eUPP  NewSGGrabBottleUPP  ( 

SGGrabBottl eProcPtr  userRoutine  ); 


Inside  QuickTime:  Function  l-Q 


11-1107 


NewSGGrabCompleteBottleUPP 


userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewSGGrabBottl  eProc. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


NewSGGrabCompleteBottleUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  SGGrabCompl  eteBottl  eProc 
(III— 2143)  callback. 

SGGrabCompl  eteBottl  ellPP  NewSGGrabCompleteBottleUPP  ( 

SGGrabCompl eteBottl eProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Softzvare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewSGGrabCompl  eteBottl  eProc. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 


NewSGGrabCompressCompleteBottleUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  SGGrabCompressCompl  eteBottl  eProc 
(III— 2143)  callback. 

SGGrabCompressCompl eteBottl eUPP  NewSGGrabCompressCompl eteBottl eUPP  ( 
SGGrabCompressCompl eteBottl eProcPtr  userRoutine  ); 


11-1108 


Inside  QuickTime:  Function  l-Q 


NewSGModalFilterUPP 


userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewSGGrabCompressCompl  eteBottl  eProc. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


NewSGModalFilterUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  SGModal  Fi  1  terProc  (III— 2144) 
callback. 

SGModal FilterUPP  NewSGModalFilterUPP  ( 

SGModal Fi 1 terProcPtr  userRouti ne  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewSGModal  Fi  1  terProc. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 


NewSGTransferFrameBottleUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  SGT ransferFrameBottl  eProc 
(III— 2145)  callback. 

SGTransferFrameBottl eUPP  NewSGTransferFrameBottleUPP  ( 
SGTransferFrameBottl eProcPtr  userRoutine  ); 


Inside  QuickTime:  Function  l-Q 


11-1109 


NewSICompletionUPP 


userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewSGT ransferFrameBottl  eProc. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


NewSICompletionUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  SICompI  eti  onProc  (III— 2146) 
callback. 

SICompI  eti  onLIPP  NewSICompletionUPP  ( 

SICompI eti onProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Softzvare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewSICompl  eti  onProc. 

Programming  Info 

C  interface  file:  Sound .  h 


NewSIInterruptUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  SI  InterruptProc  (III— 2147) 
callback. 

SI InterruptUPP  NewSIInterruptUPP  ( 

SI InterruptProcPtr  userRoutine  ); 


11-1110 


Inside  QuickTime:  Function  l-Q 


NewSndCallBackUPP 


userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewSI  InterruptProc. 

Programming  Info 

C  interface  file:  Sound .  h 


NewSndCallBackUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  SndCall  BackProc  (III— 2147) 
callback. 

SndCall BackUPP  NewSndCallBackUPP  ( 

SndCal 1 BackProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewSndCal  1  BackProc. 

Programming  Info 

C  interface  file:  Sound .  h 


NewSndDoubleBackUPP 


Obsolete. 

SndDoubl eBackUPP  NewSndDoubleBackUPP  ( 

SndDoubl eBackProcPtr  userRoutine  ); 


Inside  QuickTime:  Function  l-Q 


11-1111 


NewSoundConverterFillBufferDataUPP 


Version  Notes 

Introduced  in  QuickTime 4.1  to  replace  NewSndDoubl  eBackProc.  Macintosh  Note:  Not 
supported  by  CarbonLib. 

Programming  Info 

C  interface  file:  Sound .  h 


NewSoundConverterFillBufferDataUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  SoundConverterFi  llBufferDataProc 
(III— 2148)  callback. 

SoundConverterFi 11 BufferDataUPP  NewSoundConverterFi 1 1 BufferDataUPP  ( 
SoundConverterFi 1 1 BufferDataProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Softivare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Sound .  h 


NewSoundParamUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  SoundParamProc  (III— 2149)  callback. 

SoundParamUPP  NewSoundParamUPP  ( 

SoundParamProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 


11-1112 


Inside  QuickTime:  Function  l-Q 


NewSprite 


Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewSoundParamProc. 

Programming  Info 

C  interface  file:  Sound .  h 


NewSprite 


Creates  a  new  sprite  in  a  specified  sprite  world. 

OSErr  NewSprite  ( 

Spri te 
Spri  teWorl  d 

ImageDescri pti onHandl e 
Ptr 

Matri xRecord 
Bool ean 
short 

newSpri te 

A  pointer  to  field  that  is  to  receive  the  new  sprite's  identifier.  On  return,  this 
field  contains  the  identifier  of  the  newly  created  sprite. 

i tsSpri teWorl d 

The  sprite  world  with  which  the  new  sprite  should  be  associated, 
i  dh 

A  handle  to  an  ImageDescri  pti  on  (IV-2285)  structure  of  the  sprite's  image. 
imageDataPtr 

A  pointer  to  the  sprite's  image  data, 
matri x 

A  pointer  to  the  sprite's  Matri  xRecord  (IV-2304)  structure.  If  you  pass  NI L,  an 
identity  matrix  is  assigned  to  the  sprite. 

vi  si  bl  e 

Specifies  whether  the  sprite  is  visible. 

1  ayer 

The  sprite's  layer.  Sprites  with  lower  layer  values  appear  in  front  of  sprites  with 
higher  layer  values .  If  you  want  to  create  a  sprite  that  is  drawn  to  the  background 


*newSpri te , 
i tsSpri teWorl d  , 
i  dh , 

imageDataPtr, 
*matrix, 
vi  si  bl  e , 
layer  ); 
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graphics  world,  you  should  specify  the  constant  kBackgroundSpriteLayerNumfor 
the  1  ayer  parameter. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

The  visible  parameter,  the  1  ayer  parameter,  and  the  newSpri  te  and  i  tsSpri  teWorl  d 
parameters  are  required.  You  can  defer  assigning  image  data  to  the  sprite  by 
passing  N I L  for  both  the  i  d h  and  imageDataPtr  parameters .  If  you  choose  to  defer 
assigning  image  data,  you  must  call  SetSpri  teProperty  (III— 1641)  to  assign  the 
image  description  handle  and  image  data  to  the  sprite  before  the  next  call  to 
Spri  teWorl dldl e  (III — 1908). 

Special  Considerations 

The  caller  owns  the  image  description  handle  and  the  image  data  pointer;  it  is  the 
caller's  responsibility  to  dispose  of  them  after  it  disposes  of  a  sprite. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Creating  and  Manipulating  Sprites"  (V-2901) 

Related  Java  Methods 

qu ickti me. std. an im. Sprite. Sprite! ) 


See  Also 

Once  you  have  created  the  sprite,  you  can  manipulate  it  using  SetSpri  teProperty 
(III— 1641). 


NewSpriteWorld 


Creates  a  new  sprite  world. 


OSErr  NewSpriteWor 
Spri  teWorl  d 
GWorl dPtr 
GWorl dPtr 
RGBCol or 
GWorl dPtr 


d  ( 

*newSpri teWorl d , 
desti nati on , 
spri teLayer , 
*backgroundCol or , 
background  ) ; 
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newSpri teWorl d 

A  pointer  to  a  field  that  is  to  receive  the  new  sprite  world's  identifier.  On 
return,  this  field  contains  the  identifier  for  the  newly  created  sprite  world, 
desti nati on 

A  pointer  to  a  CGraf  Port  (IV-2168)  structure  that  defines  the  graphics  world  to 
be  used  as  the  destination. 

spri  teLayer 

A  pointer  to  a  CGraf  Port  (IV-2168)  structure  that  defines  the  graphics  world  to 
be  used  as  the  sprite  layer. 
backgroundCol or 

A  pointer  to  an  RGBCol  or  (IV-2403)  structure  that  defines  the  color  to  be  used  as 
the  background  color  .Ifyoupassabackground  graphics  world  to  this  function 
by  setting  the  background  parameter,  you  can  set  this  parameter  to  NIL. 
background 

A  pointer  to  a  CGraf  Port  (IV-2168)  structure  that  defines  the  graphics  world  to 
be  used  as  the  background.  If  you  pass  a  background  color  to  this  function  by 
setting  the  backgroundCol  or  parameter,  you  can  set  this  parameter  to  NIL. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

You  call  this  function  to  create  a  new  sprite  world  with  associated  destination  and 
sprite  layer  graphics  worlds,  and  either  a  background  color  or  a  background  graphics 
world.  Once  created,  you  can  manipulate  the  sprite  world  and  add  sprites  to  it  using 
other  sprite  Movie  Toolbox  functions. 

The  newSpri  teWorl  d,  destination,  and  spri  teLayer  parameters  are  all  required.  You 
should  specify  a  b  a  c  k  g  r  o  u  n  d  color,  a  b  a  c  k  g  r  o  u  n  d  graphics  world,  or  both.  You  should 
not  pass  NIL  for  both  parameters.  If  you  specify  both  a  background  graphics  world 
and  a  background  color,  the  sprite  world  is  filled  with  the  background  color  before  the 
background  sprites  are  drawn.  If  no  background  color  is  specified,  black  is  the  default. 
If  you  specify  a  background  graphics  world,  it  should  have  the  same  dimensions  and 
depth  as  the  graphics  world  specified  by  spri  teLayer.  If  you  draw  to  the  graphics 
worlds  associated  with  a  sprite  world  using  standard  QuickDraw  and  QuickTime 
functions,  your  drawing  is  erased  by  the  sprite  world's  background  color.  The  sprite 
world  created  by  this  function  has  an  identity  matrix  and  does  not  have  a  clip  shape. 

Here  is  an  example  of  creating  a  sprite  world: 


N 
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//  NewSpri teWorl d  coding  example 

//  See  “Discovering  QuickTime,”  page  166 

GWorldPtr  pSpritePlane  =  NIL; 

SpriteWorld  spriteWorld  =  NIL; 

Rect  rectBounce; 

RGBColor  rgbcBackground ; 

void  CreateSpri teStuff  (Rect  *pWndRect,  CGrafPtr  pMacWnd) 

{ 

OSErr  nErr; 

Rect  rect; 

//  calculate  the  size  of  the  destination 
rect  =  *pWndRect; 

OffsetRect(&rect,  -rect. left,  -rect. top); 
rectBounce  =  rect; 

InsetRectt&rectBounce,  16,  16); 

//  create  a  sprite  graphics  world  with  a  bit  depth  of  16 
NewGWorldt&pSpritePlane,  16,  &rect,  NIL,  NIL,  useTempMem); 
if  (pSpritePlane  ==  NIL) 

NewGWorl d( & p S p r i tePl ane ,  16,  &rect,  NIL,  NIL,  0); 

if  (pSpritePlane  !=  NIL)  { 

LockPixels(pSpritePlane->portPi xMap) ; 
rgbcBackground . red  = 
rgbcBackground . green  = 
rgbcBackground . bl ue  =  0; 

//  create  a  sprite  world 

nErr  =  NewSpri teWorl d( &spri teWorl  d ,  (CGrafPtr)pMacWnd, 
pSpritePlane,  &rgbcBackground ,  NIL); 

} 

} 

Special  Considerations 

Before  calling  this  function,  you  should  lock  the  pixel  maps  of  the  sprite  layer  and 
background  graphics  worlds.  These  graphics  worlds  must  remain  valid  and  locked 
for  the  lifetime  of  the  sprite  world.  The  sprite  world  does  not  own  the  graphics 
worlds  that  are  associated  with  it;  it  is  the  caller's  responsibility  to  dispose  of  the 
graphics  worlds  when  they  are  no  longer  needed. 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  with  Sprite  Worlds"  (V-2900) 

Related  Java  Methods 

qui  cktime .  std  .  anim.  Spri  teWorl  d  .  Spri  teWorl  d( ) 


NewStartDocumentHandlerUPP 


Undocumented 

StartDocumentHandl erUPP  NewStartDocumentHandlerUPP  ( 
StartDocumentHandl er  userRoutine  ); 

userRouti ne 

Undocumented 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


NewStartElementHandlerUPP 


Undocumented 

StartEl ementHandl erUPP  NewStartElementHandlerUPP  ( 

StartEl ementHandl er  userRoutine  ); 

userRouti ne 

Undocumented 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 
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NewStdPixUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  StdPixProc  (III— 2149)  callback. 

StdPixUPP  NewStdPixUPP  ( 

StdPi xProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewStdPixProc. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


NewTextMediaUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  TextMedi  aProc  (III— 2150)  callback. 

TextMedlaUPP  NewTextMediaUPP  ( 

TextMedi aProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Softzvare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewTextMedi  aProc. 

Programming  Info 

C  interface  file:  Movi  es .  h 
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NewTimeBase 


Obtains  a  new  time  base. 

TimeBase  NewTimeBase  (  void  ); 
function  result  The  ID  of  the  new  time  base. 

Discussion 

This  function  sets  the  rate  of  the  time  base  to  0,  the  start  time  to  its  minimum  value, 
the  time  value  to  0,  and  the  stop  time  to  its  maximum  value.  The  function  assigns 
the  default  clock  component  to  the  new  time  base. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Creating  and  Disposing  of  Time  Bases"  (V-2759) 

Related  Java  Methods 

qui ckti me . std . cl ocks . TimeBase .TimeBase ( ) 


See  Also 

If  you  want  to  assign  a  different  clock  component  or  a  master  time  base  to  the  new 
time  base,  use  SetTimeBaseMasterCl  ock  (III— 1649)  or  SetTimeBaseMasterTimeBase 
(III— 1650). 

NewT  rackEditState 


Creates  a  new  edit  state  for  a  given  track. 

TrackEdi tState  NewTrackEdi tState  ( 

Track  theTrack  ); 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

function  result  The  track's  edit  state  identifier.  If  the  edit  state  could  not  be  created, 
the  returned  identifier  is  set  to  NI L.  You  must  dispose  of  a  movie's 
track  edit  states,  using  Use  DisposeTrackEdi  tState  (1-300),  before 
disposing  of  the  track  or  of  the  movie  that  contains  the  track. 
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Discussion 

Use  the  returned  identifier  with  other  Movie  Toolbox  edit  state  functions,  such  as 
UseTrackEditState  (III— 1984).  The  edit  state  contains  all  the  information  describing 
a  track's  content,  including  the  identity  of  the  media  data  associated  with  the  track 
and  all  the  track's  edit  lists. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi es .  h 

Programming  summary:  "Undo  for  Tracks"  (V-2751) 

Related  Java  Methods 

quickti me. std. mo vies. Track. newEditStateO 


NewTrackMedia 


Creates  a  media  for  a  new  track. 


Media  NewTrackMedia  ( 


T  rack 
OSType 
TimeScale 
Handl e 
OSType 


theT  rack , 
medi aType , 
ti meScal e , 
dataRef , 
dataRefType 


) : 


theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eTrack  (11-1092). 
medi aType 

The  type  of  media  to  create;  see  "Codec  Identifiers"  (IV-2655).  The  Movie 
Toolbox  uses  this  value  to  find  the  correct  media  handler  for  the  new  media.  If 
the  Movie  Toolbox  cannot  locate  an  appropriate  media  handler,  it  returns  an 
error. 

ti meScal e 

Defines  the  media's  time  coordinate  system. 
dataRef 

The  data  reference.  This  parameter  contains  a  handle  to  the  information  that 
identifies  the  file  that  contains  this  media's  data.  The  type  of  information  stored 
in  that  handle  depends  upon  the  value  of  the  dataRefType  parameter.  If  you  are 
creating  a  new  media  that  refers  to  existing  media  data,  you  can  use  the 
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GetMedi  aDataRef  (1-427)  function  to  obtain  information  about  the  existing  data 
reference.  You  can  then  supply  information  about  that  reference  to  this 
function.  Set  this  parameter  to  N I L  to  use  the  file  that  is  associated  with  the 
movie  or  if  the  movie  does  not  have  a  movie  file.  For  example,  if  you  have 
created  the  movie  using  CreateMovi  eFi  1  e  (1-145)  or  NewMovi  eFromFi  1  e  (11-1080), 
the  Movie  Toolbox  assumes  that  the  movie's  data  resides  in  the  file  specified  at 
that  time.  If  you  have  created  the  movie  using  the  NewMovi  eFromScrap  (11-1085) 
or  NewMovi  e  (11-1069)  functions,  the  movie  does  not  have  a  movie  file. 

dataRefType 

The  type  of  data  reference;  see  "Data  References"  (IV-2661).  If  the  data 
reference  is  an  alias,  you  must  set  this  parameter  to  rAl  i  asType.  See  Inside 
Macintosh:  Files  (listed  in  the  bibliography)  for  more  information  about  aliases 
and  the  Alias  Manager. 

function  result  A  media  identifier,  referring  to  the  actual  data  samples  used  by  the 
track.  If  the  function  cannot  create  a  new  media,  it  sets  the  returned 
value  to  NIL. 

Discussion 

The  following  code  sample  creates  a  new  sprite  track  and  media,  then  calls 

Begi  nMedi  a  Ed  1  ts  (1-56)  to  prepare  to  add  samples  to  the  media: 

//  NewTrackMedia  coding  example 

//  See  “Discovering  QuickTime,”  page  349 

#define  kSpri teMedi aTimeScal e  600 

track  =  NewMovi eTrack(movi e ,  ( ( 1 ong )1 TrackWi dth  <<  16), 

( ( 1 ong )1 TrackHei ght  <<  16),  0); 

media  =  NewTrackMedia(track,  Spri teMedi aType , 

kSpri teMedi aTimeScal e ,  NIL,  0); 

Fa i 1 0SErr( Begi nMedi a  Ed i ts (medi a ) ) ; 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Creating  Tracks  and  Media  Structures"  (V-2726) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Musi cMedi a . Musi cMedi  a ( ) , 
qui cktime . std .movi es .medi a .Ti meCodeMedi a . Ti meCodeMedi a ( ) , 
qui cktime . std .movi es .medi a . TextMedi a .TextMedi a ( ) , 
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qu  i  c  kti  me.  std.  mo  vies,  media.  Video  Media.  Vi deoMedi a ( ) , 
qui ckti me . std .movi es .medi a . BaseMedi a . BaseMedi a ( ) , 
qui ckti me . std .movi es .medi a .TweenMedi a .TweenMedi a ( ) , 
qui ckti me . std .movi es .medi a . Spri teMedi a . Spri teMedi a ( ) , 
qui ckti me . std .movi es .medi a . MPEGMedi a . MPEGMedi a ( ) , 
qui ckti me . std .movi es .medi a . SoundMedi a . SoundMedi a () , 
qui ckti me . std .movi es .medi a . Medi a . newFromTypet ) , 
quicktime.std.movies.media.ThreeDMedia.ThreeDMediat ) 

NewT  rackT  ransf  erUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  TrackTransferProc  (III— 2151) 
callback. 

TrackTransferUPP  NewTrackTransferUPP  ( 

TrackTransferProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PozverPC  System  Softivare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewTrackTransferProc. 

Programming  Info 

C  interface  file:  Movi  es .  h 


N  e  wT  uneCallB  ackUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  TuneCal  1  BackProc  (III— 2152) 
callback. 

TuneCal 1 BackUPP  NewTuneCal 1 BackUPP  ( 

TuneCall BackProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 
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function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewTuneCallBackProc. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 


NewTunePlayCallBackUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  TunePl  ayCall  BackProc  (III— 2152) 
callback. 

TunePl ayCal 1 BackUPP  NewTunePlayCallBackUPP  ( 

TunePl ayCal 1 BackProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PoiverPC  System  Softivare  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewT unePl  ayCal  1  BackProc. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 


NewTweenerDataUPP 


Allocates  a  Universal  Procedure  Pointer  for  the  TweenerDataProc  (III— 2153) 
callback. 

TweenerDataUPP  NewTweenerDataUPP  ( 

TweenerDataProcPtr  userRoutine  ); 
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userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewTweenerDataProc. 

Programming  Info 

C  interface  file:  Movi  es .  h 


NewUserData 


Creates  a  new  user  data  structure. 

OSErr  NewUserData  ( 

UserData  *theUserData  ); 

theUserData 

A  pointer  to  a  pointer  to  a  new  UserData  Record  (IV-2496)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error.  If  the 
function  fails,  theUserData  is  set  to  NIL. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  User  Data"  (V-2743) 

Related  Java  Methods 

qu i c kti me. std. mo vies. media. User Data. User Da tat) 


NewUserDataFromHandle 


Creates  a  new  user  data  structure  from  a  handle. 

OSErr  NewUserDataFromHandle  ( 

Handle  h, 

UserData  *theUserData  ); 
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h 

A  handle  to  the  data  structure  specified  inthellserData. 
thellserData 

A  pointer  to  a  pointer  to  a  new  UserDataRecord  (IV-2496)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error.  If  the 
function  fails,  thellserData  is  set  to  NIL. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  User  Data"  (V-2743) 

Related  Java  Methods 

qui cktime . std .movi es .medi a.UserData.UserDatal) 


NewVdiglntUPP 

Allocates  a  Universal  Procedure  Pointer  for  the  Vdi  glntProc  (III— 2154)  callback. 

Vdi glntUPP  NewVdiglntUPP  ( 

VdiglntProcPtr  userRoutine  ); 

userRouti ne 

Your  application-defined  function. 

function  result  A  new  UPP;  see  "Universal  Procedure  Pointers"  (IV-2641). 

Discussion 

This  function  is  used  with  Macintosh  PowerPC  systems.  See  Inside  Macintosh: 
PowerPC  System  Software  (listed  in  the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  NewVdi  glntProc. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 
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OpenAComponent 

Gains  access  to  the  services  provided  by  a  component  specified  by  a  component 
identifier  and  returns  an  OSErr  value. 

OSErr  OpenAComponent  ( 

Component  aComponent, 

Componentlnstance  *ci  ); 

aComponent 

A  component  identifier  that  specifies  the  component  to  open.  Your  application 
obtains  this  identifier  from  Fi  ndNextComponent  (1-360).  If  your  application 
registers  a  component,  it  can  also  obtain  a  component  identifier  from 
Regi  sterComponent  (III — 1451)  or  Regi  sterComponentResource  (III — 1453). 

ci 

A  pointer  to  a  field  to  receive  the  instance  of  the  newly-opened  component. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Component  Functions  Used  By  Applications"  (V-2781) 

Related  Java  Methods 

qui ckti me. std. comp. Component. Component! ) , 

qui ckti me . std . qt components . DataCodecDecompressor . DataCodecDecompressor ( ) , 

qui ckti me . std . qt components .Movi e Exporter . Movi e Exporter! ) , 

qui ckti me . std . qt components . Movielmporter.Movielmporter! ) , 

qui ckti me . std . qt components . DataCodecCompressor . DataCodecCompressor ( ) 


See  Also 

This  function  acts  similarly  to  OpenComponent  (11-1130),  except  that  it  provides  an 
OSErr  value  return. 
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OpenAComponentResFile 


OpenAComponentResFile 

Allows  your  component  to  gain  access  to  its  resource  file  and  returns  an  OS  Err 
value. 

OSErr  OpenAComponentResFile  ( 

Component  aComponent, 

short  *resRef  ); 

aComponent 

A  component  identifier  that  specifies  the  component  whose  resource  file  you 
want  to  open.  Your  application  can  obtain  this  identifier  from 
Regi  sterComponentResource  (III— 1453)  or  Fi  ndNextComponent  (1-360);  or  it  can  be 
a  Componentlnstance  value,  in  which  case  it's  returned  by  OpenAComponent 
(11-1126)  or  OpenADefaul  tComponent  (11-1129). 

resRef 

A  pointer  to  a  field  to  receive  the  resource  reference  number  of  the  newly 
opened  component  resource  file. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 

See  Also 

This  function  acts  similarly  to  OpenComponentResFi  1  e  (11-1130),  except  that  it 
provides  an  OSErr  value  return. 


OpenADataHandler 


Opens  a  data  handler  component. 


OSErr  OpenADataHandler 
Hand! e 
OSType 
Hand! e 
OSType 
T i meBase 
1  ong 

Componentlnstance 


dataRef , 

dataHandlerSubType, 
anchorDataRef , 
anchorDataRefType, 
tb , 

fl ags , 

*dh  ) ; 
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OpenADataHandler 


dataRef 

A  handle  to  a  data  reference.  The  type  of  information  stored  in  the  handle 
depends  upon  the  data  reference  type  specified  by  the  dataHandlerSubType 
parameter. 
dataHandlerSubType 

Identifies  both  the  type  of  data  reference  and,  by  implication,  the  component 
subtype  value  assigned  to  the  data  handler  components  that  operate  on  data 
references  of  that  type. 

anchorDataRef 

A  handle  to  the  anchor  data  reference, 
anchor Data RefType 

The  type  of  the  anchor  data  reference, 
tb 

The  time  base  for  the  data  handler.  Your  application  obtains  this  time  base 
identifier  from  NewTimeBase  (11-1119). 

fl  ags 

Flags  (see  below)  that  indicate  the  way  in  which  you  intend  to  use  the  data 
handler  component.  Not  all  data  handlers  necessarily  support  all  services;  for 
example,  some  data  handler  components  may  not  support  streaming  writes. 
Set  the  appropriate  flags  to  1. 
dh 

A  pointer  to  a  field  to  receive  the  Component  Instance  value  of  the  newly-opened 
data  handler  component. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

flags  Constants 

kDataHCanRead 

You  intend  to  use  the  data  handler  component  to  read  data. 
kDataHCanWri  te 

You  intend  to  use  the  data  handler  component  to  write  data. 
kDataHCanStreamingWrite 

You  intend  to  do  streaming  writes  (as  part  of  a  movie-capture  operation,  for 
example). 

Version  Notes 

Introduced  in  QuickTime  4.1. 
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Programming  Info 

C  interface  file:  Movi  es  .  h 


OpenADefaultComponent 

Gains  access  to  the  services  provided  by  a  component,  specified  by  component  type 
and  subtype,  and  returns  an  OS  Err  value. 

OSErr  OpenADefaultComponent  ( 

OSType  componentType , 

OSType  componentSubType , 

Componentlnstance  *ci  ); 

componentType 

A  four-character  code  that  identifies  the  type  of  component.  All  components  of 
a  particular  type  support  a  common  set  of  interface  routines.  Your  application 
uses  this  field  to  search  for  components  of  a  given  type. 

componentSubType 

A  four-character  code  that  identifies  the  subtype  of  the  component.  Different 
subtypes  of  a  component  type  may  support  additional  features  or  provide 
interfaces  that  extend  beyond  the  standard  routines  for  a  given  component 
type.  For  example,  the  subtype  of  an  image  compressor  component  indicates 
the  compression  algorithm  employed  by  the  compressor.  Your  application  can 
use  the  componentSubType  field  to  perform  a  more  specific  lookup  operation 
than  is  possible  using  only  the  componentType  field  .For  example,  you  may  want 
your  application  to  use  only  components  of  a  certain  component  type  ('draw') 
that  also  have  a  specific  subtype  ('oval ').  Set  this  parameter  to  0  to  select  a 
component  with  any  subtype  value. 

ci 

A  pointer  to  a  field  to  receive  the  Componentlnstance  value  of  the  newly-opened 
component. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Component  Functions  Used  By  Applications"  (V-2781) 

Related  Java  Methods 

qui ckti me . std . image . Graphi cs Importer . Graph i cs Importer! ) , 
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OpenComponent 


qui ckti me . std . qt components . DataCodecDecompressor . DataCodecDecompressor ( ) , 

qui ckti me. std. comp. Component. Component!  ) , 

qui ckti me . std . qt components .Movi e Exporter . Movi e Exporter ( ) , 

qui ckti me . std . qt components . Movielmporter.Movielmportert ) , 

qui ckti me . std .musi c . Musi cComponent .Musi cComponent ( ) , 

qui  ckti  me.  std.  clocks.  Clock.  ClockO, 

qui ckti me. std. music. Not eAllocator. Not eAllocatort), 

qui ckti me. std .musi c. Tune PI  ay er .Tune PI  ay er( ) , 

qui ckti me . std . qt components . DataCodecCompressor . DataCodecCompressor ( ) , 

quicktime.std.sg.SequenceGrabber.SequenceGrabbert), 

quicktime.std.sg.VideoDigitizer.VideoDigitizert) 

See  Also 

This  function  acts  similarly  to  OpenDefaul  tComponent  (11-1131),  except  that  its  return 
value  is  an  OSErr  value. 


OpenComponent 


Gains  access  to  the  services  provided  by  a  component  specified  by  a  component 
identifier. 

Componentlnstance  OpenComponent  ( 

Component  aComponent  ) ; 

aComponent 

A  component  identifier  that  specifies  the  component  to  open.  Your  application 
obtains  this  identifier  from  Fi  ndNextComponent  (1-360).  If  your  application 
registers  a  component,  it  can  also  obtain  a  component  identifier  from 
Regi  sterComponent  (III — 1451)  or  Regi  sterComponentResource  (III — 1453). 

function  result  An  instance  of  the  component. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Component  Functions  Used  By  Applications"  (V-2781) 


OpenComponentResFile 

Allows  your  component  to  gain  access  to  its  resource  file. 
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OpenDefaultComponent 


short  OpenComponentResFi 1 e  ( 

Component  aComponent  ); 

aComponent 

A  component  identifier  that  specifies  the  component  whose  resource  file  you 
want  to  open.  Your  application  can  obtain  this  identifier  from 
Regi  sterComponentResource  (III— 1453)  or  Fi  ndNextComponent  (1-360);  or  it  can  be 
a  Componentlnstance  value,  in  which  case  it's  returned  by  OpenAComponent 
(11-1126)  or  OpenADef  aul  tComponent  (11-1129). 

function  result  The  resource  reference  number  of  the  newly  opened  component 
resource  file. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 


OpenDefaultComponent 

Gains  access  to  the  services  provided  by  a  component  specified  by  component  type 
and  subtype. 

Componentlnstance  OpenDefaultComponent  ( 

OSType  componentType , 

OSType  componentSubType  ); 

componentType 

A  four-character  code  that  identifies  the  type  of  component.  All  components  of 
a  particular  type  support  a  common  set  of  interface  routines.  Your  application 
uses  this  field  to  search  for  components  of  a  given  type. 

componentSubType 

A  four-character  code  that  identifies  the  subtype  of  the  component.  Different 
subtypes  of  a  component  type  may  support  additional  features  or  provide 
interfaces  that  extend  beyond  the  standard  routines  for  a  given  component 
type.  For  example,  the  subtype  of  an  image  compressor  component  indicates 
the  compression  algorithm  employed  by  the  compressor.  Your  application  can 
use  the  componentSubType  field  to  perform  a  more  specific  lookup  operation 
than  is  possible  using  only  the  componentType  field.  For  example,  you  may  want 
your  application  to  use  only  components  of  a  certain  component  type  ('draw') 
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OpenMixerSoundComponent 


that  also  have  a  specific  subtype  ( '  oval ' ).  Set  this  parameter  to  0  to  select  a 
component  with  any  subtype  value. 

function  result  The  Componentlnstance  value  of  the  newly-opened  component. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Component  Functions  Used  By  Applications"  (V-2781) 


OpenMixerSoundComponent 

Opens  the  Apple  Mixer  sound  component. 

OSErr  OpenMixerSoundComponent  ( 

SoundComponentDataPtr  outputDescription, 

long  outputFlags, 

Componentlnstance  *mi xerComponent  ); 

outputDescri pti on 

A  pointer  to  a  SoundComponentData  (IV-2448)  structure  for  the  mixer  output. 
outputFl ags 

Flags  (see  below)  that  provide  information  about  the  sound  component  chain, 
mi xerComponent 

A  pointer  to  memory  that  is  to  receive  an  instance  of  the  Apple  Mixer 
component. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

outputFlags  Constants 

kNoMi xi ng 

The  Apple  Mixer  does  not  mix  audio  data  sources. 
kNoSampleRateConversion 

The  sound  component  chain  does  not  perform  sample  rate  conversion  (for 
example,  from  11  kHz  data  to  22  kHz  data). 
kNoSampleSizeConversion 

The  sound  component  chain  does  not  perform  sample  size  conversion  (for 
example,  from  8-bit  data  to  16-bit  data). 
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OpenMovieFile 


kNoSampl eFormatConversi  on 

The  sound  component  chain  does  not  convert  between  sample  formats  (for 
example,  converting  from  two's  complement  data  to  offset  binary  data).  Most 
sound  output  devices  on  Macintosh  computers  accept  only  8-bit  offset  binary 
data,  which  is  therefore  the  default  type  of  data  produced  by  the  Apple  Mixer. 
If  your  output  device  can  handle  either  offset  binary  or  two's  complement  data, 
you  should  set  this  flag.  Note  that  16-bit  data  is  always  in  two's  complement 
format. 

kNoChannel Conversion 

The  sound  component  chain  does  not  convert  channels  (for  example,  between 
monophonic  and  stereo). 

kNoDecompressi on 

The  sound  component  chain  does  not  decompress  audio  data.  If  your  output 
device  can  decompress  data,  you  should  set  this  flag. 
kNoVol umeConversi  on 

The  sound  component  chain  does  not  convert  volumes. 
kNoReal timeProcessi  ng 

The  sound  component  chain  does  not  do  any  processing  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


OpenMovieFile 


Opens  a  specified  movie  file. 

OSErr  OpenMovieFile  ( 

const  FSSpec  *fileSpec, 

short  *resRefNum, 

SInt8  permission  ); 

f i 1 eSpec 

A  pointer  to  the  FSSpec  (IV-2262)  structure  for  the  movie  file  to  be  opened. 
resRefNum 

A  pointer  to  a  field  that  is  to  receive  the  file  reference  number  for  the  opened 
movie  file.  Your  application  must  use  this  value  when  calling  other  Movie 
Toolbox  functions  that  work  with  movie  files.  This  reference  number  refers  to 
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OpenMovieFile 


the  file  fork  that  contains  the  movie  resource.  If  the  movie  is  stored  in  the  data 
fork  of  the  file,  the  returned  reference  number  corresponds  to  the  data  fork. 

permi ssi on 

The  permission  level  for  the  file  (see  below).  If  your  application  is  only  going  to 
play  the  movie  that  is  stored  in  the  file,  you  can  open  the  file  with  read 
permission.  If  you  plan  to  add  data  to  the  file  or  change  data  in  the  file,  you 
should  open  the  file  with  write  permission. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

permission  Constants 

fsCurPerm 

Whatever  permission  is  allowed, 
f sRdPerm 

Read  permission. 
fsWrPerm 

Write  permission, 
f sRdWrPerm 

Exclusive  read/ write  permission, 
f sRdWrShPerm 

Shared  read /write  permission. 

Discussion 

Your  application  must  open  a  movie  file  before  reading  movie  data  from  it  or 
writing  movie  data  to  it.  You  can  open  a  movie  file  more  than  once;  be  sure  to  call 
Cl  oseMovi  eFi  1  e  (1-102)  once  for  each  time  you  call  this  function.  Note  that  opening 
the  movie  file  with  write  permission  does  not  prevent  other  applications  from 
reading  data  from  the  movie  file. 

If  the  specified  file  has  a  resource  fork,  this  function  opens  the  resource  fork  and 
returns  a  file  reference  number  to  the  resource  fork.  If  the  movie  file  does  not  have 
a  resource  fork  (that  is,  it  is  a  single-fork  movie  file),  this  function  opens  the  data 
fork  instead.  In  this  case,  your  application  cannot  use  AddMovi  eResource  (1-36)  with 
the  movie  file. 

The  following  is  an  example  of  using  OpenMovieFile: 

//  OpenMovieFile  coding  example 

//  See  “Discovering  QuickTime,”  page  385 
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OpenMovieFile 


Movie  MyGetMovie  (void) 
{ 

OSErr 

SFTypeLi  st 
StandardFi 1 eReply 
Movi  e 
short 


nErr ; 

types  =  (Movi eFi 1 eType ,  0,  0,  0}  ; 
sf  r ; 

movie  =  NIL; 
n  F i 1 eRefNum; 


StandardGetFi 1 ePrevi ew( NI L,  1,  types,  &sfr); 
if  (sfr.sfGood)  { 

nErr  =  OpenMovi eFi 1 e(&sf r . sf Fi 1 e ,  &n F i 1 eRefNum,  fsRdPerm); 
if  (nErr  ==  noErr)  { 

short  nResID  =  0;  //We  want  the  first  movie. 

Str255  strName; 

Boolean  bWasChanged; 

nErr  =  NewMovi eFromFi 1 e(&movi e ,  nFileRefNum,  &nResID,  strName, 

newMovi eActi ve ,  &bWasChanged ) ; 

Cl  oseMovi eFi  1  e(nFi  1  eRefNum) ; 

} 

} 

return  movie; 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Movie  Functions"  (V-2713) 

Related  Java  Methods 

qui cktime . i o . OpenMovi eFi 1 e . as  Read ( ) , 
qui ckti me . i o . OpenMovi eFi 1 e . asWri te( ) 
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P 


ParseAIFFHeader 


Parses  out  the  header  in  an  AIFF  file. 

OSErr  ParseAIFFHeader  ( 
short 

SoundComponentData 
unsigned  long 
unsigned  long 

f Ref Num 

A  file  reference  number  for  an  AIFF  file, 
sndlnfo 

Pointer  to  a  SoundComponentData  (IV-2448)  structure  in  which  information  is 
returned. 

numFrames 

Returns  the  number  of  frames  of  data. 
dataOffset 

Returns  the  byte  offset  of  the  first  data  sample. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

Related  Java  Methods 

qu ickti me. sound. Sndlnfo. pa rseA IF FHeaderO 


f Ref Num , 
*sndInfo , 
*numFrames , 
*dataOffset  ) ; 


ParseSndHeader 


Returns  information  describing  the  audio  data  in  a  given  '  snd  '  resource  handle. 


OSErr  ParseSndHeader  ( 
SndLi stHandl e 
SoundComponentData 
unsigned  long 


sndHandl e , 
*sndInfo , 
*numFrames , 
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unsigned  long  *dataOffset  ); 

sndHandl e 

The  sound  handle  to  use. 
sndlnfo 

Pointer  to  a  SoundComponentData  (IV-2448)  structure  in  which  information  is 
returned. 
numFrames 

Returns  the  number  of  frames  of  audio  data  in  the  handle. 
dataOf f set 

Returns  the  byte  offset  of  the  first  audio  sample  in  the  handle. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

Related  Java  Methods 

qui ckti me . sound . SndHandl e . pa rseSndHeader( ) 


PasteHandlelntoMovie 


Takes  the  contents  of  a  specified  handle,  together  with  its  type,  and  pastes  it  into  a 
specified  movie. 

OSErr  PasteHandlelntoMovie  ( 

Handle  h, 

OSType  handleType, 

Movie  theMovie, 

long  flags, 

Componentlnstance  userComp  ); 


h 

The  handle  to  be  pasted  into  the  movie  indicated  by  the  theMovie  parameter, 
hand! eType 

The  data  type  of  the  handle  specified  in  the  h  parameter.  If  the  handle  is  set  to 
0,  the  function  searches  the  scrap  for  a  field  of  the  type  handleType.  If  both  the  h 
parameter  and  the  handleType  parameter  are  N I L,  the  function  uses  the  first 
available  data  from  the  scrap. 
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PasteHandlelntoMovie 


theMovi e 

The  destination  movie  for  this  operation.  Your  application  obtains  this  movie 
identifier  from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080), 
and  NewMovieFromHandl  e  (11-1084). 
fl  ags 

A  flag  (see  below)  that  can  further  refine  conditions  of  the  paste  operation. 
userComp 

The  component  or  an  instance  of  the  component  that  is  to  perform  the 
conversion  of  the  data  into  a  QuickTime  movie.  If  you  want  a  particular  movie 
import  component  to  perform  the  conversion,  you  may  pass  the  component  or 
an  instance  of  that  component.  Otherwise,  set  this  parameter  to  0  to  allow  the 
Movie  Toolbox  to  determine  the  appropriate  component.  If  you  pass  in  a 
component  instance,  this  function  uses  it.  This  allows  you  to  communicate 
directly  with  the  component  before  using  this  function  to  establish  any 
conversion  parameters.  If  you  pass  in  a  component  ID,  an  instance  is  created 
and  closed  within  this  function. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

flags  Constants 

pastelnParal 1  el 

Changes  the  function  so  that  it  takes  the  contents  of  the  specified  handle  along 
with  its  type  and  adds  (rather  than  inserts)  it  to  the  specified  movie  in  an 
operation  analogous  to  that  of  AddMovi  eSel  ecti  on  (1-38).  This  operation  does 
not  affect  the  duration  of  existing  tracks.  It  does  not  necessarily  create  a  new 
track;  rather,  it  uses  a  piece  of  an  existing  track,  if  possible. 

Discussion 

If  you  are  just  pasting  in  data  from  the  scrap,  it  is  best  to  allow  this  function  to 
retrieve  the  data  from  the  scrap,  rather  than  doing  it  yourself.  In  this  way,  the 
function  is  able  to  obtain  supplemental  data  from  the  scrap,  if  necessary  (for 
example,  '  sty  1 '  resources  for  ’  TEXT ' ).  This  function  can  paste  into  the  current 
selection  in  two  different  ways.  If  the  selection  is  empty  (for  example,  duration  =  0), 
it  adds  the  data  with  the  appropriate  duration.  If  the  selection  is  not  empty,  the  data 
is  added  and  then  scaled  to  fit  into  the  duration  of  the  selection.  The  current 
selection  is  deleted,  unless  you  set  the  pastelnParal  lei  flag. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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PasteMovieSelection 


Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "High-Level  Movie  Editing  Functions"  (V-2746) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . pasteHandl e( ) 


PasteMovieSelection 


Places  the  tracks  from  one  movie  into  another  movie. 

void  PasteMovieSelection  ( 

Movie  theMovie, 

Movie  src  ); 

theMovi e 

The  destination  movie  for  this  operation.  Your  application  obtains  this  movie 
identifier  from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080), 
and  NewMovi  eFromHandl  e  (11-1084). 

src 

The  source  movie  for  this  operation.  PasteMovieSelection  places  the  tracks 
from  this  movie  in  the  destination  movie. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

Whenever  possible,  the  Movie  Toolbox  uses  existing  tracks  to  store  the  data  to  be 
pasted.  Before  adding  a  track  to  the  destination  movie,  the  Toolbox  looks  in  the 
destination  movie  for  tracks  that  have  the  same  characteristics  as  the  tracks  in  the 
source  movie.  It  considers  several  characteristics  when  searching  for  an  appropriate 
track,  including  track  spatial  dimensions,  track  matrix,  track  clipping  region,  track 
matte,  alternate  group  affiliation,  media  time  scale,  media  type,  media  language, 
and  data  reference  (that  is,  the  two  tracks  must  refer  to  the  same  file).  If  the  Movie 
Toolbox  cannot  find  an  appropriate  track  in  the  destination  movie,  it  creates  a  track 
with  the  proper  characteristics.  It  removes  any  empty  tracks  from  the  destination 
movie  after  the  paste  operation. 

Special  Considerations 

If  you  have  assigned  a  progress  function  to  the  destination  movie,  the  Movie 
Toolbox  calls  that  progress  function  during  long  paste  operations. 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "High-Level  Movie  Editing  Functions"  (V-2746) 

Related  Java  Methods 

quicktime.std.movies.Movie.pasteSelectionO 


PlayMoviePreview 

Plays  a  movie's  preview. 

void  PlayMoviePreview  ( 

Movie  theMovie, 

Movi ePrevi ewCal lOutUPP  callOutProc, 

1 ong  refcon  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
cal  1 OutProc 

A  pointer  to  a  Movi  ePrevi  ewCal  1  OutProc  (III— 2105)  callback  in  your  application. 
The  Movie  Toolbox  calls  this  function  repeatedly  while  the  movie  preview  is 
playing.  You  can  use  this  function  to  stop  the  preview.  If  you  don't  want  to 
assign  a  function,  set  this  parameter  to  NIL. 

refcon 

A  reference  constant  that  the  Movie  Toolbox  passes  to  your  callback.  Use  this 
parameter  to  point  to  a  data  structure  containing  any  information  your  callback 
needs. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

This  function  sets  the  movie  into  preview  mode,  plays  the  movie  preview,  sets  the 
movie  back  to  normal  playback  mode,  and  returns  to  your  application.  The  Movie 
Toolbox  plays  the  preview  in  the  movie's  graphics  world.  Note  that  if  you  call  the 
GetMovi  eActi  veSegment  (1-457)  function  from  within  your  movie  callout  function, 
the  Movie  Toolbox  will  have  changed  the  active  movie  segment  to  be  the  preview 
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PrePrerollMovie 


segment  of  the  movie.  The  Movie  Toolbox  restores  the  active  segment  when  the 
preview  is  done  playing. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movl  es  .  h 

Programming  summary:  "Movie  Posters  and  Movie  Previews"  (V-2718) 

Related  Java  Methods 

qui cktime . std .movi es . Movi e . pi ayPrevi ew( ) 


PrePrerollMovie 


Sets  up  any  necessary  network  connections  to  receive  streaming  content. 

OSErr  PrePrerollMovie  ( 

Movi  e 

m. 

T i meVal ue 

ti  me , 

Fi  xed 

rate , 

Movi  ePrePrerol  1  Compl  etellPP 

proc , 

void 

*refcon  ); 

m 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

ti  me 

The  starting  time  of  the  movie  segment  to  play. 

rate 

The  rate  at  which  you  anticipate  playing  the  movie.  You  specify  the  movie  rate 
as  a  32-bit,  fixed-point  number.  Positive  integers  indicate  forward  rates  and 
negative  integers  indicate  reverse  rates. 

proc 

The  Movi  ePrePrerol  1  Compl  eteProc  (III— 2104)  callback  you  want  called  when 
pre-prerolling  is  complete.  If  a  completion  proc  is  specified,  PrePreroll  Movie 
operates  asynchronously.  You  must  call  Movi  esTask  periodically  during 
asynchronous  operation.  If  no  completion  proc  is  specified,  PrePrerollMovie 
operates  synchronously. 
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refcon 

A  reference  constant  that  is  passed  to  your  callback.  Use  this  parameter  to  point 
to  a  data  structure  containing  any  information  your  callback  needs. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

Before  a  movie  is  played,  it  is  normally  prerolled.  During  preroll,  the  Movie 
Toolbox  tells  the  appropriate  media  handlers  to  load  the  movie  data,  allocate  sound 
channels,  start  up  image-decompression  sequences,  and  so  on.  Before  a  movie  that 
contains  streaming  content  is  prerolled,  it  must  be  pre-prerolled.  This  sets  up  any 
necessary  network  connections  between  the  client  and  the  server.  If  a  movie 
contains  streaming  content  (one  or  more  '  strm'  tracks),  you  must  call  this  function 
before  calling  Prerol  1  Movi  e  (11-1142).  If  the  movie  does  not  contain  streaming 
content,  calling  this  function  has  no  effect.  If  your  application  calls  PrerollMovie,  it 
should  always  call  this  function  first.  If  you  play  movies  using  a  movie  controller, 
you  don't  need  to  preroll  or  pre-preroll  the  movie  explicitly;  it  is  done  for  you 
automatically.  If  a  completion  p roc  is  specified  in  the  proc  parameter,  this  function 
operates  asynchronously;  it  returns  almost  immediately  and  calls  the  completion 
proc  when  pre-prerolling  is  complete. 

Special  Considerations 

You  must  call  Movi  esTask  (11-973)  periodically  to  grant  time  for  pre-prerolling 
during  asynchronous  operation.  If  no  completion  proc  is  specified,  this  function 
operates  synchronously;  the  function  will  not  return  until  pre-prerolling  is 
complete.  This  can  take  a  long  time,  particularly  if  a  dial-up  network  connection 
must  be  established. 

Version  Notes 

Introduced  in  QuickTime  4.  Beginning  with  QuickTime  4,  your  application  should 
call  this  function  any  time  it  calls  Prerol  1  Movi  e  (11-1142). 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Enhancing  Movie  Playback  Performance"  (V-2722) 

Related  Java  Methods 

quicktime.std.movies.Movie.prePreroll ( ) 


PrerollMovie 


Prepares  a  portion  of  a  movie  for  playback. 
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OSErr  PrerollMovie  ( 

Movie  theMovie, 

TimeValue  time. 

Fixed  Rate  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi eFromHandl e  (11-1084). 

ti  me 

The  starting  time  of  the  movie  segment  to  play. 

Rate 

The  rate  at  which  you  anticipate  playing  the  movie.  You  specify  the  movie  rate 
as  a  32-bit,  fixed-point  number.  Positive  integers  indicate  forward  rates  and 
negative  integers  indicate  reverse  rates. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

When  your  application  calls  Prerol  1  Movi  e,  the  Movie  Toolbox  tells  the  appropriate 
media  handlers  to  prepare  to  play  the  movie.  The  media  handlers  may  then  load  the 
movie  data  and  perform  any  other  necessary  preparations  to  play  the  movie,  such 
as  allocating  sound  channels  and  starting  up  image-decompression  sequences.  In 
this  manner,  you  can  eliminate  playback  stutter  when  the  movie  starts  playing. 

If  your  application  uses  QuickTime's  Movie  Toolbox  to  play  back  movies,  there  are 
two  choices  for  how  to  preroll  the  movie.  Like  the  movie  controller,  the  Movie 
Toolbox  provides  a  single  function  call,  StartMovi  e  (III— 1911),  which  will  both 
preroll  the  movie  and  start  it  playing.  Unlike  the  movie  controller,  the  Movie 
Toolbox  function  doesn't  allow  you  to  specific  the  rate  to  play  the  movie  at,  but 
instead  assumes  the  movie's  preferred  rate. 

Calling  StartMovi  e,  just  like  the  movie  controller's  preroll  and  play  action,  first 
prerolls  the  movie  and  then  sets  it  playing.  If  your  application  requires  more 
control,  the  Movie  Toolbox  provides  lower  level  functions  that  give  you  more 
control: 

//  PrerollMovie  coding  example 
StartMovi e ( theMovi e) ; 

TimeValue  timeNow; 
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Fixed  playRate; 

timeNow  =  GetMovieTimettheMovie,  NIL); 
playRate  =  GetMoviePreferredRate(theMovie) ; 

Prerol 1 Movi e( theMovi e ,  timeNow,  playRate); 

SetMovieRatettheMovie,  playRate) ; 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Enhancing  Movie  Playback  Performance"  (V-2722) 

Related  Java  Methods 

qui cktime. std .movi es .Movi e . prerol  1  ( ) 


PreviewEvent 


May  be  called  as  appropriate  if  a  preview  component  handles  events. 

ComponentResul t  PreviewEvent  ( 
pnotComponent  p, 

EventRecord  *e. 

Boolean  *handl edEvent  ); 


P 

Specifies  your  preview  component.  You  obtain  this  identifier  from 
OpenComponent  (11-1130). 
e 

A  pointer  to  the  event  structure  for  this  operation, 
handl edEvent 

A  pointer  toaBoolean  value.  If  you  completely  handle  an  event  such  as  a 
mouse-down  event  or  keystroke,  you  should  set  the  handl  edEvent  parameter  to 
TRUE.  Otherwise,  set  it  to  FALSE. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Handling  Preview  Events"  (V-2872) 


PreviewMakePreview 


Creates  previews  by  allocating  a  handle  to  data  that  is  to  be  added  to  a  file. 

ComponentResul t  PreviewMakePreview  ( 
pnotComponent  p, 

OSType  *previ ewType , 

Handle  *previ ewResul t , 

const  FSSpec  *sourceFile, 

ICMProgressProcRecordPtr  progress  ); 


P 

Specifies  your  preview  component.  You  obtain  this  identifier  from 
OpenComponent  (11-1130). 
previ ewType 

A  pointer  to  the  type  of  preview  component  that  should  be  used  to  display  the 
preview. 

previ ewResul t 

A  pointer  to  a  handle  of  cached  preview  data  created  by  this  function. 
sourceFi 1 e 

A  pointer  to  a  reference  to  the  file  for  which  the  preview  is  created, 
progress 

A  pointer  to  an  ICMProgressProcRecord  (IV-2284)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 
Programming  summary:  "Creating  Previews"  (V-2873) 


PreviewMakePreviewReference 


Returns  the  type  and  identification  number  of  a  resource  within  a  file  to  be  used  as 
the  preview  for  a  file. 
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ComponentResul t  P 
pnotComponent 
OSType 
short 

const  FSSpec 


revi ewMakePrevi ewReference 
P. 

*previ ewType , 

*resID, 

*sourceFi 1 e  ) ; 


( 


P 

Specifies  your  preview  component.  You  obtain  this  identifier  from 
OpenComponent  (11-1130). 
previ ewType 

A  pointer  to  the  type  of  preview  component  that  should  be  used  to  display  the 
preview. 
resID 

A  pointer  to  the  identification  number  of  a  resource  within  the  file  to  be  used 
as  the  preview  for  the  file. 

sourceFi 1 e 

A  pointer  to  an  FSSpec  (IV-2262)  structure  that  provides  a  reference  to  the  file 
for  which  the  preview  is  created. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 
Programming  summary:  "Creating  Previews"  (V-2873) 


PreviewShowData 


Displays  a  preview  if  it  does  not  handle  events. 


ComponentResul t  Previ 
pnotComponent 
OSType 
Handl e 
const  Rect 


ewShowData 

P. 

dataType , 
data , 

*inhlere  ); 


( 


Specifies  your  preview  component.  You  obtain  this  identifier  from 
OpenComponent  (11-1130). 
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dataType 

The  type  of  handle  pointing  to  the  data  to  be  displayed  in  the  preview. 

data 

A  handle  to  the  data,  which  is  typically  the  same  as  the  subtype  of  your 
preview  component. 

i nHere 

A  pointer  to  a  Rect  (IV-2399)  structure  that  defines  the  area  into  which  you 
draw  the  preview.  The  current  port  is  set  to  the  correct  graphics  port  for 
drawing.  You  must  not  draw  outside  the  given  rectangle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Displaying  Previews"  (V-2872) 


PtlnDSequenceData 


Tests  to  see  if  a  compressed  image  contains  data  at  a  a  given  point. 

OSErr  PtlnDSequenceData  ( 

ImageSequence  seqlD, 
void  *data. 

Size  dataSize, 

Point  where. 

Boolean  *hit  ); 

seqlD 

The  unique  sequence  identifier  that  was  returned  by  the 
DecompressSequenceBegi  n  (1-238)  function. 

data 

Pointer  to  compressed  data  in  the  format  specified  by  the  desc  param. 
dataSi ze 

Size  of  the  compressed  data  referred  to  by  the  data  param. 
where 

A  QuickDraw  Point  (IV-2339)  structure  of  value  (0,0),  based  at  the  top-left 
comer  of  the  image. 
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hi  t 

A  pointer  to  a  field  to  receive  the  Boolean  indicating  whether  or  not  the  image 
contained  data  at  the  specified  point.  The  Boolean  will  be  set  to  T  RU  E  if  the  point 
specified  by  the  where  parameter  is  contained  within  the  compressed  image 
data  specified  by  the  data  para m,  or  FALSE  if  the  specified  point  falls  within  a 
blank  portion  of  the  image. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

PtlnDSequenceData  allows  the  application  to  perform  hit  testing  on  compressed 
data. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Changing  Sequence-Decompression  Parameters" 
(V-2795) 

Related  Java  Methods 

qui cktime. std . image. DSequence. ptlnData ( ) 


PtlnMovie 


Determines  whether  a  specified  point  lies  in  the  region  defined  by  a  movie's  final 
display  boundary  region  after  it  has  been  clipped  by  the  movie's  display  clipping 
region. 

Boolean  PtlnMovie  ( 

Movie  theMovie, 

Poi nt  pt  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovieFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

pt 

The  point  to  be  checked.  This  point  must  be  expressed  in  the  movie's  local 
display  coordinate  system. 

function  result  Returns  TRUE  if  the  point  is  in  the  movie. 
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Discussion 

This  function  is  accurate  at  the  current  movie  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Movies  and  Your  Event  Loop"  (V-2720) 

Related  Java  Methods 

qui cktime . std .movi es . Movi e . poi ntlnMovi e( ) 


PtlnTrack 


Determines  whether  a  specified  point  lies  in  the  region  defined  by  a  track's  display 
boundary  region  after  it  has  been  clipped  by  the  movie's  final  display  clipping 
region. 

Boolean  PtlnTrack  ( 

Track  theTrack, 

Point  pt  ); 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 
pt 

The  point  to  be  checked.  This  point  must  be  expressed  in  the  local  display 
coordinate  system  of  the  movie  that  contains  the  track. 

function  result  Returns  TRUE  if  the  point  lies  in  the  track's  display  space. 

Discussion 

This  function  is  accurate  at  the  current  movie  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Movies  and  Your  Event  Loop"  (V-2720) 

Related  Java  Methods 

qui cktime . std .movi es .Track. poi ntlnMovi e( ) 
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PutMovielntoDataFork 


Stores  a  movie  in  the  data  fork  of  a  given  file. 

OSErr  PutMovielntoDataFork  ( 

Movie  theMovie, 

short  fRefNum, 

long  offset, 

1 ong  maxSi ze  ) ; 

theMovi e 

The  movie  to  be  stored  in  the  data  fork  of  an  atom.  Your  application  obtains  this 
movie  identifier  from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e 
(11-1080),  and  NewMovi  eFromHandl  e  (11-1084). 
fRefNum 

A  file  reference  number  for  the  data  fork  of  the  given  file.  You  pass  in  an  open 
write  path  in  the  fRefNum  parameter. 

offset 

Indicates  where  the  movie  should  be  written. 
maxSi ze 

The  largest  number  of  bytes  that  may  be  written. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Saving  Movies"  (V-2715) 

Related  Java  Methods 

quicktime.std.movies.Movie.putlntoDataForkO 


PutMovieIntoDataFork64 


Provides  a  64-bit  version  of  PutMovielntoDataFork  (II— 1 150) . 

OSErr  PutMovi eIntoDataFork64  ( 

Movie  theMovie, 

long  fRefNum, 
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const  wide  *offset, 

unsigned  long  maxSize  ); 

theMovi e 

A  movie  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e 
(11-1084). 
f Ref Num 

A  file  reference  number  for  the  data  fork  of  the  given  file.  You  pass  in  an  open 
write  path  in  the  f  Ref  Num  parameter, 
offset 

Pointer  to  a  64-bit  value  that  indicates  where  the  movie  should  be  written. 
maxSi ze 

The  largest  number  of  bytes  that  may  be  written. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movl  es  .  h 


PutMovielntoHandle 


Creates  a  new  movie  resource. 

OSErr  PutMovielntoHandle  ( 

Movie  theMovie, 

Handle  publicMovie  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

publ i cMovi e 

The  handle  that  is  to  receive  the  new  movie  resource.  The  function  resizes  the 
handle  if  necessary. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
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(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

Use  this  handle  to  store  a  QuickTime  movie  in  a  specialized  storage  format. 

Special  Considerations 

Note  that  you  cannot  use  this  new  movie  with  other  Movie  Toolbox  functions, 
except  for  NewMovi eFromHandl  e  (11-1084). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Saving  Movies"  (V-2715) 

Related  Java  Methods 

qui cktime. std .movi es .Movi e. put IntoHandl  e( ) 


See  Also 

Use  NewMovi  eFromHandl  e  (11-1084)  to  load  a  movie  from  a  handle. 


PutMo  vielntoT  ypedHandle 


Takes  a  movie,  or  a  single  track  from  within  that  movie,  and  converts  it  into  a 
handle  of  a  specified  type. 


OSErr  PutMovielntoTypedHandle  ( 


Movi  e 
T  rack 
OSType 
Handl e 
TimeVal ue 
TimeVal ue 
1  ong 

Componentlnstance 


theMovi e , 
targetTrack, 
handl eType , 
publ i cMovi e , 
start , 
dur , 
fl ags , 
userComp  ) ; 


theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

targetTrack 

The  track  to  convert. 


11-1152 


Inside  QuickTime:  Function  l-Q 


PutMovieOnScrap 


handl eType 

The  type  of  the  new  data, 
publ i cMovi e 

The  actual  handle  in  which  to  place  the  new  data, 
start 

The  start  time  of  the  segment  of  the  movie  or  track  to  be  converted. 

dur 

The  duration  of  the  segment  of  the  movie  or  track  to  be  converted, 
fl  ags 

Condition  of  the  conversion.  Set  this  parameter  to  0. 
userComp 

Indicates  a  component  or  component  instance  of  the  movie  export  component 
you  want  to  perform  the  conversion.  Otherwise,  set  this  parameter  to  0  for  the 
Movie  Toolbox  to  choose  the  appropriate  component.  If  you  pass  in  a 
component  instance,  this  function  will  use  it.  This  allows  you  to  communicate 
directly  with  the  component  before  using  this  function  to  establish  any 
conversion  parameters.  If  you  pass  in  a  component  ID,  an  instance  is  created 
and  closed  within  this  function. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "High-Level  Movie  Editing  Functions"  (V-2746) 

Related  Java  Methods 

qui cktime . std .movi es . Movi e . putlntoTypedHandl  e( ) 


PutMovieOnScrap 


Places  a  movie  into  the  Macintosh  scrap. 

OSErr  PutMovieOnScrap  ( 

Movie  theMovie, 

long  movi eScrapFl ags  ); 


Inside  QuickTime:  Function  l-Q 


11-1153 


PutUserDatalntoHandle 


theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
movi eScrapFl ags 

Flags  (see  below)  that  control  the  operation.  Be  sure  to  set  unused  flags  to  0. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

movieScrapFlags  Constants 

movieScrapDontZeroScrap 

Controls  whether  the  Movie  Toolbox  clears  the  scrap  before  putting  the  movie 
on  the  scrap.  If  you  set  this  flag  to  1,  the  Movie  Toolbox  does  not  clear  the  scrap 
before  placing  your  movie  onto  this  scrap,  thus  adding  your  movie  to  the 
previous  contents  of  the  scrap.  If  you  set  this  flag  to  0,  the  function  clears  the 
scrap,  then  places  your  movie  on  the  scrap. 
movieScrapOnlyPutMovie 

Controls  whether  the  Movie  Toolbox  places  other  items  on  the  scrap  along  with 
your  movie.  If  you  set  this  flag  to  1,  the  Movie  Toolbox  only  places  your  movie 
on  the  scrap.  If  you  set  this  flag  to  0,  the  Movie  Toolbox  places  an  image  from 
the  current  movie  time  (including  but  not  limited  to  a  PICT)  on  the  scrap  along 
with  your  movie.  The  picture  is  intended  for  use  by  applications  that  cannot 
work  with  movies. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi es .  h 

Programming  summary:  "High-Level  Movie  Editing  Functions"  (V-2746) 

Related  Java  Methods 

qui ckti me. std .movi es .Movi e . put0nScrap( ) 


PutUserDatalntoHandle 


Takes  a  specified  user  data  structure  and  replaces  the  contents  of  the  handle  with  a 
publicly  parsable  form  of  the  user  data. 

OSErr  PutUserDatalntoHandle  ( 

UserData  theUserData, 


11-1154 


Inside  QuickTime:  Function  l-Q 


QTBandwidthRelease 


Handle  h  ); 

theUserData 

The  user  data  structure  that  is  to  be  disposed  of. 
h 

A  handle  to  the  user  data  structure  specified  in  the  theUserData  parameter. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  User  Data"  (V-2743) 

Related  Java  Methods 

qui  cktime .  std  .movi  es  .medi  a.UserData.putlntoHandleO 


QTBandwidthRelease 


Undocumented 

OSErr  QTBandwidthRelease  ( 

QTBandwi dthReference  bwRef, 

long  flags  ); 

bwRef 

Undocumented 
fl  ags 

Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 


Inside  QuickTime:  Function  l-Q 


11-1155 


QTBandwidthRequest 


flags  Constants 

Undocumented 

Undocumented 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es .  h 


QTBandwidthRequest 


Undocumented 


OSErr  QTBandwidthRequest  ( 

1  ong 

QTBandwidthNotificationUPP 
const  void 

QTBandwidth Reference 
1  ong 


pri  ori  ty , 
cal  1  back , 
*refcon , 
*bwRef , 
f 1 ags  ) ; 


priori  ty 

Undocumented 
cal  1  back 

A  QTBandwi  dthNoti f i cati onProc  (III — 2124)  callback, 
refcon 

A  reference  constant  to  be  passed  to  your  callback.  Use  this  parameter  to  point 
to  a  data  structure  containing  any  information  your  function  needs. 
bwRef 

Undocumented 
fl  ags 

Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

flags  Constants 

Undocumented 

Undocumented 


Version  Notes 

Introduced  in  QuickTime  4. 


11-1156 


Inside  QuickTime:  Function  l-Q 


QTBandwidthRequestForTimeBase 


Programming  Info 

C  interface  file:  Movi  es  .  h 


QTBandwidthRequestForTimeBase 


Undocumented 

OSErr  QTBandwidthRequestForTimeBase  ( 


Ti meBase  tb , 

long  priority, 

QTBandwi dthNoti f i cati onUPP  cal  1  back, 
const  void  *refcon, 

QTBandwi dthReference  *bwRef, 

long  flags  ); 


tb 

A  time  base.  Your  application  obtains  this  time  base  identifier  from  NewT  i  meBase 
(11-1119). 

pri ori ty 

Undocumented 
cal  1  back 

A  QTBandwi  dthNoti  f  i  cati  onProc  (III — 2124)  callback, 
ref con 

A  reference  constant  to  be  passed  to  your  callback.  Use  this  parameter  to  point 
to  a  data  structure  containing  any  information  your  function  needs. 

bwRef 

Undocumented 
fl  ags 

Flags  (see  below). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

flags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  4.1. 


Inside  QuickTime:  Function  l-Q 


11-1157 


QTCopyAtom 


Programming  Info 

C  interface  file:  Movi  es .  h 


QTCopyAtom 


Copies  an  atom  and  its  children  to  a  new  atom  container. 

OSErr  QTCopyAtom  ( 

QTAtomContai ner 
QTAtom 

QTAtomContai ner 
contai ner 

The  atom  container  that  contains  the  atom  to  be  copied. 

atom 

The  atom  to  be  copied.  To  duplicate  the  entire  container,  pass  a  value  of 
kParentAtomlsContai ner  for  the  atom  parameter. 

targetContai ner 

A  pointer  to  an  uninitialized  atom  container  data  structure.  On  return,  this 
parameter  points  to  an  atom  container  that  contains  a  copy  of  the  atom. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

The  caller  is  responsible  for  disposing  of  the  new  atom  container  by  calling 
QTDi sposeAtomContai ner  (11-1164). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Copying  Existing  Atoms"  (V-2767) 

Related  Java  Methods 

qui ckti me . std .movi es . AtomContai ner . copyAtomt ) 


contai ner , 
atom , 

*targetContai ner  ) ; 


QTCopyAtomDataT  oHandle 

Copies  the  specified  leaf  atom's  data  to  a  handle. 


11-1158 


Inside  QuickTime:  Function  l-Q 


QTCopyAtomDataToPtr 


OSErr  QTCopyAtomDataToHandl e  ( 
QTAtomContai ner  container, 

QTAtom  atom. 

Handle  targetHandle  ); 


contai ner 

The  atom  container  that  contains  the  leaf  atom. 


atom 

The  leaf  atom  whose  data  should  be  copied. 
targetHandl e 

A  handle.  On  return,  the  handle  contains  the  atom's  data.  The  handle  must  not 
be  locked.  This  function  resizes  the  handle,  if  necessary. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

You  call  this  function,  passing  an  initialized  handle,  to  retrieve  a  copy  of  a  leaf 
atom's  data. 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Retrieving  Atoms  and  Atom  Data"  (V-2768) 

Related  Java  Methods 

qui cktime . std .movi es . AtomContai ner . copyAtomDataToHandl e( ) 


QTCopyAtomDataToPtr 


Copies  the  specified  leaf  atom's  data  to  a  buffer. 


OSErr  QTCopyAtomDataToPtr  ( 


QTAtomContai ner 

QTAtom 

Bool ean 

1  ong 

voi  d 

1  ong 


contai ner , 
atom, 

si zeOrLessOK, 
size, 

*targetPtr, 
*actualSize  ); 


Inside  QuickTime:  Function  l-Q 


11-1159 


QTCountChildrenOf  Type 


contai ner 

The  atom  container  that  contains  the  leaf  atom. 

atom 

The  leaf  atom  whose  data  should  be  copied, 
si zeOrLessOK 

Specifies  whether  the  function  may  copy  fewer  bytes  than  the  number  of  bytes 
specified  by  the  size  parameter.  The  buffer  may  be  larger  than  the  amount  of 
atom  data  if  you  set  the  value  of  this  parameter  to  TRUE.  You  can  determine  the 
size  of  an  atom's  data  by  calling  QTGetAtomDataPtr  (11-1171). 

si  ze 

The  length,  in  bytes,  of  the  buffer  pointed  to  by  the  ta  rgetPtr  parameter. 
targetPtr 

A  pointer  to  a  buffer.  On  return,  the  buffer  contains  the  atom  data, 
actual  Si ze 

A  pointer  to  a  long  integer  which,  on  return,  contains  the  number  of  bytes 
copied  to  the  buffer. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

You  call  this  function,  passing  a  data  buffer,  to  retrieve  a  copy  of  a  leaf  atom's  data. 
The  buffer  must  be  large  enough  to  contain  the  atom's  data. 

Special  Considerations 

This  function  may  move  memory. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Retrieving  Atoms  and  Atom  Data"  (V-2768) 

Related  Java  Methods 

qui ckti me . std .movi es . AtomContai ner . copyAtomDataToPtr ( ) 


QTCountChildrenOfType 

Returns  the  number  of  atoms  of  a  given  type  in  the  child  list  of  the  specified  parent 
atom. 


11-1160 


Inside  QuickTime:  Function  l-Q 


QTCreateStandardParameterDialog 


short  QTCountChi 1 drenOfType  ( 

QTAtomContai ner  container, 

QTAtom  parentAtom, 

QTAtomType  childType  ); 

contai ner 

The  atom  container  that  contains  the  parent  atom. 
parentAtom 

The  parent  atom  for  this  operation, 
chi  1 dType 

The  atom  type  for  this  operation.  To  retrieve  the  total  number  of  atoms  in  the 
child  list,  set  this  parameter  to  0. 

function  result  The  number  of  atoms  of  a  given  type  in  the  child  list  of  the  specified 
parent  atom. 

Discussion 

You  can  call  this  function  to  determine  the  number  of  atoms  of  a  specified  type  in  a 
parent  atom's  child  list.  If  the  total  number  of  atoms  in  the  parent  atom's  child  list 
is  0,  the  parent  atom  is  a  leaf  atom. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Retrieving  Atoms  and  Atom  Data"  (V-2768) 

Related  Java  Methods 

qui cktime . std .movi es . AtomContai ner.countChildrenOfTypeO 


QTCreateStandardParameterDialog 

Creates  a  dialog  box  that  allows  the  user  to  choose  an  effect  from  the  list  of  effects 
passed  to  the  function. 

OSErr  QTCreateStandardParameterDi al og  ( 

QTAtomContai ner  effectList, 

QTAtomContai ner  parameters, 

QTParameterDi al ogOpti ons  di al ogOpti ons , 

QTParameterDi al og  *createdDi al og  ); 


Inside  QuickTime:  Function  l-Q 


11-1161 


QTCreateStandardParameterDialog 


effectLi st 

A  list  of  the  effects  that  the  user  can  choose  from.  In  most  cases  you  should  call 
QTGet  Effects  Li  st  (11-1174)  to  generate  this  list.  If  you  pass  NI L  in  this 
parameter,  the  function  calls  QTGetEffectsListto  retrieve  the  list  of  all 
currently  installed  effects;  this  list  is  then  presented  to  the  user, 
parameters 

An  effect  description  containing  the  default  parameter  values  for  the  effect.  If 
the  effect  named  in  the  parameter  description  is  in  effectlist,  that  effect  is 
displayed  when  the  dialog  is  first  shown  and  its  parameter  values  are  set  from 
the  parameter  description.  Pass  in  an  empty  atom  container  to  have  the  dialog 
box  display  the  first  effect  in  the  list,  set  to  its  default  parameters.  On  return, 
this  atom  container  holds  an  effect  description  for  the  effect  selected  by  the 
user,  including  the  parameter  settings.  This  effect  description  can  then  be 
added  to  the  media  of  an  effect  track.  You  will  need  to  add  source  atoms  to  this 
container  for  effects  that  require  sources. 

di al ogOpti ons 

Options  (see  below)  that  control  the  behavior  of  the  dialog. 
createdDi al og 

Returns  a  reference  to  the  dialog  box  that  is  created  by  this  function.  You  should 
pass  this  value  only  to  QTIsStandardParameterDi  al  ogEvent  (11-1186)  and 
QTDi  smi  ssStandardParameterDi  al  og  (11-1163). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

dialogOptions  Constants 

pdOptionsCollectOneValue 

Only  one  value  can  be  entered  for  parameters  that  are  optionally  tweenable. 
This  means  that  optionally-tweened  parameters  will  not  be  tweened. 

pdOptionsAll owOpti onal Interpol  at ions 

The  user  interface  for  optionally-tweened  parameters  will  be  constructed  to 
take  tweened  values.  Setting  this  flag  selects  the  "advanced"  user  interface 
mode.  If  the  user  interface  supports  this  mode  of  operation,  then  a  tween  value 
can  be  entered  for  this  parameter  when  the  user  interface  is  in  the  mode.  An 
example  of  an  advanced  mode  is  the  standard  parameters  dialog  box;  if  you 
hold  down  the  option  key  while  selecting  an  effect,  any  parameters  that  have 
the  kAtom  Interpol  a  te  Is  Opt  i  onal  flag  set  will  allow  a  tween  value  to  be  entered. 


11-1162 


Inside  QuickTime:  Function  l-Q 


QTDismissStandardParameterDialog 


Discussion 

This  function  creates  and  displays  a  standard  parameter  dialog  box  that  allows  the 
user  to  choose  an  effect  from  the  list  in  the  effectin'  st  parameter.  The  dialog  box 
also  allows  the  user  to  choose  values  for  the  parameters  of  the  effect,  to  preview  the 
effects  as  they  choose  and  customize  them,  and  to  get  more  information  about  each 
effect.  Your  application  must  call  the  Mac  OS  function  Wai tNextEvent  and 
QTIsStandardParameterDi  al  ogEvent  (11-1186)  to  allow  the  user  to  interact  with  the 
dialog  box  that  is  shown.  Note  that  the  dialog  box  will  remain  hidden  until  the  first 
event  is  processed  by  QTIsStandardParameterDi  al  ogEvent.  At  this  point,  the  dialog 
box  will  be  displayed.  You  can  modify  the  default  behavior  of  the  dialog  box  that  is 
created  by  calling  QTStandardParameterDi  al  ogDoActi  on  (11-1313). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "High-Level  Effects  Functions"  (V-2897) 

Related  Java  Methods 

qui cktime . std .movi es . ParameterDi al og . showParameterDi a  1 og ( ) 


QTDismissStandardParameterDialog 

Closes  a  standard  parameter  dialog  box  that  was  created  using 
QTCreateStandardParameterDi  al  og  (11-1161). 

OSErr  QTDi smi ssStandardParameterDi  al  og  ( 

QTParameterDi al og  createdDi al og  ); 

createdDi al og 

The  reference  to  the  standard  parameters  dialog  box  that  is  returned  by 
QTCreateStandardParameterDi  al  og  (11-1161). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

This  function  disposes  of  all  memory  associated  with  the  dialog  box. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Function  l-Q 


11-1163 


QTDisposeAtomContainer 


Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "High-Level  Effects  Functions"  (V-2897) 

Related  Java  Methods 

quicktime.std.movies.ParameterDialog.showParameterDialogO 


QTDisposeAtomContainer 

Disposes  of  an  atom  container. 

OSErr  QTDisposeAtomContainer  ( 

QTAtomContai ner  atomData  ); 

atomData 

The  atom  container  to  be  disposed  of. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

You  can  call  this  function  to  dispose  of  an  atom  container  data  structure  that  was 
created  by  QTNewAtomContai  ner  (11-1203)  or  QTCopyAtom  (11-1158). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Creating  and  Disposing  of  Atom  Containers"  (V-2766) 


QTDisposeTween 


Disposes  of  a  tween  component  instance. 

OSErr  QTDisposeTween  ( 

QTTweener  tween  ) ; 


tween 

The  tween  to  be  disposed  of. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 


11-1164 


Inside  QuickTime:  Function  l-Q 


QTDoTween 


result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


QTDoTween 


Runs  a  tween  component. 

OSErr  QTDoTween  ( 

QTTweener 
TimeVal  lie 
Handl e 
1  ong 

TweenerDatallPP 
void 

tween 

The  tween  to  be  run. 
atT i me 

A  value  that  defines  the  time  to  run  the  tween, 
resul t 

A  handle  to  the  result  of  the  tweening  operation, 
resul tSi ze 

A  pointer  to  the  size  of  the  result. 
tweenDataProc 

A  Universal  Procedure  Pointer  that  accesses  a  TweenerDataProc  (III— 2153) 
callback. 
tweenDataRefCon 

A  pointer  to  a  reference  constant  to  be  passed  to  your  callback.  Use  this  constant 
to  point  to  a  data  structure  containing  any  information  your  function  needs. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 


tween , 
atTime, 
resul t , 

*resul tSi ze , 
tweenDataProc, 
*tweenDataRefCon  ); 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Movi  es .  h 

QTFindChildBylD 

Retrieves  an  atom  by  ID  from  the  child  list  of  the  specified  parent  atom. 

QTAtom  QTFindChildBylD  ( 

QTAtomContai ner  container, 

QTAtom  parentAtom, 

QTAtomType  atomType, 

QTAtomID  id, 

short  *i ndex  ) ; 

contai ner 

The  atom  container  that  contains  the  parent  atom. 
parentAtom 

The  parent  atom  for  this  operation. 
atomType 

The  type  of  the  atom  to  be  retrieved, 
i  d 

The  ID  of  the  atom  to  be  retrieved, 
i  ndex 

A  pointer  to  an  uninitialized  short  integer.  On  return,  if  the  atom  specified  by 
the  i  d  parameter  was  found,  the  integer  contains  the  atom's  index.  If  you  don't 
want  this  function  to  return  the  atom's  index,  set  the  value  of  the  index 
parameter  to  NIL. 

function  result  The  found  atom. 

Discussion 

You  call  this  function  to  search  for  and  retrieve  an  atom  by  its  type  and  ID  from  a 
parent  atom's  child  list.  The  following  code  shows  how  you  can  use  this  function  to 
insert  a  copy  of  container  B's  atoms  as  children  of  the  '  abed '  atom  in  container  A: 

//  QTFindChildBylD  coding  example 
QTAtom  targetAtom; 

targetAtom  =  QTFindChildBylD  (containerA,  kParentAtomlsContainer ,  'abed', 
1000,  NIL); 

FailOSErr  (QTInsertChi 1 dren  (containerA,  targetAtom,  contai nerB )) ; 
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QTFindChildBylndex 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Retrieving  Atoms  and  Atom  Data"  (V-2768) 

Related  Java  Methods 

qui cktime . std .movi es . AtomContai ner . f i ndChi 1 dBy ID_Atom( ) , 
qui cktime . std .movi es .AtomContai ner . f i ndChi 1 dBy ID„i ndex( ) 


QTFindChildBylndex 


Retrieves  an  atom  by  index  from  the  child  list  of  the  specified  parent  atom. 

QTAtom  QTFindChildBylndex  ( 

QTAtomContai ner  container, 

QTAtom  parentAtom, 

QTAtomType  atomType, 

short  index, 

QTAtomID  *id  ); 

contai ner 

The  atom  container  that  contains  the  parent  atom. 
parentAtom 

The  parent  atom  for  this  operation. 
atomType 

The  type  of  the  atom  to  be  retrieved, 
i  ndex 

The  index  of  the  atom  to  be  retrieved. 


i  d 

A  pointer  to  an  uninitialized  QTAtomID  data  structure.  On  return,  if  the  atom 
specified  by  index  was  found,  the  QTAtomID  data  structure  contains  the  atom's 
ID.  If  you  don't  want  this  function  to  return  the  atom's  ID,  set  the  value  of  the 
i d  parameter  to  NIL. 

function  result  The  found  atom. 

Discussion 

You  call  this  function  to  search  for  and  retrieve  an  atom  by  its  type  and  index  within 
that  type  from  a  parent  atom's  child  list.  The  following  code  illustrates  one  way  to 
use  it: 
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//  QTFi ndChi 1 dBy Index  coding  example 

if  ( ( propertyAtom  =  QTFi ndChi 1 dBy Index  (sprite,  kParentAtomlsContainer , 
kSpri teProperty Imagelndex ,  1,  NIL))  ==  0) 

FailOSErr  ( QTInsertChi 1 d  (sprite,  kParentAtomlsContainer, 

kSpri teProperty Imagelndex ,  1,  1,  si zeof( short ), &i magelndex , 
NIL)) ; 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Retrieving  Atoms  and  Atom  Data"  (V-2768) 

Related  Java  Methods 

qui ckti me . std .movi es . AtomContai ner . f i ndChi 1 dBy Index_Atom( ) , 
qui ckti me . std .movi  es .AtomContai ner . fi ndChi 1 dBy Index_i d( ) 


QTGetAccessKeys 


Returns  all  the  application  and  system  access  keys  of  a  specified  access  key  type. 

OSErr  QTGetAccessKeys  ( 

Str255  accessKeyType , 

long  flags, 

QTAtomContai ner  *keys  ); 

accessKeyType 

The  type  of  access  keys  to  return, 
fl  ags 

Unused;  must  be  set  to  0. 

keys 

A  pointer  to  a  QT  atom  container  that  contains  atoms  of  type 
kAccessKeyAtomType  at  the  top  level.  These  atoms  contain  the  keys.  If  there  are 
no  access  keys  of  the  specified  type,  the  function  returns  an  empty  QT  atom 
container. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 
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QTGetAliasInfo 


Discussion 

In  the  QT  atom  container,  application  keys,  which  are  more  likely  to  be  the  ones  an 
application  needs,  appear  before  system  keys.  You  can  get  the  key  values  by  using 
QT  atom  functions. 

Special  Considerations 

When  your  application  is  done  with  the  QT  atom  container,  it  must  dispose  of  it  by 
calling  QTDi sposeAtomContai ner  (11-1164). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Retrieving  Access  Keys"  (V-2771) 


QTGetAliasInfo 


Retrieves  information  from  an  alias  record  without  actually  resolving  the  alias. 
OSErr  QTGetAliasInfo  ( 


A1 i asHandl e 

alias. 

A1  i asInfoType 

i  ndex. 

char 

*outBuf , 

1  ong 

buf Len , 

1  ong 

*outLen 

unsigned  long 

flags  ) ; 

alias 

A  handle  to  an  A1  i  asRecord  (IV-2159)  structure, 
i  ndex 

The  kind  of  information  to  be  retrieved.  If  a  positive  integer  is  passed,  the 
function  retrieves  the  name  of  the  parent  directory  that  many  levels  above  the 
alias.  If  the  integer  is  greater  than  the  number  of  levels  to  the  root  directory,  an 
empty  string  is  returned.  You  can  also  pass  a  constant  (see  below). 

outBuf 

A  pointer  to  a  buffer  to  hold  the  returned  C  string.  This  function  returns  strings 
of  potentially  unlimited  length.  If  you  pass  N I L  here,  or  set  b  u  f  L  e  n  too  short,  the 
function  will  return  an  error  and  write  the  actual  length  needed  to  outLen.  So 
you  can  make  one  call  to  this  function,  passing  N I L,  then  allocate  the  buffer  and 
call  it  again  with  the  correct  length. 
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QTGetAliasInfo 


buf Len 

The  length  of  the  actual  output  buffer. 
outLen 

The  required  output  buffer  length,  including  any  trailing  null  character, 
fl  ags 

Reserved;  set  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

index  Constants 

asi  ZoneName 

The  name  of  the  zone  containing  the  target  of  the  alias.  This  selector  will  will 
always  return  an  empty  string  on  the  Windows  platform, 
asi ServerName 

The  name  of  the  server  containing  the  target.  This  will  will  always  return  an 
empty  string  in  the  usual  case  of  a  drive-letter  based  path.  But  sometimes  these 
aliases  refer  to  paths  such  as  Wwww.mypage .  com\dropboxes\Bob 
JonesXsampl  e  .mov,  instead  of  a  drive-letter  based  path.  In  those  cases, 
asi  ServerName  will  return  www.mypage .  com  and  asi  Vol  umeName  will  return 
dropboxes. 

asi Vol umeName 

The  name  of  the  volume  containing  the  target, 
asi A1 i asName 

The  name  of  the  target, 
asi ParentName 

The  name  of  the  parent  directory  of  the  target.  If  the  target  is  a  volume,  return 
the  volume  name. 

Discussion 

This  function  is  used  to  retrieve  the  name  of  the  target,  the  names  of  the  target's 
parent  directories,  the  name  of  the  target's  volume,  or  its  zone  or  server  name. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  QTML.h 

See  Also 

See  GetAl  i  as  Info  in  Inside  Macintosh:  Files  (listed  in  the  bibliography). 
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QTGetAtomDataPtr 


Retrieves  a  pointer  to  the  atom  data  for  a  specified  leaf  atom. 

OSErr  QTGetAtomDataPtr  ( 

QTAtomContai ner  container, 

QTAtom  atom, 

long  *dataSize, 

Ptr  *atomData  ); 

contai ner 

The  atom  container  that  contains  the  leaf  atom. 

atom 

The  leaf  atom  whose  data  should  be  retrieved. 
dataSi ze 

On  return,  contains  a  pointer  to  the  length,  in  bytes,  of  the  leaf  atom's  data. 
atomData 

On  return,  contains  a  pointer  to  the  leaf  atom's  data. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

You  call  this  function  in  retrieve  a  pointer  to  a  leaf  atom's  data  so  that  you  can  access 
the  data  directly. 

Special  Considerations 

To  ensure  that  the  pointer  returned  in  the  atomData  parameter  will  remain  valid  if 
memory  is  moved,  you  should  call  QTLockContai  ner  (11-1187)  before  you  call  this 
function.  If  you  call  QTLockContai  ner,  you  should  call  QTUnl  ockContai  ner  (11-1316) 
when  you  have  finished  using  the  atomData  pointer.  If  you  pass  a  locked  atom 
container  to  a  function  that  resizes  atom  containers,  the  function  returns  an  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Retrieving  Atoms  and  Atom  Data"  (V-2768) 

Related  Java  Methods 

qui cktime . std .movi es . AtomContai ner . get AtomData ( ) 
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QTGetAtomParent 

Gets  the  parent  of  a  QT  atom. 

QTAtom  QTGetAtomParent  ( 

QTAtomContai ner  container, 

QTAtom  chi  1 dAtom  ) ; 

contai ner 

A  QT  atom  container, 
chi  1 dAtom 

A  QT  child  atom  in  the  container. 
function  result  On  return,  the  parent  of  the  child  atom. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es .  h 


QTGet  AtomT  ype  AndID 


Retrieves  an  atom's  type  and  ID. 


OSErr  QTGetAtomTypeAndID  ( 

QTAtomContai ner  container, 
QTAtom  atom, 

QTAtomType  *atomType, 

QTAtomID  *id  ); 


contai ner 

The  atom  container  that  contains  the  atom. 


atom 

The  atom  whose  type  and  ID  should  be  retrieved. 
atomType 

A  pointer  to  an  atom  type.  On  return,  this  parameter  points  to  the  type  of  the 
specified  atom.  You  can  pass  N I L  for  this  parameter  if  you  don't  need  this 
information. 
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QTGetDataRefMaxFileOffset 


i  d 

A  pointer  to  an  atom  ID.  On  return,  this  parameter  points  to  the  ID  of  the 
specified  atom.  You  can  pass  N I L  for  this  parameter  if  you  don't  need  this 
information. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Retrieving  Atoms  and  Atom  Data"  (V-2768) 

Related  Java  Methods 

qui cktime . std .movi es . AtomContai ner . getAtomType( ) , 
qui ckti me . std .movi es .AtomContai ner . getAtomlDC ) 


QTGetDataRefMaxFileOffset 


Undocumented 

OSErr  QTGetDataRefMaxFileOffset  ( 

Movie  movieH, 

OSType  dataRefType, 

Handle  dataRef, 

long  *offset  ); 

movi eH 

Undocumented 

dataRefType 

The  type  of  data  reference;  see  "Data  References"  (IV-2661).  If  the  data 
reference  is  an  alias,  you  must  set  this  parameter  to  rAl  i  asType.  See  Inside 
Macintosh:  Files  (listed  in  the  bibliography)  for  more  information  about  aliases 
and  the  Alias  Manager. 

dataRef 

A  handle  to  a  data  reference.  The  type  of  information  stored  in  the  handle 
depends  upon  the  data  reference  type  specified  by  the  dataRefType  parameter. 

offset 

Undocumented 
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function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 


QTGetDDObject 


Returns  the  Windows  DirectDraw  object  currently  in  use  by  QuickTime. 

OSErr  QTGetDDObject  ( 

void  **lpDDObject  ); 

1 pDDObject 

A  handle  to  a  DirectDraw  object. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  useful  for  developers  who  want  to  call  DirectDraw  methods 
directly. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML.h 

See  Also 

For  the  corresponding  set  function,  see  QTSetDDObject  (11-1225). 


QTGetEffectsList 


Returns  a  QT  atom  container  holding  a  list  of  the  currently  installed  effects 
components. 


OSErr  QTGetEffectsList  ( 
QTAtomContai ner 
1  ong 
1  ong 

QTEffectLi stOptions 


*returnedLi st , 
mi nSources , 
maxSources , 
getOpti ons  ) ; 
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QTGetEffectsList 


returnedLi st 

If  the  function  returns  noErr,  this  parameter  contains  a  newly  created  QT  atom 
container  holding  a  list  of  their  currently  installed  effects.  Any  data  stored  in 
the  parameter  on  entry  is  overwritten  by  the  list  of  effects.  It  is  the  responsibility 
of  the  calling  application  to  dispose  of  the  storage  by  calling 
QTDi  sposeAtomContai  ner  (11-1164)  once  the  list  is  no  longer  required, 
mi  nSources 

The  minimum  number  of  sources  that  an  effect  must  have  to  be  added  to  the 
list.  Pass  -1  as  this  parameter  to  specify  no  minimum. 

maxSources 

The  maximum  number  of  sources  that  an  effect  can  have  to  be  added  to  the  list. 
Pass  -1  as  this  parameter  to  specify  no  maximum.  The  mi  nSources  and 
maxSources  parameters  allow  you  to  restrict  which  effects  are  returned  in  the 
list,  by  specifying  the  minimum  and  maximum  number  of  sources  that 
qualifying  effects  can  have. 
getOpti ons 

Options  (see  below)  that  control  which  effects  are  added  to  the  list.  If  you  pass 
0,  the  function  includes  every  effect,  except  the  "none"  effect  and  any 
prohibited  by  the  values  of  mi  nSources  and  maxSources. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

getOptions  Constants 

el Opti onslncl udeNonelnLi st 

Include  the  "none"  effect  in  the  returned  list.  The  "none"  effect  does  nothing. 

Discussion 

The  returned  list  contains  two  atoms  for  each  effect  component.  The  first  atom,  of 
type  kEf fectNameAtom,  contains  the  name  of  the  effect.  The  second  atom,  of  type 
kEf  f  ectTypeAtom,  contains  the  type  of  the  effect,  which  is  the  sub-type  of  the  effect 
component.  This  list  is  sorted  alphabetically  on  the  names  of  the  effects.  You  can 
constrain  the  list  to  certain  types  of  effects,  such  as  those  that  take  two  sources.  Use 
this  function  to  obtain  a  list  of  effects  that  you  can  pass  to 
QTCreateStandardParameterDi  al  og  (11-1161). 

Special  Considerations 

This  function  can  take  a  fairly  long  time  to  execute,  as  it  searches  the  system  for 
installed  effects  components.  You  will  normally  want  to  call  this  function  once 
when  your  application  starts,  or  after  a  pair  of  suspend  and  resume  events. 
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QTGetEffectSpeed 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "High-Level  Effects  Functions"  (V-2897) 


QTGetEffectSpeed 


Returns  the  speed  of  the  effect,  expressed  in  frames  per  second. 

OSErr  QTGetEffectSpeed  ( 

QTAtomContai ner  parameters, 

Fixed  *pFPS  ); 

parameters 

Contains  parameter  values  for  the  effect. 

pFPS 

The  speed  of  the  effect  is  returned  in  this  parameter,  expressed  in  frames  per 
second.  Effects  can  also  return  the  pre-defined  constant  effect  Is  Real  time  (see 
below)  as  their  speed. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

pFPS  Constant 

effectlsReal time 

The  effect  will  execute  as  quickly  as  frames  can  be  sent  to  it  for  rendering. 

Discussion 

The  value  returned  should  not  be  treated  as  an  absolute  measurement  of  effect 
performance.  In  particular,  most  effects  only  return  one  value,  regardless  of 
parameter  settings  and  hardware.  This  value  is  an  estimate  of  execution  speed  on  a 
reference  hardware  platform.  Actual  performance  will  vary  depending  on 
hardware,  configuration  and  parameter  options. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "High-Level  Effects  Functions"  (V-2897) 
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QTGetFileNameExtension 


Gets  the  extension  to  a  file  name. 

OSErr  QTGetFileNameExtension  ( 

Const St rFileNameParam  fileName, 

OSType  fileType, 

OSType  *extension  ); 

f i 1 eName 

A  file  name  string, 
f i 1 eType 

A  file  type;  see  "File  Types  and  Creators"  (IV-2668). 
extensi on 

A  pointer  to  the  file  name  extension  string. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


QTGetMIMETypelnfo 


Retrieves  information  about  a  particular  MIME  type. 


OSErr  QTGetMIMETypelnfo  ( 

const  char  *mimeStringStart, 
short  mimeStri ngLength , 

OSType  i nf oSel ector , 

void  *infoDataPtr, 

long  *i nf oDataSi ze  ); 


mimeStri ngStart 

A  pointer  to  the  first  character  of  a  string  holding  the  MIME  type, 
mi meStri ngLength 

The  number  of  characters  in  the  MIME  type  string.  Pascal,  C,  and  nondelimited 
string  buffers  can  be  passed  equally  well. 

i nf oSel ector 

A  constant  (see  below)  that  indicates  the  type  of  information  being  requested. 
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QTGetN  extChildType 


i nfoDataPtr 

A  pointer  to  a  value  to  be  updated.  For  current  selectors  this  value  is  Bool  ean. 

1 nfoDataSi ze 

On  input,  a  pointer  to  the  size  of  the  data  being  expected;  on  output,  a  pointer 
to  the  size  of  the  data  being  retrieved.  In  all  current  cases  these  will  be  the  same 
size. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

infoSelector  Constants 

kQTGetMIMETypelnfoIsQui ckTimeMovi eType 

Corresponds  to  a  MIME  type  for  a  QuickTime  movie.  The  current  check  is 
against  video /quicktime  and  application/x-quicktimeplayer  but  this  may  be 
extended  in  the  future. 
kQTGetMIMETypelnfoIsUnhel pf ul Type 

Useful  in  trying  to  determine  an  importer,  this  returns  false  for  application/ 
octet-stream,  a  MIME  type  that  often  indicates  a  poorly  configured  server.  This 
allows  the  MIME  check  to  be  bypassed  for  obviously  bogus  MIME  type 
information. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Movi  es .  h 


QTGetNextChildType 


Returns  the  next  atom  type  in  the  child  list  of  the  specified  parent  atom. 

QTAtomType  QTGetNextChildType  ( 

QTAtomContai ner  container, 

QTAtom  parentAtom, 

QTAtomType  currentChi 1 dType  ); 

contai ner 

The  atom  container  that  contains  the  parent  atom. 
parentAtom 

The  parent  atom  for  this  operation. 


11-1178 


Inside  QuickTime:  Function  l-Q 


QTGetPixelSize 


currentChi 1 dType 

The  last  atom  type  retrieved  by  this  function. 

function  result  The  next  atom  type  in  the  child  list  of  the  atom  specified  by 
parentAtom. 

Discussion 

You  can  call  this  function  to  iterate  through  the  atom  types  in  a  parent  atom's  child 
list.  To  retrieve  the  first  atom  type,  you  should  set  the  value  of  the  currentChi  1  dType 
parameter  to  0.  To  retrieve  subsequent  atom  types,  you  should  set  the  value  of  the 
currentChi  1  dType  parameter  to  the  atom  type  retrieved  by  the  previous  call  to  this 
function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Retrieving  Atoms  and  Atom  Data"  (V-2768) 

Related  Java  Methods 

qui cktime . std .movi es . AtomContai ner . getNextChi 1 dType ( ) 


QTGetPixelSize 


Returns  the  bits  per  pixel  for  a  given  pixel  format. 

short  QTGetPixelSize  ( 

OSType  Pixel  Format  ); 

Pi xel Format 

A  constant  that  identifies  the  pixel  format;  see  "Pixel  Formats"  (IV-2686).  This 
function  returns  meaningful  information  only  for  non-planar  formats. 

function  result  The  bits  per  pixel.  Returns  0  if  the  format  is  unknown. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Related  Java  Methods 

qui cktime . qd . QDGraphi cs . get Pi xel Si ze( ) 


Inside  QuickTime:  Function  l-Q 


11-1179 


QTGetPixMapHandleGammaLevel 


See  Also 

See  the  ICMSetPi  xel  Format  Info  (11-678)  function  and  the  I  CM  Pi  xel  Format  Info 
(IV-2282)  structure. 


QTGetPixMapHandleGammaLevel 

Retrieves  the  current  Pi xMap  extension's  gamma  level  setting. 

Fixed  QTGetPixMapHandleGammaLevel  ( Pi xMapHandl e  pm); 
pm 

A  handle  to  a  Pi  xMap  (IV-2332)  structure  that  has  a  Pi  xMapExtensi  on  (IV-2335) 
structure. 

function  result  On  return,  the  gamma  level  previously  set  (or  the  default  level)  for 
the  pixel  map  referenced  by  the  pm  parameter. 

Discussion 

A  typical  use  for  this  function  is  to  retrieve  the  gamma  level  of  a  pixel  map  after  a 
codec  decompresses  it  into  a  Pi  xMap  structure. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

See  Also 

For  the  corresponding  set  function,  see  QTSetPi xMapHandl  eGamma Level  (11-1227). 


QTGetPixMapHandleRequestedGammaLevel 

Retrieves  the  current  Pi  xMap  extension's  requested  gamma  level  setting. 
Fixed  QTGetPixMapHandleRequestedGammaLevel  ( Pi xMapHandl e  pm); 


A  handle  to  a  Pi  xMap  (IV-2332)  structure  that  has  a  Pi  xMapExtensi  on  (IV-2335) 
structure. 

function  result  On  return,  the  requested  gamma  level  previously  set  (or  the  default 
level)  for  the  pixel  map  referenced  by  the  pm  parameter. 


11-1180 


Inside  QuickTime:  Function  l-Q 


QTGetPixMapHandleRowBytes 


Discussion 

A  typical  use  for  this  function  is  to  retrieve  the  gamma  level  of  a  pixel  map  after  a 
codec  decompresses  it  into  a  Pi  xMap  structure.  The  requested  gamma  level  is  used 
to  control  what  gamma  conversion  is  attempted  during  decompression.  The 
requested  gamma  level  may  differ  from  the  actual  gamma  level  depending  on  the 
compressed  data  and  the  capabilities  of  the  codecs  involved. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

See  Also 

For  the  corresponding  set  function,  see  QTSetPi xMapHandl  eRequestedGammaLevel 
(11-1227). 


QTGetPixMapHandleRowBytes 

Gets  the  row  By  tes  value  for  a  pixel  map  accessed  by  a  handle. 

long  QTGetPixMapHandleRowBytes  ( 

PixMapHandle  pm  ); 


pm 

A  handle  to  a  Pi  xMap  (IV-2332)  structure. 
function  result  The  rowBytes  value. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

See  Also 

For  the  corresponding  set  function,  see  QTSetPi  xMapHandl  eRowBytes  (11-1228). 


QTGetPixMapPtrGammaLevel 

Retrieves  the  current  Pi  xMap  extension's  gamma  level  setting. 
Fixed  QTGetPixMapPtrGammaLevel  (PixMapPtr  pm); 


Inside  QuickTime:  Function  l-Q 


11-1181 


QTGetPixMapPtrRequestedGammaLevel 


pm 

A  pointer  to  a  Pi  xMap  (IV-2332)  structure  that  has  a  PixMapExtension  (IV-2335) 
structure. 

function  result  On  return,  the  gamma  level  previously  set  (or  the  default  level)  for 
the  pixel  map  pointed  to  by  the  pm  parameter. 

Discussion 

A  typical  use  for  this  function  is  to  retrieve  the  gamma  level  of  a  pixel  map  after  a 
codec  decompresses  it  into  a  Pi  xMap  structure. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

See  Also 

For  the  corresponding  set  function,  see  QTSetPixMapPtrGammaLevel  (11-1229). 


QTGetPixMapPtrRequestedGammaLevel 

Retrieves  the  current  Pi  xMap  extension's  gamma  level  setting. 

Fixed  QTGetPixMapPtrRequestedGammaLevel  (PixMapPtr  pm); 
pm 

A  pointer  to  a  Pi  xMap  (IV-2332)  structure  that  has  a  PixMapExtension  (IV-2335) 
structure. 

function  result  On  return,  the  requested  gamma  level  previously  set  (or  the  default 
level)  for  the  pixel  map  pointed  to  by  the  pm  parameter. 

Discussion 

A  typical  use  for  this  function  is  to  retrieve  the  gamma  level  of  a  pixel  map  after  a 
codec  decompresses  it  into  a  Pi  xMap  structure.  The  requested  gamma  level  is  used 
to  control  what  gamma  conversion  is  attempted  during  decompression.  The 
requested  gamma  level  may  differ  from  the  actual  gamma  level  depending  on  the 
compressed  data  and  the  capabilities  of  the  codecs  involved 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


11-1182 


Inside  QuickTime:  Function  l-Q 


QTGetPixMapPtrRowBytes 


See  Also 

For  the  corresponding  set  function,  see  QTSetPi xMapPtrRequestedGammaLevel 
(11-1230). 


QTGetPixMapPtrRowBytes 


Gets  the  row  By  tes  value  for  a  pixel  map  accessed  by  a  pointer. 

long  QTGetPixMapPtrRowBytes  ( 

PixMapPtr  pm  ); 


pm 

A  pointer  to  a  Pi  xMap  (IV-2332)  structure. 
function  result  The  rowBytes  value. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

See  Also 

For  the  corresponding  set  function,  see  QTSetPi xMapPtrRowBytes  (11-1231). 


QTInsertChild 


Creates  a  new  child  atom  of  the  specified  parent  atom. 

OSErr  QTInsertChild  ( 

QTAtomContai ner 
QTAtom 
QTAtomType 
QTAtomID 
short 
1  ong 
void 
QTAtom 

contai ner 

The  atom  container  that  contains  the  parent  atom.  The  atom  container  must  not 
be  locked. 


container, 
parentAtom, 
atomType , 
i  d , 

i ndex, 
dataSi ze , 
*data , 
*newAtom  ) ; 


Inside  QuickTime:  Function  l-Q 


11-1183 


QTInsertChild 


parentAtom 

The  parent  atom  within  the  atom  container. 
atomType 

The  type  of  the  new  atom  to  be  inserted, 
i  d 

The  ID  of  the  new  atom  to  be  inserted.  This  ID  must  be  unique  among  atoms  of 
the  same  type  for  the  specified  parent.  If  you  set  this  parameter  to  0,  the 
function  assigns  a  unique  ID  to  the  atom, 
i  ndex 

The  index  of  the  new  atom  among  atoms  with  the  same  parent.  To  insert  the 
first  atom  for  the  specified  parent,  you  should  set  this  parameter  to  1.  To  insert 
an  atom  as  the  last  atom  in  the  child  list,  you  should  set  this  parameter  to  0. 
Index  values  greater  than  the  index  of  the  last  atom  in  the  child  list  plus  1  are 
invalid. 
dataSi ze 

The  size  of  the  data  for  the  new  atom.  If  the  new  atom  is  to  be  a  parent  atom  or 
if  you  want  to  add  the  atom's  data  later,  you  should  pass  0  for  this  parameter. 
To  create  the  new  atom  as  a  leaf  atom  that  contains  data,  you  should  specify  the 
data  using  the  data  parameter  and  and  its  size  using  the  dataSi  ze  parameter. 

data 

A  pointer  to  a  buffer  containing  the  data  for  the  new  atom.  If  you  set  the  value 
of  the  dataSi  ze  parameter  to  0,  you  should  pass  NIL  for  this  parameter. 
newAtom 

A  pointer  to  data  of  type  QTAtom.  On  return,  this  parameter  points  to  the  newly 
created  atom.  You  can  pass  N I L  for  this  parameter  if  you  don't  need  a  reference 
to  the  newly  created  atom. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

You  call  this  function  to  create  a  new  child  atom.  The  new  child  atom  has  the 
specified  atom  type  and  atom  ID,  and  is  inserted  into  its  parent  atom's  child  list  at 
the  specified  index.  Any  existing  atoms  at  the  same  index  or  greater  are  moved 
toward  the  end  of  the  child  list. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


11-1184 


Inside  QuickTime:  Function  l-Q 


QTInsertChildren 


Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Creating  New  Atoms"  (V-2767) 

Related  Java  Methods 

qui cktime . std .movi es . AtomContai ner . i nsertChi 1 d ( ) 


QTInsertChildren 

Inserts  a  container  of  atoms  as  children  of  the  specified  parent  atom. 

OSErr  QTInsertChildren  ( 

QTAtomContai ner  container, 

QTAtom  parentAtom, 

QTAtomContai ner  chi  1 drenContainer  ); 

contai ner 

The  atom  container  that  contains  the  parent  atom.  The  atom  container  must  not 
be  locked. 
parentAtom 

The  parent  atom  within  the  atom  container, 
chi  1 drenContai ner 

The  atom  container  that  contains  the  child  atoms  to  be  inserted. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

You  call  this  function  to  insert  a  container  of  atoms  as  children  of  a  parent  atom  in 
another  atom  container.  Each  child  atom  is  inserted  as  the  last  atom  of  its  type  and 
is  assigned  a  corresponding  index.  The  ID  of  a  child  atom  to  be  inserted  must  not 
duplicate  that  of  an  existing  child  atom  of  the  same  type.  The  following  code  shows 
how  you  can  use  this  function  to  create  a  container,  insert  an  atom,  and  insert 
another  container  as  a  child  of  the  atom: 

//  QTInsertChildren  coding  example 

FailOSErr  (QTInsertChi 1 d  (outerContainer,  kParentAtomlsContainer, 
kSpri teAtomType ,  spritelD,  0,  0,  NIL,  &newParentAtom) ) ; 

FailOSErr  (QTInsertChildren  (outerContainer,  newParentAtom, 
i nnerContai ner) ) ; 


Inside  QuickTime:  Function  l-Q 


11-1185 


QTIsStandardParameterDialogEvent 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi es .  h 

Programming  summary:  "Copying  Existing  Atoms"  (V-2767) 

Related  Java  Methods 

qui ckti me . std .movi es . AtomContai ner.insertChildrent ) 


QTIsStandardParameterDialogEvent 

Determines  if  a  Macintosh  event  is  processed  by  a  standard  parameter  dialog  box 
created  by  QTCreateStandardParameterDi  al  og  (11-1161). 

OSErr  QTIsStandardParameterDial ogEvent  ( 

EventRecord  *pEvent, 

QTParameterDial og  createdDi al og  ); 

pEvent 

The  Macintosh  event. 
createdDi al og 

The  reference  to  the  standard  parameters  dialog  box  that  is  returned  by 
QTCreateStandardParameterDi  al  og  (11-1161). 

function  result  See  below. 

Function  Result  Constants 

noErr 

The  event  was  related  to  the  standard  parameters  dialog  box  and  was 
completely  processed.  Your  application  should  not  process  this  event. 

featurellnsupported 

The  event  was  not  related  to  the  standard  parameters  dialog  box.  Your 
application  should  process  the  event  in  the  normal  way. 

codec Pa rameterDi al ogConf i rm 

The  user  clicked  the  OK  button  in  the  standard  parameters  dialog  box.  Your 
application  should  call  QTDismissStandardParameterDialog  (11-1163)  to  close  the 
dialog  box.  The  values  chosen  by  the  user  are  put  into  the  atom  container  you 
passed  in  the  parameters  parameter  when  you  called 

QTCreateStandardParameterDi  al  og  (11-1161).  This  atom  container  now  holds  an 
effect  description  that  is  ready  to  insert  into  an  effects  track.  It  may  require  one 
or  two  '  s  rc  '  atoms  to  be  complete. 


11-1186 


Inside  QuickTime:  Function  l-Q 


QTLockContainer 


userCancel edErr 

The  event  was  handled  by  the  standard  parameter  dialog  box,  and  the  user 

clicked  the  Cancel  button  of  the  dialog  box.  You  should  call 

QTDi  smi  ssStandardParameterDi  al  og  (11-1163)  to  close  the  dialog  box. 

Discussion 

After  you  create  a  standard  parameter  dialog  box,  pass  every  Macintosh  event 
through  this  function  to  determine  if  your  application  should  handle  the  event. 
Once  the  dialog  box  has  been  confirmed  or  cancelled  by  the  user,  you  should  no 
longer  call  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "High-Level  Effects  Functions"  (V-2897) 

Related  Java  Methods 

qui cktime . std .movi es . ParameterDi al og . showParameterDi a  1 og ( ) 


QTLockContainer 


Locks  an  atom  container  in  memory. 

OSErr  QTLockContainer  ( 

QTAtomContai ner  container  ); 

contai ner 

The  atom  container  to  be  locked. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

You  should  call  this  function  to  lock  an  atom  container  before  calling 
QTGetAtomDataPtr  (11-1171)  to  directly  access  a  leaf  atom's  data.  When  you  have 
finished  accessing  a  leaf  atom's  data,  you  should  call  QTUnl  ockContai  ner  (11-1316). 
You  may  make  nested  pairs  of  calls  to  QTLockContai  ner  and  QTUnl  ockContai  ner;  you 
don't  need  to  check  the  current  state  of  the  container  first. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Function  l-Q 


11-1187 


QTMIDIGetMIDIPorts 


Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Retrieving  Atoms  and  Atom  Data"  (V-2768) 


QTMIDIGetMIDIPorts 


Returns  two  lists  of  MIDI  ports  supported  by  the  specified  MIDI  component:  a  list 
of  ports  that  can  receive  MIDI  input  and  a  list  of  ports  that  can  send  MIDI  output. 

ComponentResul t  QTMIDIGetMIDIPorts  ( 

QTMIDIComponent  ci  , 

QTMIDIPortLi stHandle  *i nputPorts, 

QTMIDIPortLi stHandl e  *outputPorts  ); 


ci 

A  MIDI  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

i nputPorts 

A  list  of  the  MIDI  ports  supported  by  the  component  that  can  receive  MIDI 
input. 

outputPorts 

A  list  of  the  MIDI  ports  supported  by  the  component  that  can  send  MIDI 
output. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  caller  of  this  function  must  dispose  of  the  i  nputPorts  and  outputPorts  handles. 

Special  Considerations 

NAGetMIDI  Ports  (11-1025)  is  the  correct  call  for  applications  to  make.  They  should  not 
call  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c . h 

Programming  summary:  "MIDI  Component  Functions"  (V-2924) 


11-1188 


Inside  QuickTime:  Function  l-Q 


QTMIDISendMIDI 


QTMIDISendMIDI 


Sends  MIDI  data  to  a  MIDI  port. 

ComponentResul t  QTMIDISendMIDI  ( 
QTMIDIComponent  ci  , 

long  portlndex, 

MusicMIDIPacket  *mp  ); 


ci 

A  MIDI  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
portlndex 

The  index  of  the  MIDI  port  to  use  for  this  operation, 
mp 

A  pointer  to  the  MIDI  data  packet  to  send. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  can  be  called  at  interrupt  time.  However,  the  same  interrupt  level  is 
used  whenever  MIDI  data  is  sent  by  the  specified  MIDI  component. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "MIDI  Component  Functions"  (V-2924) 


QTMIDIUseReceivePort 

Allocates  a  MIDI  port  for  input  or  to  release  the  port. 

ComponentResul t  QTMIDIUseReceivePort  ( 
QTMIDIComponent  ci  , 

long  portlndex, 

MusicMIDIReadHookUPP  readHook, 
long  refCon  ); 


A  MIDI  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 


Inside  QuickTime:  Function  l-Q 


11-1189 


QTMIDIUseSendPort 


portlndex 

The  index  of  the  MIDI  port  to  use  for  this  operation. 
readHook 

A  pointer  to  aMusicMIDIReadHookProc  (III— 2109)  callback  that  receives  incoming 
MIDI  data  packets,  or  N I L  to  release  the  port. 

refCon 

A  reference  constant  passed  to  the  function  specified  by  the  readHook 
parameter.  Use  this  parameter  to  point  to  a  data  structure  containing  any 
information  your  callback  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  MIDI  component  delivers  only  MIDI  data  packets  that  contain  a  single  status 
byte. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "MIDI  Component  Functions"  (V-2924) 


QTMIDIUseSendPort 


Allocates  a  MIDI  port  for  output  or  to  release  the  port. 

ComponentResul t  QTMIDIUseSendPort  ( 

QTMIDIComponent  ci  , 

long  portlndex, 

1 ong  i nUse  ) ; 


ci 

A  MIDI  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

portlndex 

The  index  of  the  MIDI  port  for  this  operation, 
i  n  U  s  e 

Specifies  whether  to  allocate  the  MIDI  port  for  output  (if  the  value  is  1)  or  to 
release  the  port  (if  the  value  is  0). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


11-1190 


Inside  QuickTime:  Function  l-Q 


QTMLAcquireWindowList 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "MIDI  Component  Functions"  (V-2924) 


QTMLAcquireWindowList 

Acquires  exclusive  access  to  the  global  list  of  Macintosh  windows,  so  that  the  list 
will  not  change  until  you  call  QTMLRel  easeWi  ndowLi  st  (11-1196). 

void  QTMLAcquireWindowList  (  void  ); 


Discussion 

If  you  want  to  call  the  Windows  LMGetWi  ndowLi  st  or  FrontWi  ndow  functions  and  then 
proceed  to  walk  down  the  next  pointers,  you  need  to  protect  yourself  against 
another  thread  modifying  the  list  while  you  walk.  Call  this  function  before  and 
QTMLRel  easeWi  ndowLi  st  (11-1196)  after. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML .  h 


QTMLCreateMutex 


Creates  a  synchronization  object  to  facilitate  mutually  exclusive  access  to  a 
Windows  data  structure. 

QTMLMutex  QTMLCreateMutex  (  void  ); 


Discussion 

This  function  creates  a  mutex  object  for  guarded  access  to  data  structures  and 
routines  that  require  mutually  exclusive  access.  In  a  multithreaded  preemptive 
environment,  such  as  Windows  NT,  you  can  use  the  various  mutex  utility  functions 
such  as  QTMLGrabMutex  (11-1195)  to  protect  a  shared  resource  from  simultaneous 
access  by  multiple  threads  or  processes.  Mutex  objects  are  used  throughout  QTML 
to  provide  such  protection. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Function  l-Q 


11-1191 


QTMLCreateSyncVar 


Programming  Info 

C  interface  file:  QTM  L .  h 


QTMLCreateSync  V  ar 

Creates  a  synchronization  variable,  used  to  provide  guarded  access  to  resources 
shared  across  threads  and  processes. 

QTMLSyncVarPtr  QTMLCreateSyncVar  (  void  ); 

function  result  A  pointer  to  a  Windows  synchronization  variable. 

Discussion 

You  call  this  function  to  create  a  synchronization  variable  that  allows  for 
mutually-exclusive  access  to  resources.  The  synchronization  variable  routines  use 
atomic  tests  to  ensure  that  the  portions  of  the  routines  that  perform  the  testing 
cannot  be  interrupted  during  the  test. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML.h 


QTMLDestroyMutex 

Deallocates  a  synchronization  object  created  by  QTMLCreateMutex  (11-1191). 

void  QTMLDestroyMutex  ( 

QTMLMutex  mu  ) ; 


mu 

A  mutex  object. 

Discussion 

Call  this  function  to  deallocate  the  mutex  object  created  by  QTMLCreateMutex 
(11-1191). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML.h 


11-1192 


Inside  QuickTime:  Function  l-Q 


QTMLDestroySyncVar 


QTMLDestroy  Sync  V  ar 

Releases  ownership  of  a  synchronization  variable. 

void  QTMLDestroySyncVar  ( 

QTMLSyncVarPtr  p  ); 


P 

A  pointer  to  a  synchronization  variable. 

Discussion 

Call  this  function  to  deallocate  the  QTMLSyncVar  object  created  by  QTMLCreateSyncVar 
(11-1192). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML .  h 


QTMLGetCanonicalPathName 


Takes  a  Windows  native  file  path  and  returns  the  one  canonical  path  to  that  file. 

OSErr  QTMLGetCanonicalPathName  ( 
char  *inName, 

char  *outName, 

unsigned  long  outLen  ); 

i nName 

The  input  path. 
outName 

Specifies  where  the  routine  puts  the  canonical  path. 
outLen 

The  length  of  the  outName  buffer,  so  that  the  routine  knows  not  to  write  past  the 
end  of  your  buffer. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Discussion 

Some  of  the  tasks  performed  by  this  routine  include  removing  all  double-dots  from 
the  path,  converting  all  short  (8.3)  names  back  to  their  long  names,  and  restoring  the 
correct  capitalization.  This  routine  also  works  for  universal  naming  convention 
(UNC)  paths.  These  paths  are  of  the  form: 


Inside  QuickTime:  Function  l-Q 


11-1193 


QTMLGetVolumeRootPath 


c:\Program  FilesXSome  ProductXtest.mov 
c:\PROGRA-l\SOMEPR-l\test.mov 

c:\Some  other  fol der\ . . \program  FI LESXanother  programX. .\somepr-l\TeSt.MoV 

C:\proGra-l\Some  productX. .\S0MEPR-1\. .\. .\program  files\a_product\test.mov 

C:\PR0GRA-1\S0MEPR-1\TEST.M0V 

c:\Program  Fil es\A_Product\test .mov 

\\my_server\shared_fol der\a_fo! der\test.mov 

Special  Considerations 

There  is  a  one-to-one  mapping  between  canonical  pathnames  and  files.  In  other 
words,  you  can  determine  if  two  paths  point  to  the  same  file  by  canonicalizing  both 
paths,  and  then  doing  a  string  compare. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML.h 


QTMLGetV  olumeRootPath 

Takes  a  Windows  path  and  returns  the  portion  of  it  that  points  to  the  volume  root. 

OSErr  QTMLGetVolumeRootPath  ( 
char  *fullPath, 

char  *vol umeRootPath , 

unsigned  long  vol umeRootLen  ); 

f ul 1  Path 

The  path  being  passed  in. 
vol umeRootPath 

Specifies  where  this  routine  writes  the  volume  root  path, 
vol umeRootLen 

The  length  of  the  vol  umeRootPath  buffer,  so  the  routine  knows  not  to  write  past 
the  end  of  your  buffer. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  routine  is  useful  when  you  need  to  call  Windows  routines,  such  as 
GetVol  umelnformati  on,  which  take  a  volume  root  path  as  an  argument. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


11-1194 
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QTMLGetWindowWndProc 


Programming  Info 

C  interface  file:  QTML .  h 


QTMLGetW  indowWndProc 

Returns  the  WndProc  previously  specified  in  QTMLSetWi  ndowWndProc  (11-1198). 

void  *  QTMLGetWindowWndProc  ( 

WindowPtr  theWindow  ); 

theWi ndow 

The  Macintosh  window  to  hook.  This  must  have  been  created  via  the  Windows 
calls  NewCWi  ndow  or  NewWi  ndow,  or  as  a  result  of  calling  CreatePortAssoci  ati  on 
(1-148)  on  a  native  HWND. 

function  result  Returns  N I L  if  no  application-defined  WndProc  is  set. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTML .  h 

See  Also 

For  the  corresponding  set  function,  see  QTMLSetWi  ndowWndProc  (11-1198). 


QTMLGrabMutex 


Confers  ownership  of  a  mutex  created  by  QTMLCreateMutex  (11-1191). 

void  QTMLGrabMutex  ( 

QTMLMutex  mu  ); 


mu 

A  mutex  object. 

Discussion 

Call  this  function  when  you  require  exclusive  ownership  of  the  resource  guarded 
by  a  mutex.  This  function  will  return  when  you  have  gained  this  ownership.  In  the 
case  where  another  thread  or  process  holds  the  mutex,  this  function  waits  until  that 
process  or  thread  relinquishes  control.  If  you  need  to  determine  if  you  can  grab  the 
mutex,  without  actually  grabbing  it,  call  QTMLT ryGrabMutex  (11-1199). 
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QTMLRegisterlnterruptSafeThread 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML.h 


QTMLRegisterlnterruptSafeThread 

Registers  a  thread  of  execution  that  is  allowed  to  make  interrupt-safe  calls. 

long  QTMLRegisterlnterruptSafeThread  ( 
unsigned  long  threadID, 

voi d  *threadInfo  ) ; 

threadID 

Thread  ID  of  the  calling  thread.  This  value  is  obtained  by  calling  the  Win32 
GetCurrentThreadld  function. 

threadlnfo 

Thread  information.  This  value  is  obtained  by  calling  the  Win32 
GetCurrentThread  function. 

function  result  Returns  noErr  if  successful. 

Discussion 

The  QTML  function  dispatcher  includes  a  mechanism  that  prevents  not  only  the 
QuickTime  Toolbox  from  being  reentered  but  also  allows  certain  APIs  to  be  callable 
at  interrupt  time.  On  the  Macintosh,  these  calls  require  that  the  calling  code  not 
allocate,  move,  or  purge  memory.  On  Windows,  threads  that  emulate  interrupt 
handlers  need  to  register  with  QTML  by  calling  this  function,  so  that  API  calls  made 
from  that  thread  are  not  blocked.  You  should  make  this  call  at  the  top  of  your  thread 
main  routine. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML.h 


QTMLReleaseWindowList 

Allows  Windows  threads  to  modify  the  global  list  of  Macintosh-style  windows, 
void  QTMLReleaseWindowList  (  void  ); 


11-1196 


Inside  QuickTime:  Function  l-Q 


QTMLResetSyncVar 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML .  h 


QTMLResetSync  V  ar 

Resets  the  lock  for  a  QTMLSyncVar  object. 

void  QTMLResetSyncVar  ( 

QTMLSyncVarPtr  sync  ); 


sync 

A  pointer  to  a  synchronization  variable. 

Discussion 

Call  QTMLResetSyncVar  to  relinquish  the  lock  obtained  from  a  previous  call  to 
QTMLWai tAndSetSyncVar  (11-1200). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML .  h 


QTMLReturnMutex 


Releases  ownership  of  a  QTMLMutex  object. 

void  QTMLReturnMutex  ( 

QTMLMutex  mu  ); 


mu 

A  mutex  object. 

Discussion 

Call  this  function  to  balance  a  call  to  QTMLGrabMutex  (11-1195)  when  you  are  ready  to 
relinquish  control  of  the  mutex  and  corresponding  shared  resource.  By  making  this 
call,  you  allow  other  processes  or  threads  waiting  for  the  release  of  this  mutex  to 
gain  access. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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QTMLSetWindowWndProc 


Programming  Info 

C  interface  file:  QTM  L .  h 


QTMLSetWindowWndProc 


Specifies  an  application-defined  window  procedure  (WndProc)  which  is  called  by 
QTML  after  QTML  processes  the  message  for  an  HWND. 

void  QTMLSetWindowWndProc  ( 

WindowPtr  theWindow, 

voi d  *wi ndowProc  ) ; 

theWi ndow 

A  pointer  to  the  Macintosh  window  to  hook.  This  must  have  been  created  via 
the  Windows  calls  NewCWi  ndow  or  NewWi  ndow,  or  as  a  result  of  calling 
CreatePortAssoci  ati  on  (1-148)  on  a  native  HWND. 
wi ndowProc 

A  Windows  WndProc  procedure.  For  a  detailed  description  of  the  WndProc 
procedure,  see  the  Win32  documentation. 

Discussion 

This  routine  is  useful  if  you  want  to  perform  some  special  Windows  processing  of 
the  native  messages  that  Windows  sends  to  your  window  pointer. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTML.h 

See  Also 

For  the  corresponding  get  function,  see  QTMLGetWi  ndowWndProc  (11-1195). 


QTMLT  est  AndSetSync  V  ar 


Performs  a  one-shot  atomic  test  and  set  operation  of  a  QTMLSyncVar  object. 

long  QTMLTestAndSetSyncVar  ( 

QTMLSyncVarPtr  sync  ); 


sync 

A  pointer  to  a  synchronization  variable. 


11-1198 


Inside  QuickTime:  Function  l-Q 


QTMLTryGrabMutex 


function  result  Returns  0  if  you  have  acquired  the  synchronization  lock. 

Discussion 

Call  this  function  to  perform  a  single  test  and  set  operation  on  the  QTMLSyncVar 
object. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML .  h 


QTMLTryGrabMutex 


Determines  if  you  would  be  able  to  get  immediate  ownership  of  a  mutex  created  by 
QTMLCreateMutex  (11-1191). 

Boolean  QTMLTryGrabMutex  ( 

QTMLMutex  mu  ); 


mu 

A  mutex  object. 

function  result  Returns  TRUE  if  you  are  able  to  immediately  grab  the  mutex,  via  the 
QTMLGrabMutex  (11-1195)  call,  without  having  to  wait. 

Discussion 

Call  this  function  when  you  need  to  preflight  a  QTMLGrabMutex  (11-1195)  call. 

Special  Considerations 

Under  normal  circumstances  you  should  not  need  to  make  this  call. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTML .  h 


QTMLUnregisterlnterruptSafeThread 


Unregisters  a  thread  of  execution. 

long  QTMLUnregi sterlnterruptSafeThread  ( 
unsigned  long  threadID  ); 


Inside  QuickTime:  Function  l-Q 


11-1199 


QTMLWaitAndSetSyncVar 


threadID 

Thread  ID  of  the  calling  thread.  This  value  is  obtained  by  calling  the  Win32 
GetCurrentThreadld  function. 

function  result  Returns  noErr  if  successful. 

Discussion 

Use  this  function  to  unregister  an  interrupt-safe  thread  previously  registered  by 
QTMLRegi  sterlnterruptSafeThread  (11-1196).  You  should  make  this  call  at  the  bottom 
of  your  thread  main  routine,  just  before  the  exit. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML.h 


QTML  W  ait  AndSetSync  V  ar 


Acquires  the  lock  for  a  QTMLSyncVar  object, 

void  QTMLWaitAndSetSyncVar  ( 
QTMLSyncVarPtr  sync  ); 


sync 

A  pointer  to  a  synchronization  variable. 

Discussion 

Call  this  function  to  acquire  the  lock  corresponding  to  a  QTMLSyncVar  object.  This 
function  will  wait,  yielding  CPU  time  to  other  threads,  until  the  lock  is  acquired. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML.h 


QTMLYieldCPU 


Yields  time  to  other  threads  while  your  code  is  in  a  tight  loop, 
void  QTMLYieldCPU  (  void  ); 


11-1200 


Inside  QuickTime:  Function  l-Q 


QTMLYieldCPUTime 


Discussion 

Use  this  function  from  within  tight  loops  to  yield  time  to  other  threads.  Using  this 
function  is  similar  to  calling  SystemTask  from  within  a  Macintosh  event  loop. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML .  h 


QTMLYieldCPUTime 


Yields  time  to  other  threads  and  specifies  the  sleep  time  while  in  a  tight  loop. 

void  QTMLYieldCPUTime  ( 

long  milliseconds, 

unsigned  long  flags  ); 

mi  1 1 i Seconds 

Number  of  milliseconds  to  sleep  before  returning  to  the  caller, 
fl  ags 

A  flag  (see  below)  that  specifies  an  option  for  this  function. 

flags  Constant 

kQTMLHandl ePortEvents 

If  this  flag  is  set,  QTML  will  call  the  Win32  functions  PeekMessage, 

T ransl  ateMessage,  and  Di  spatchMessage  to  process  Win32  messages  while  in 
tight  spin  loops. 

Discussion 

Use  this  function  from  within  tight  loops  to  yield  time  to  other  threads. 

Special  Considerations 

This  function  differs  from  QTMLYi  el  dCPU  (11-1200)  in  that  you  can  specify  the  time  to 
sleep  as  well  as  optionally  have  QTML  process  Win32  messages  while  waiting  for 
the  yield  time  to  expire. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML .  h 
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QTMovieNeedsTimeTable 


QTMovieNeedsTimeTable 


Returns  whether  a  movie  is  being  progressively  downloaded. 

OSErr  QTMovieNeedsTimeTable  ( 

Movie  theMovie, 

Boolean  *needsTimeTable  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  identifier  from  such 
functions  as  NewMovie  (11-1069),  NewMovieFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

needsTimeTable 

If  TRUE,  the  movie  is  being  progressively  downloaded.  If  an  error  occurs,  this 
parameter  is  set  to  FALSE. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

A  movie  can  be  progressively  downloaded  when  its  data  is  received  over  a  network 
connection  or  other  slow  data  channel.  Progressive  downloads  are  not  necessary 
when  the  data  for  the  movie  is  on  a  local  disk.  The  Movie  Toolbox  creates  a  time 
table  for  a  movie  when  either  this  function  or  GetMaxLoadedT i  melnMovi  e  (1-423)  is 
called  for  the  movie,  but  the  time  table  is  used  only  by  the  toolbox  and  is  not 
accessible  to  applications.  The  toolbox  disposes  of  the  time  table  when  the 
download  is  complete. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "High-Level  Download  Control"  (V-2772) 

Related  Java  Methods 

quicktime.std.movies.Movie.needsTi meTabl e( ) 


QTNew  Alias 

Creates  a  Mac  OS  alias  to  a  file. 
OSErr  QTNewAlias  ( 


11-1202 
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QTN  e wAtomContainer 


const  FSSpec 
A1  i asHandl e 
Bool ean 


*f  ss , 

*al i as , 
minimal  ); 


f  ss 

A  pointer  to  an  FSSpec  (IV-2262)  structure  that  specifies  a  file, 
alias 

On  return,  a  pointer  to  a  handle  to  a  new  A1  i  as  Record  (IV-2159)  structure  that 
defines  an  alias  to  the  file.  If  the  function  was  unable  to  create  an  alias,  the 
handle  is  set  to  NIL.  This  function  does  not  create  relative  aliases.  For  further 
information  about  Mac  OS  file  aliases,  see  Chapter  4  of  Inside  Macintosh:  Files 
(listed  in  the  bibliography). 

mi nimal 

If  you  pass  TRUE,  the  function  writes  in  the  A1  i  as  Record  structure  only  the  target 
name,  parent  directory  ID,  volume  name  and  creation  date,  and  volume 
mounting  information.  If  you  pass  FALSE,  it  fills  out  the  structure  fully. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Related  Java  Methods 

qui  ckti me .  i  o .  QTFi  1  e .  newAl  i  as  ( ) 


QTNewAtomContainer 

Creates  a  new  atom  container. 

OSErr  QTNewAtomContainer  ( 

QTAtomContai ner  *atomData  ); 

atomData 

A  pointer  to  an  unallocated  atom  container  data  structure.  On  return,  this 
parameter  points  to  an  allocated  atom  container. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
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11-1203 


QTNewG  World 


result.  See  "Error  Codes"  (IV-2663). 

Discussion 

This  function  creates  a  new,  empty  atom  container  structure.  Once  you  have  created 
an  atom  container,  you  can  manipulate  it  using  the  atom  container  functions.  The 
following  example  illustrates  using  this  function  to  create  a  new  QT  atom  container 
and  add  an  atom: 

//  QTNewAtomContai ner  coding  example 
QTAtom  f i rstAtom ; 

QTAtomContai ner  container; 

OSErr  err 

err  =  QTNewAtomContai ner  (&container) ; 
if  ( ! e r r ) 

err  =  QTInsertChi 1 d  (container,  kParentAtomlsContainer ,  'abed', 

1000,  1,  0,  NIL,  &f i rstAtom ) ; 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Creating  and  Disposing  of  Atom  Containers"  (V-2766) 

Related  Java  Methods 

qui ckti me . std .movi es . AtomContai ner . AtomContai ner ( ) , 
qui ckti me . std .musi c .Atomi c Instrument . Atomi c Instrument! ) , 
qui ckti me . std .movi es . Effects  Li st . Effects  Li st ( ) 


QTNewGWorld 


Creates  an  offscreen  graphics  world  that  may  have  a  non-Macintosh  pixel  format. 


OSErr  QTNewGWorld 
GWorl dPtr 
OSType 
const  Rect 
CTabHandl e 
GDHandl e 
GWorl  d FI  ags 


( 

*offscreenGWorl d , 
Pi xel Format , 
*boundsRect , 
cTabl e , 
aGDevi ce , 
f 1 ags  ) ; 


offscreenGWorl d 

On  return,  a  pointer  to  the  offscreen  graphics  world  created  by  this  routine. 


11-1204 
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QTNewGWorld 


Pi xel Format 

The  new  graphics  world's  pixel  format;  see  "Pixel  Formats"  (IV-2686).  This 
function  won't  work  with  planar  pixel  formats;  use  QTNewGWorl  dFromPtr 
(11-1206)  instead.  See  the  ICMPixel  Formatlnfo  (IV-2282)  structure  for  a 
discussion  of  planar  and  chunky  formats. 

boundsRect 

A  pointer  to  the  boundary  rectangle  and  port  rectangle  for  the  offscreen  pixel 
map.  This  becomes  the  boundary  rectangle  for  the  GDevi ce  structure,  if  this 
function  creates  one.  If  you  specify  0  in  the  PixelFormat  parameter,  the  function 
interprets  the  boundaries  in  global  coordinates  that  it  uses  to  determine  which 
screens  intersect  the  rectangle.  It  then  uses  the  pixel  format,  color  table,  and 
GDev i ce  structure  from  the  screen  with  the  greatest  pixel  depth  from  among  all 
screens  whose  boundary  rectangles  intersect  this  rectangle.  Typically,  your 
application  supplies  this  parameter  with  the  port  rectangle  for  the  onscreen 
window  into  which  your  application  will  copy  the  pixel  image  from  this 
offscreen  world. 

cTabl e 

A  handle  to  a  Col  orTabl  e  (IV-2210)  structure.  If  you  pass  N I L  in  this  parameter, 
the  function  uses  the  default  color  table  for  the  pixel  format  that  you  specify  in 
the  Pi  xel  Format  parameter.  If  you  set  the  Pi  xel  Format  parameter  to  0,  the 
function  ignores  the  cTabl  e  parameter  and  instead  copies  and  uses  the  color 
table  of  the  graphics  device  with  the  greatest  pixel  depth  among  all  graphics 
devices  whose  boundary  rectangles  intersect  the  rectangle  that  you  specify  in 
the  boundsRect  parameter.  If  you  use  this  function  on  a  computer  that  supports 
only  basic  QuickDraw,  you  may  specify  only  N I L  in  this  parameter. 

aGDevi ce 

A  handle  to  a  GDevi  ce  (IV-2264)  structure  that  is  used  only  when  you  specify 
the  noNewDevi  ce  flag  in  the  f  1  ags  parameter,  in  which  case  the  function  attaches 
this  structure  to  the  new  offscreen  graphics  world.  If  you  set  the  Pi  xel  Format 
parameter  to  0,  or  if  you  do  not  set  the  noNewDevi  ce  flag,  the  function  ignores 
this  parameter,  so  you  should  set  it  to  N I L.  If  you  set  the  Pi  xel  Format  parameter 
to  0,  the  function  uses  the  GDevi  ce  structure  for  the  graphics  device  with  the 
greatest  pixel  depth  among  all  graphics  devices  whose  boundary  rectangles 
intersect  the  rectangle  that  you  specify  in  the  boundsRect  parameter.  You  should 
pass  N I L  in  this  parameter  if  the  computer  supports  only  basic  QuickDraw. 
Generally,  your  application  should  never  create  GDevi  ce  structures  for  offscreen 
graphics  worlds. 

fl  ags 

Constants  (see  below)  that  identify  options  available  to  your  application.  You 
can  set  a  combination  of  these  flags.  If  you  don't  wish  to  use  any  of  them,  pass 
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0  in  this  parameter.  In  this  case  the  default  behavior  is  to  create  an  offscreen 
graphics  world  where  the  base  address  for  the  offscreen  pixel  image  is 
unpur geable,  the  graphics  world  uses  an  existing  GDevi  ce  structure  (if  you  pass 
0  in  the  depth  parameter)  or  creates  a  new  GDevi  ce  structure,  it  uses  memory  in 
your  application  heap,  and  it  allows  graphics  accelerators  to  cache  the  offscreen 
pixel  image. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

pi xPurge 

Make  base  address  for  the  offscreen  pixel  image  purgeable. 
noNewDevi ce 

Do  not  create  an  offscreen  GDevi  ce  structure. 
useTempMem 

Create  a  base  address  for  the  offscreen  pixel  image  in  temporary  memory. 
keepLocal 

Keep  the  offscreen  pixel  image  in  main  memory  where  it  cannot  be  cached  to  a 
graphics  accelerator  card. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Related  Java  Methods 

qui cktime.qd .QDGraphi cs .QDGraphi cs ( ) 


QTNewGWorldFromPtr 


Wraps  a  graphics  world  and  pixel  map  structure  around  an  existing  block  of 
memory  containing  an  image. 


OSErr  QTNewGWor 
GWorl dPtr 
OSType 
const  Rect 
CTabHandl e 
GDHandl e 
GWorl  d FI  ags 
voi  d 
1  ong 


dFromPtr  ( 

*gw, 

pi xel Format , 
*boundsRect , 
cTabl e , 
aGDevi ce , 
fl ags , 
*baseAddr , 
rowBytes  ) ; 
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gw 

On  entry,  a  pointer  that  isn't  going  to  change  during  the  lifetime  of  the  allocated 
graphics  world.  On  return,  this  pointer  references  the  offscreen  graphics  world 
created  by  this  function, 
pi xel Format 

The  new  graphics  world's  pixel  format;  see  "Pixel  Formats"  (IV-2686).  This 
function  won't  work  with  planar  pixel  formats;  see  the  I  CM  Pi  xel  Format  Info 
(IV-2282)  structure  for  a  discussion  of  planar  and  chunky  formats. 

boundsRect 

A  pointer  to  the  boundary  rectangle  and  port  rectangle  for  the  offscreen  pixel 
map.  This  becomes  the  boundary  rectangle  for  the  GDevi  ce  structure,  if  this 
function  creates  one.  If  you  specify  0  in  the  pixelFormat  parameter,  the  function 
interprets  the  boundaries  in  global  coordinates  that  it  uses  to  determine  which 
screens  intersect  the  rectangle.  It  then  uses  the  pixel  format,  color  table,  and 
GDev i ce  structure  from  the  screen  with  the  greatest  pixel  depth  from  among  all 
screens  whose  boundary  rectangles  intersect  this  rectangle.  Typically,  your 
application  supplies  this  parameter  with  the  port  rectangle  for  the  onscreen 
window  into  which  your  application  will  copy  the  pixel  image  from  this 
offscreen  world. 
cTabl e 

A  handle  to  a  Col  orTabl  e  (IV-2210)  structure.  If  you  pass  N I L  in  this  parameter, 
the  function  uses  the  default  color  table  for  the  pixel  format  that  you  specify  in 
the  pi  xel  Format  parameter.  If  you  set  the  pi  xel  Format  parameter  to  0,  the 
function  ignores  the  cTabl  e  parameter  and  instead  copies  and  uses  the  color 
table  of  the  graphics  device  with  the  greatest  pixel  depth  among  all  graphics 
devices  whose  boundary  rectangles  intersect  the  rectangle  that  you  specify  in 
the  boundsRect  parameter.  If  you  use  this  function  on  a  computer  that  supports 
only  basic  QuickDraw,  you  may  specify  only  N I L  in  this  parameter. 
aGDevi ce 

A  handle  to  a  GDevi  ce  (IV-2264)  structure  that  is  used  only  when  you  specify 
the  noNewDevi  ce  flag  in  the  f  1  ags  parameter,  in  which  case  the  function  attaches 
this  structure  to  the  new  offscreen  graphics  world.  If  you  set  the  pi  xel  Format 
parameter  to  0,  or  if  you  do  not  set  the  noNewDevi  ce  flag,  the  function  ignores 
this  parameter,  so  you  should  set  it  to  N I L.  If  you  set  the  pi  xel  Format  parameter 
to  0,  the  function  uses  the  GDevi  ce  structure  for  the  graphics  device  with  the 
greatest  pixel  depth  among  all  graphics  devices  whose  boundary  rectangles 
intersect  the  rectangle  that  you  specify  in  the  boundsRect  parameter.  You  should 
pass  N I L  in  this  parameter  if  the  computer  supports  only  basic  QuickDraw. 
Generally,  your  application  should  never  create  GDevi  ce  structures  for  offscreen 
graphics  worlds. 
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fl  ags 

A  constant  (see  below)  that  identifies  an  option  available  to  your  application.  If 
you  don't  wish  to  use  this  option,  pass  0  in  this  parameter.  In  this  case  the 
default  behavior  is  to  create  an  offscreen  graphics  world  that  uses  an  existing 
GDevi  ce  structure  (if  you  pass  0  in  the  depth  parameter)  or  creates  anew  GDevi ce 
structure.  Most  constants  used  in  creating  a  GWorl  d  are  irrelevant  for  this 
function,  as  its  purpose  is  to  wrap  a  GWorl  d  around  an  existing  block  of  pixels 
rather  than  to  define  and  create  a  pi  xmap. 
baseAddr 

The  base  address  for  the  pixel  data. 
rowBytes 

The  total  size  of  the  pixel  data  divided  by  the  height  of  the  pixel  map.  In  other 
words,  the  number  of  bytes  in  one  row  of  pixels  or  the  number  of  bytes  between 
vertically  adjacent  pixels. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

noNewDevi ce 

Do  not  create  an  offscreen  GDevi  ce  structure. 

Discussion 

This  function  wraps  a  GWorl  d  around  an  existing  pixel  map.  Note  that  it  does  not 
copy  the  pi  xmap.  A  subsequent  call  to  Di  sposeGWorl  d  will  not  dispose  of  the  pixel 
map;  it  will  only  dispose  of  the  GWorl  d  wrapper.  It  is  the  caller's  responsibility  to 
dispose  of  the  pixel  map. 

You  can  use  this  call  to  allocate  an  offscreen  graphics  world  using  special  memory 
(such  as  on  a  video  card).  If  you  have  an  image  in  memory  that  belong  to  something 
else  (a  hardware  screen  buffer,  a  3D  card,  or  another  file  format  or  program),  you 
can  use  this  function  to  wrap  a  graphics  world  around  the  image  and  then  use 
QuickTime  calls  on  that  graphics  world  to  compress  it,  scale  it,  draw  to  it,  and  so  on. 
If  your  new  graphics  world  has  a  planar  pixel  format,  you  must  use  this  call  instead 
of  QTNewGWorld  (11-1204). 

Special  Considerations 

Do  not  unlock  the  pixels  of  the  allocated  graphics  world.  If  your  original  pixels  are 
from  another  graphics  world  then  you  must  ensure  that  the  source  pixels  are  locked. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 
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QTNewTween 

Undocumented 

OSErr  QTNewTween  ( 

QTTweener 
QTAtomContai ner 
QTAtom 
TimeVal ue 

tween 

A  pointer  to  a  pointer  to  a  QTTweenerRecord  (IV-2391)  structure, 
contai ner 

Undocumented 

tweenAtom 

Undocumented 

maxTime 

Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

QTN  extChild  AnyT  y  pe 

Returns  the  next  atom  in  the  child  list  of  the  specified  parent  atom. 

OSErr  QTNextChi 1 dAnyType  ( 

QTAtomContai ner  container, 

QTAtom  parentAtom, 

QTAtom  currentChi 1 d , 

QTAtom  *nextChild  ); 

contai ner 

The  atom  container  that  contains  the  parent  atom. 


*tween , 
container, 
tweenAtom, 
maxTime  ): 
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parentAtom 

The  parent  atom  for  this  operation. 
currentChi 1 d 

The  last  atom  retrieved  by  this  function.  To  retrieve  the  first  atom  in  the  child 
list,  set  the  value  of  currentChi  1  d  to  0. 

nextChi 1 d 

A  pointer  to  an  uninitialized  QT  atom  data  structure.  On  return,  the  data 
structure  contains  the  offset  of  the  next  atom  in  the  child  list  after  the  atom 
specified  by  currentChi  1  d,  or  0  if  the  atom  specified  by  currentChi  1  d  was  the 
last  atom  in  the  list. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

You  can  call  this  function  to  iterate  through  all  the  atoms  in  a  parent  atom's  child 
list,  regardless  of  their  types  and  IDs. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Retrieving  Atoms  and  Atom  Data"  (V-2768) 

Related  Java  Methods 

qui ckti me . std .movi es . AtomContai ner . nextChi 1 dAnyTypet ) 


QTParseT  extHREF 


Undocumented 

OSErr  QTParseTextHREF  ( 

char  *href, 

SInt32  hrefLen, 

QTAtomContai ner  inContainer, 

QTAtomContai ner  *outContai ner  ); 


href 

A  pointer  to  an  HREF  string. 
hrefLen 

The  length  of  the  HREF  string. 
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i nContai ner 

Undocumented 
outContai ner 

Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


QTPhotoDef  ineHuf  f  manT  able 


Defines  a  Huffman  table. 


Component  Res ul t  QTPhotoDef i neHuffmanTabl e 


Componentlnstance 
short 
Bool ean 
unsigned  char 
unsigned  char 


codec , 

componentNumber , 
i  sDC , 

*1 engthCounts , 
*values  ); 


( 


codec 

Identifies  your  connection  to  the  image  compressor  component. 
componentNumber 

Specifies  a  color  component.  If  0,  the  luminance  Huffman  table  is  set.  If  1,  the 
chrominance  Huffman  table  is  set. 


i  sDC 

If  TRUE,  the  DC  Huffman  table  is  set.  If  FALSE,  the  AC  Huffman  table  is  set. 
1 engthCounts 

A  pointer  to  an  array  of  16  length  counts, 
val ues 

A  pointer  to  an  array  of  Huffman  values. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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Discussion 

This  function  lets  you  define  a  Huffman  table  to  be  used  in  future  JPEG 
compression  operations.  Normally  the  JPEG  image  compressor  components  use  the 
default  Huffman  tables  as  specified  in  sections  K.3  through  K.6  of  the  JPEG 
specification.  You  can  use  this  function  to  override  the  default  tables. 

Special  Considerations 

This  call  is  supported  only  by  the  Photo  JPEG  and  Motion  JPEG  compressors.  Only 
advanced  programmers  will  need  to  use  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.  h 


QTPhotoDef  ineQuantizationT  able 

Specifies  a  custom  quantization  table. 

ComponentResul t  QTPhotoDefineQuantizationTable  ( 

Componentlnstance  codec, 

short  componentNumber , 

unsigned  char  *table  ); 

codec 

Identifies  your  connection  to  the  image  compressor  component. 
componentNumber 

If  0,  the  luminance  quantization  table  is  set.  If  1,  the  chrominance  quantization 
table  is  set. 

tabl  e 

A  pointer  to  an  array  of  64  quantization  values. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

By  default,  the  JPEG  compressors  select  quantization  tables  based  on  quality 
settings.  This  function  lets  you  override  these  tables  with  tables  of  your  own  choice. 

Special  Considerations 

This  call  is  only  supported  by  the  Photo  JPEG  and  Motion  JPEG  compressors.  Only 
advanced  programmers  will  need  to  use  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  ImageCodec.h 


QTPhotoSetRestartlnterval 

Specifies  the  restart  interval  to  use  in  future  JPEG  compression  operations. 

ComponentResul t  QTPhotoSetRestartlnterval  ( 

Componentlnstance  codec, 

unsigned  short  restartlnterval  ); 

codec 

Identifies  your  connection  to  the  image  compressor  component, 
restartlnterval 

The  new  restart  interval.  Pass  0  to  tell  the  compressor  not  to  insert  restart 
markers  in  the  data  stream. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

By  default,  the  JPEG  compressor  components  do  not  insert  restart  markers  in  the 
compressed  data  stream  unless  the  "optimize  for  streaming"  setting  is  selected. 

Special  Considerations 

This  call  is  supported  only  by  the  Photo  JPEG  and  Motion  JPEG  compressors.  Only 
advanced  programmers  will  need  to  use  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.h 


QTPhotoSetSampling 


Specifies  the  chrominance  downsampling  ratio  to  use  in  future  JPEG  compression 
operations. 

ComponentResul t  QTPhotoSetSampling  ( 


Componentlnstance 

codec 

short 

yH, 

short 

y  v. 

short 

cbH , 

short 

cbV , 
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short  crH, 

short  crV  ) ; 

codec 

Identifies  your  connection  to  the  image  compressor  component. 
yH 

The  number  of  horizontal  luminance  blocks  to  put  in  each  macroblock, 
yv 

The  number  of  vertical  luminance  blocks  to  put  in  each  macroblock. 

cbH 

The  number  of  horizontal  chroma  blue  blocks  to  put  in  each  macroblock. 

cbV 

The  number  of  vertical  chroma  blue  blocks  to  put  in  each  macroblock. 

crH 

The  number  of  horizontal  chroma  red  blocks  to  put  in  each  macroblock. 

crV 

The  number  of  vertical  chroma  red  blocks  to  put  in  each  macroblock. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

By  default,  the  Photo  JPEG  compressor  uses  4:1:1  chroma  downsampling  and  the 
Motion  JPEG  compressors  use  4:2:2  chroma  downsampling  for  most  quality 
settings.  For  codecLossl  essQual  i  ty,  both  compressors  disable  chroma 
downsampling.  Currently  the  only  supported  downsampling  ratios  are  none  (pass 
1,1,1,1,1,1),  4:2:2  (pass  2,1,1,1,1,1)  and  4:1:1  (pass  2,2,1,1,1,1). 

Special  Considerations 

This  call  is  supported  only  by  the  Photo  JPEG  and  Motion  JPEG  compressors.  Only 
advanced  programmers  will  need  to  use  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCodec.  h 


QTRegisterAccessKey 

Registers  an  access  key. 

OSErr  QTRegisterAccessKey  ( 
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Str255  accessKeyType, 

long  flags. 

Handle  accessKey  ); 


accessKeyType 

The  access  key  type  of  the  key  to  be  registered, 
fl  ags 

Flags  that  specify  the  operation  of  this  function.  To  register  a  system  access  key, 
set  the  kAccessKeySystemFl  ag  flag  (see  below).  To  register  an  application  access 
key,  set  this  parameter  to  0. 

accessKey 

A  handle  to  the  key  to  be  registered. 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error  or  if 
the  access  key  has  already  been  registered. 


flags  Constant 

kAccessKeySystemFl  ag 

Set  to  1  to  register  a  system  access  key. 


Discussion 

Most  access  keys  are  strings.  A  string  stored  in  the  accessKey  handle  does  not 
include  a  trailing  zero  or  leading  length  byte;  to  get  the  length  of  the  string,  get  the 
size  of  the  handle.  If  the  access  key  has  already  been  registered,  no  error  is  returned, 
and  the  request  is  simply  ignored. 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Registering  and  Unregistering  Access  Keys"  (V-2771) 


QTRemoveAtom 


Removes  an  atom  and  its  children  from  the  specified  atom  container. 

OSErr  QTRemoveAtom  ( 

QTAtomContai ner  container, 

QTAtom  atom  ); 


contai ner 

The  atom  container  for  this  operation.  The  atom  container  must  not  be  locked. 
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QTRemoveChildren 


atom 

The  atom  to  be  removed  from  the  container. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

You  call  this  function  to  remove  a  particular  atom  and  its  children  from  an  atom 
container.  To  remove  all  the  atoms  in  an  atom  container,  you  should  use 
QTRemoveChildren  (11-1216). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Removing  Atoms  From  an  Atom  Container"  (V-2770) 

Related  Java  Methods 

qui ckti me . std .movi es . AtomContai ner . removeAtom( ) 


QTRemoveChildren 


Removes  all  the  children  of  an  atom  from  the  specified  atom  container. 

OSErr  QTRemoveChildren  ( 

QTAtomContai ner  container, 

QTAtom  atom  ) ; 

contai ner 

The  atom  container  for  this  operation.  The  atom  container  must  not  be  locked. 

atom 

The  atom  whose  children  should  be  removed.  To  remove  all  the  atoms  in  the 
atom  container,  pass  a  value  of  kParentAtomlsContai ner. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Removing  Atoms  From  an  Atom  Container"  (V-2770) 

Related  Java  Methods 

qui cktime . std .movi es . AtomContai ner . removeChi 1 dren( ) 


QTReplaceAtom 

Replaces  the  contents  of  an  atom  and  its  children  with  a  different  atom  and  its 
children. 

OSErr  QTReplaceAtom  ( 

QTAtomContai ner 
QTAtom 

QTAtomContai ner 
QTAtom 

targetContai ner 

The  atom  container  that  contains  the  atom  to  be  replaced.  The  atom  container 
must  not  be  locked. 
targetAtom 

The  atom  to  be  replaced, 
repl acementContai  ner 

The  atom  container  that  contains  the  replacement  atom, 
repl acementAtom 

The  replacement  atom. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

The  target  atom  and  the  replacement  atom  must  be  of  the  same  type.  The  target 
atom  maintains  its  original  atom  ID.  This  function  does  not  modify  the  replacement 
container. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Copying  Existing  Atoms"  (V-2767) 


targetContainer, 
targetAtom, 
repl acementContai ner , 
repl acementAtom  ); 
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QTSAllocBuffer 


Related  Java  Methods 

qui ckti me . std .  movi es . AtomContai ner . repl aceAtom( ) 


QTSAllocBuffer 

Allocates  a  QuickTime  streaming  stream  buffer. 

QTSStreamBuffer  *  QTSAllocBuffer  ( 

SInt32  size  ) ; 

si  ze 

The  size  of  the  buffer  to  be  allocated. 
function  result  A  QTSStreamBuffer  (IV-2385)  structure 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


QTSAllocMemPtr 

Undocumented 

QTSMemPtr  QTSAllocMemPtr  ( 
UInt32  inByteCount, 

SInt32  i n FI ags  ) ; 

i nByteCount 

Undocumented 
i  n FI  ags 

Undocumented 

function  result  Undocumented 

inFlags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  4. 
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Inside  QuickTime:  Function  l-Q 


QTScheduledBandwidthRelease 


Programming  Info 

C  interface  file:  Qui ckTi  meStreami  ng .  h 


QTScheduledBandwidthRelease 

Undocumented 

OSErr  QTScheduledBandwidthRelease  ( 

QTSchedul edBandwi dth Reference  sbwRef , 

long  flags  ); 

sbwRef 

A  pointer  to  an  opaque  data  structure, 
fl  ags 

Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

flags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


QTScheduledBandwidthRequest 


Undocumented 


schedul eRec , 

noti f i cationCal 1  back, 

*ref con , 

*sbwRef , 
flags  ); 


OSErr  QTScheduledBandwidthRequest  ( 
QTSchedul edBandwi dth Ptr 
QTBandwi  dthNoti  f  i  cati  onllPP 
voi  d 

QTSchedul edBandwi dth Reference 
1  ong 


schedul eRec 

A  pointer  to  a  QTSchedul  edBandwi  dthRecord  (IV-2366)  structure. 


Inside  QuickTime:  Function  l-Q 
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QTSCopyMessage 


notificationCallback 

A  Universal  Procedure  Pointer  that  accesses  a  QTBandwi  dthNoti  f  1  cati  onProc 
(III— 2124)  callback, 
refcon 

A  reference  constant  to  be  passed  to  your  callback.  Use  this  parameter  to  point 
to  a  data  structure  containing  any  information  your  function  needs. 

sbwRef 

A  pointer  to  an  opaque  data  structure, 
fl  ags 

Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

flags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es .  h 


QTSCopyMessage 

Undocumented 

QTSStreamBuffer  *  QTSCopyMessage  ( 

QTSStreamBuffer  *i nStreamBuffer  ); 

1 nStreamBuffer 

A  pointer  to  a  QTSStreamBuffer  (IV-2385)  structure. 
function  result  A  pointer  to  a  QTSStreamBuffer  (IV-2385)  structure. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 
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Inside  QuickTime:  Function  l-Q 


QTSDisposePresentation 


QTSDisposePresentation 

Disposes  of  a  QuickTime  streaming  presentation. 

OSErr  QTSDisposePresentation  ( 

QTSPresentation  inPresentation, 

SInt32  inFlags  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentation  Re  cord  (IV-2379)  structure  that  defines  the 
presentation  to  be  disposed. 

i  n  FI  ags 

Flags  governing  the  disposal  of  the  presentation.  Currently,  no  flags  are 
defined;  set  this  parameter  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSDisposeStatHelper 


Disposes  of  a  QuickTime  streaming  statistics  helper  that  was  previously  created  by 
QTSNewStatHel  per  (11-1255). 

OSErr  QTSDisposeStatHelper  ( 

QTSStatHel per  inStatHelper  ); 

i nStatHel per 

A  pointer  to  a  QTSStatHel  per  Re  cord  (IV-2384)  structure  that  defines  the 
statistics  helper  to  be  disposed. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


Inside  QuickTime:  Function  l-Q 
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QTSDisposeStream 


QTSDisposeStream 

Disposes  of  a  QuickTime  streaming  stream. 

OSErr  QTSDisposeStream  ( 

QTSStream  inStream, 

SInt32  i nFl ags  ) ; 

i nStream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure  that  defines  a  stream  to  be 
disposed, 
i  nFl  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inFlags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


QTSDuplicateMessage 


Undocumented 

OSErr  QTSDuplicateMessage  ( 

QTSStreamBuffer  *inMessage, 

SInt32  inFlags, 

QTSStreamBuffer  **outDupl i catedMessage  ); 

i nMessage 

Undocumented 
i  nFl  ags 

Undocumented 
outDupli catedMessage 
Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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Inside  QuickTime:  Function  l-Q 


QTSDupMessage 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSDupMessage 


Undocumented 

QTSStreamBuf f er  *  QTSDupMessage  ( 

QTSStreamBuf fer  *i nStreamBuf fer  ); 

i nStreamBuf fer 

A  pointer  to  a  QTSStreamBuffer  (IV-2385)  structure. 
function  result  A  pointer  to  a  QTSStreamBuffer  (IV-2385)  structure. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSetAtomData 


Changes  the  data  of  a  leaf  atom. 

OSErr  QTSetAtomData  ( 

QTAtomContai ner 
QTAtom 
1  ong 
void 

contai ner 

The  atom  container  that  contains  the  atom  to  be  modified. 


contai ner, 
atom, 
dataSi ze , 
*atomData  ); 


atom 

The  atom  to  be  modified. 
dataSi ze 

The  length,  in  bytes,  of  the  data  pointed  to  by  the  atomData  parameter. 
atomData 

A  pointer  to  the  new  data  for  the  atom. 


Inside  QuickTime:  Function  l-Q 


11-1223 


QTSetAtomData 


function  result  Only  leaf  atoms  contain  data;  this  function  returns  an  error  if  you 

pass  it  to  a  nonleaf  atom.  You  can  access  Movie  Toolbox  error  returns 
through  GetMovi  es Error  (I — 492)  and  Ge t Mo viesSticky Error  (1-494),  as 
well  as  in  the  function  result.  See  "Error  Codes"  (IV-2663). 

Discussion 

You  call  this  function  to  replace  a  leaf  atom's  data  with  new  data.  The  atom 
container  specified  by  the  contai  ner  parameter  should  not  be  locked.  The  following 
code  illustrates  using  this  function  to  update  an  atom  container  that  describes  a 

sprite: 

//  QTSetAtomData  coding  example 

OSErr  SetSpri teData  ( QTAtomContai ner  sprite,  Point  *location, 
short  *visible,  short  *layer,  short  *imagelndex) 

{ 

OSErr  err  =  noErr; 

QTAtom  propertyAtom ; 

//  if  the  sprite's  visible  property  has  a  new  value 
if  (visible) 

{ 

//  retrieve  the  atom  for  the  visible  property 
//  --  if  none  exists,  insert  one 
if  ((propertyAtom  =  QTFi ndChi 1 dBy Index  (sprite, 

kParentAtomlsContainer ,  kSpri tePropertyVi si bl e ,  1, 

NIL))  ==  0) 

FailOSErr  ( QTInsertChi 1 d  (sprite,  kParentAtomlsContainer, 
kSpri tePropertyVi si bl e ,  1,  1,  si zeof( short ) ,  visible, 

NIL)) 

//  if  an  atom  does  exist,  update  its  data 
el  se 

FailOSErr  (QTSetAtomData  (sprite,  propertyAtom, 
sizeof(short) ,  visible)); 

} 

Special  Considerations 

This  function  may  move  memory;  if  the  pointer  specified  by  the  atomData  parameter 
is  a  dereferenced  handle,  you  should  lock  the  handle. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Inside  QuickTime:  Function  l-Q 


QTSetAtomID 


Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Modifying  Atoms"  (V-2769) 

Related  Java  Methods 

qui cktime . std .movi es . AtomContai ner . setAtomData ( ) 


QTSetAtomID 


Changes  the  ID  of  an  atom. 

OSErr  QTSetAtomID  ( 

QTAtomContai ner 
QTAtom 
QTAtomID 

contai ner 

The  atom  container  for  this  operation. 

atom 

The  atom  to  be  modified.  You  cannot  change  the  ID  of  the  container  by  passing 
0  for  the  atom  parameter. 
newID 

The  new  ID  for  the  atom.  You  cannot  change  an  atom's  ID  to  an  ID  already 
assigned  to  a  sibling  atom  of  the  same  type. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Modifying  Atoms"  (V-2769) 

Related  Java  Methods 

qui cktime . std .movi es .AtomContai ner . setAtomIDI ) 


contai ner, 
atom, 
newID  ); 


QTSetDDObject 


Sets  the  Windows  DirectDraw  object  currently  in  use  by  QuickTime. 


Inside  QuickTime:  Function  l-Q 
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QTSetDDPrimarySurface 


OSErr  QTSetDDObject  ( 

void  *1 pNewDDObject  ); 

1 pNewDDObject 

The  DirectDraw  object. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  useful  for  developers  who  want  to  call  Windows  DirectDraw 
methods  directly. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML.h 

See  Also 

For  the  corresponding  get  function,  see  QTGetDDObject  (11-1174). 

QTSetDDPrimarySurface 

Sets  the  primary  Windows  DirectDraw  surface  used  by  QuickTime. 

OSErr  QTSetDDPrimarySurface  ( 

void  *1 pNewDDSurface , 

unsi gned  1 ong  f 1 ags  ) ; 

1 pNewDDSurface 

A  pointer  to  a  DirectDraw  surface, 
fl  ags 

Contains  flags  (see  below)  that  control  the  set  operation. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

kDDSurfaceLocked 

If  set,  QuickTime  won't  attempt  to  lock  the  graphics  device  when  blitting  to  the 
Pi  xMap. 

kDDSurfaceStati c 

If  set,  QuickTime  assumes  that  windows  on  this  device  do  not  move. 


11-1226 


Inside  QuickTime:  Function  l-Q 


QTSetPixMapHandleGammaLevel 


Discussion 

This  function  is  useful  for  multimedia  developers  who  want  to  wrap  QuickTime 
around  surfaces  they  have  already  created. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML .  h 


QTSetPixMapHandleGammaLevel 


Sets  the  gamma  level  of  a  pixel  map. 

OSErr  QTSetPixMapHandl eGamma Level  ( 
PixMapHandle  pm, 

Fi xed  gamma  Level ) ; 


pm 

A  handle  to  a  Pi  xMap  (IV-2332)  structure  that  has  a  Pi xMapExtensi  on  (IV-2335) 
structure. 

gammaLevel 

The  new  gamma  level. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  does  not  convert  the  contents  of  the  Pi  xMap  structure.  A  typical  usage 
would  be  to  set  the  gamma  level  of  a  pixel  map  before  compressing  it  so  that  the 
codec  knows  if  it  needs  to  do  additional  gamma  correcting  when  compressing. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

See  Also 

For  the  corresponding  get  function,  see  QTGetPi  xMapHandl  eGamma  Level  (11-1180). 


QTSetPixMapHandleRequestedGammaLevel 

Sets  the  requested  gamma  level  of  a  pixel  map. 


Inside  QuickTime:  Function  l-Q 
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QTSetPixMapHandleRowBytes 


OSErr  QTSetPixMapHandleRequestedGammaLevel  ( 
PixMapHandle  pm, 

Fixed  requestedGammaLevel  ) ; 


pm 

A  handle  to  a  Pi xMap  (IV-2332)  structure  that  has  a  Pi  xMapExtensi  on  (IV-2335) 
structure. 

requestedGammaLevel 

A  specified  gamma  level  or  a  constant  (see  below). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

requestedGammaLevel  Constants 

kQTUsePl atformDefaul  t Gamma  Level 

The  default  gamma  level  for  the  platform  (Macintosh  is  1.8,  Windows  is  2.5). 
kQTUseSourceGamma Level 

Leave  the  pixel  map  with  the  gamma  level  of  the  source  data,  instead  of 
converting  it. 

kQTCCIR601Vi deoGamma Level 

Gamma  2.2,  for  ITU-R  BT.601  based  video. 

Discussion 

This  function  does  not  convert  the  contents  of  the  Pi  xMap  structure.  A  typical  usage 
would  be  to  set  the  requested  gamma  level  of  a  pixel  map  before  decompressing  so 
that  the  codec  knows  what  gamma  correction  is  necessary  when  decompressing 
into  the  Pi  xMap  structure.  The  resulting  gamma  level  can  then  be  found  by  calling 
QTGetPi  xMapHandl  eGamma  Level  (11-1180). 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

See  Also 

For  the  corresponding  get  function,  see  QTGetPi  xMapHandl  eRequestedGamma  Level 
(11-1180). 

QTSetPixMapHandleRowBytes 

Sets  the  rowBytes  value  for  a  pixel  map  accessed  by  a  handle. 

OSErr  QTSetPixMapHandleRowBytes  ( 

PixMapHandle  pm. 


11-1228 


Inside  QuickTime:  Function  l-Q 


QTSetPixMapPtrGammaLevel 


long  rowBytes  ); 

pm 

A  handle  to  a  Pi  xMap  (IV-2332)  structure. 
rowBytes 

The  rowBytes  value  to  be  set. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

See  Also 

For  the  corresponding  get  function,  see  QTGetPi xMapHandl  eRowBytes  (11-1181). 


QTSetPixMapPtrGammaLevel 


Sets  the  gamma  level  of  a  pixel  map. 

OSErr  QTSetPixMapPtrGammaLevel  ( 
PixMapPtr  pm. 

Fixed  gammaLevel); 


pm 

A  pointer  to  a  Pi  xMap  (IV-2332)  structure  that  has  a  Pi  xMapExtensi  on  (IV-2335) 
structure. 
gammaLevel 

The  new  gamma  level. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  does  not  convert  the  contents  of  the  Pi  xMap  structure.  A  typical  usage 
would  be  to  set  the  gamma  level  of  a  pixel  map  before  compressing  it  so  that  the 
codec  knows  if  it  needs  to  do  additional  gamma  correcting  when  compressing. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


Inside  QuickTime:  Function  l-Q 
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QTSetPixMapPtrRequestedGammaLevel 


See  Also 

For  the  corresponding  get  function,  see  QTGetPixMapPtrGammaLevel  (11-1181). 


QTSetPixMapPtrRequestedGammaLevel 


Sets  the  requested  gamma  level  of  a  pixel  map. 

OSErr  QTSetPixMapPtrRequestedGammaLevel  ( 
PixMapPtr  pm. 

Fixed  requestedGammaLevel); 


pm 

A  pointer  to  a  Pi  xMap  (IV-2332)  structure  that  has  a  Pi xMapExtensi  on  (IV-2335) 
structure. 

requestedGammaLevel 

A  specified  gamma  level  or  a  constant  (see  below). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

requestedGammaLevel  Constants 

kQTUsePl atformDefaul t Gamma  Level 

The  default  gamma  level  for  the  platform  (Macintosh  is  1.8,  Windows  is  2.5). 
kQTUseSourceGamma Level 

Leave  the  pixel  map  with  the  gamma  level  of  the  source  data,  instead  of 
converting  it. 

kQTCCIR601Vi deoGamma Level 

Gamma  2.2,  for  ITU-R  BT.601  based  video. 

Discussion 

This  function  does  not  convert  the  contents  of  the  Pi  xMap  structure.  A  typical  usage 
would  be  to  set  the  requested  gamma  level  of  a  pixel  map  before  decompressing  so 
that  the  codec  knows  what  gamma  correction  is  necessary  when  decompressing 
into  the  Pi  xMap  structure.  The  resulting  gamma  level  can  then  be  found  by  calling 
QTGetPi xMapPtrGamma Level  (11-1181). 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

See  Also 

For  the  corresponding  get  function,  see  QTGetPi xMapPtrRequestedGammaLevel 
(11-1182). 
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Inside  QuickTime:  Function  l-Q 


QTSetPixMapPtrRowBytes 


QTSetPixMapPtrRowBytes 


Sets  the  rowBytes  value  for  a  pixel  map  accessed  by  a  pointer. 

OSErr  QTSetPixMapPtrRowBytes  ( 

PixMapPtr  pm, 

long  rowBytes  ); 


pm 

A  pointer  to  a  Pi  xMap  (IV-2332)  structure. 
rowBytes 

The  rowBytes  value  to  be  set. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

See  Also 

For  the  corresponding  get  function,  see  QTGetPi  xMapPtrRowBytes  (11-1183). 


QTSFindMediaPacketizer 


Creates  a  list  of  media  packetizers  that  can  work  with  a  specified  sample  description 
and  meet  specified  criteria. 

OSErr  QTSFindMediaPacketizer  ( 

Medi aPacketi zerRequi rementsPtr 
Sampl eDescri pti onHandl e 
RTPPayl oadSortRequestPtr 
QTAtomContai ner 

i nPacketi zeri nf o 

A  pointer  to  a  Medi  aPacketi  zerRequi  rements  (IV-2308)  structure  that  specifies 
the  required  features  of  the  media  packetizers  you  are  looking  for. 

i nSampl eDescri pti on 

A  handle  to  a  Sampl  eDescri  pti  on  (IV-2414)  structure  that  specifies  the  media 
data  the  packetizer  needs  to  work  with. 


i nPacketi zeri nf o , 
i nSampl eDescri pti on  , 
inSortlnfo, 
*outPacketi zerLi st  ); 


Inside  QuickTime:  Function  l-Q 


11-1231 


QTSFindMediaPacketizerForPayloadID 


i nSortlnfo 

A  pointer  to  a  RTPPayl  oadSortRequest  (IV-2410)  structure  that  specifies  the  sort 
order  for  the  list  of  packetizers. 
outPacketi zerLi st 

On  entry,  a  pointer  to  a  handle  to  a  QT  atom  container.  On  return,  this  container 
will  be  filled  with  a  sorted  list  of  available  media  packetizers  that  meet  the 
specified  criteria.  Only  packetizers  that  have  the  features  specified  by 
i  nPacketi  zer  Info  will  be  listed.  The  list  will  be  sorted  in  the  order  specified  by 
1  nSortlnfo. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


QTSFindMediaPacketizerForPayloadID 


Creates  a  list  of  media  packetizers  for  a  specified  payload  number. 

OSErr  QTSFi ndMedi aPacketi zerForPayl oadID  ( 
long  payloadID, 

RTPPayl oadSortRequestPtr  i nSortlnfo , 

QTAtomContai ner  *outPacketi zerLi st  ); 

payl oadID 

An  IETF  payload  number, 
i nSortlnfo 

A  pointer  to  a  RTPPayl  oadSortRequest  (IV-2410)  structure  that  specifies  the  sort 
order  for  the  list  of  packetizers. 
outPacketi zerLi st 

On  entry,  a  pointer  to  a  handle  to  a  QT  atom  container.  On  return,  this  container 
will  be  filled  with  a  sorted  list  of  available  media  packetizers  for  the  specified 
payload  ID.  The  list  will  be  sorted  in  the  order  specified  by  i  nSortlnfo. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 
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Inside  QuickTime:  Function  l-Q 


QTSFindMediaPacketizerForPayloadName 


Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


QTSFindMediaPacketizerForPayloadName 

Creates  a  list  of  media  packetizers  for  a  specified  payload  name. 

OSErr  QTSFi ndMedi aPacketi zerForPayl oadName  ( 
const  char  *payl oadName , 

RTPPayl oadSortRequestPtr  in Sort  Info, 

QTAtomContai ner  *outPacketi zerLi st  ); 

payl oadName 

A  pointer  to  a  payload  name  string, 
i nSortlnfo 

A  pointer  to  a  RTPPayl  oadSortRequest  (IV-2410)  structure  that  specifies  the  sort 
order  for  the  list  of  packetizers. 

outPacketi zerLi st 

On  entry,  a  pointer  to  a  handle  to  a  QT  atom  container.  On  return,  this  container 
will  be  filled  with  a  sorted  list  of  available  media  packetizers  for  the  specified 
payload  name.  The  list  will  be  sorted  in  the  order  specified  by  i  nSortlnfo. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


QTSFindMediaPacketizerForT  rack 


Creates  a  list  of  media  packetizers  for  a  specified  movie  track  and  sample  data. 

OSErr  QTSFi ndMedi aPacketi zerForTrack  ( 

T  rack  i nT  rack, 

long  inSampl eDescri pti on  Index, 

RTPPayl oadSortRequestPtr  i nSortlnfo , 

QTAtomContai ner  *outPacketi zerLi st  ); 


Inside  QuickTime:  Function  l-Q 


11-1233 


QTSFindReassemblerForPayloadID 


i nT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 
inSampleDescriptionlndex 

The  value  of  the  dataRef  Index  field  of  the  Sampl  eDescri  pti  on  (IV-2414) 
structure  that  specifies  the  type  of  media  data  that  will  be  packetized. 

i nSortlnfo 

A  pointer  to  a  RTPPayl  oadSortRequest  (IV-2410)  structure  that  specifies  the  sort 
order  for  the  list  of  packetizers. 
outPacketi zerLi st 

On  entry,  a  pointer  to  a  handle  to  a  QT  atom  container.  On  return,  this  container 
will  be  filled  with  a  sorted  list  of  available  media  packetizers  for  the  specified 
track.  The  list  will  be  sorted  in  the  order  specified  by  i  nSortlnfo. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


QTSFindReassemblerForPayloadID 


Creates  a  list  of  streaming  reassemblers  for  a  specified  payload  number. 

OSErr  QTSFindReassemblerForPayloadID  ( 

UInt8  i nPayl oadID , 

RTPPayl oadSortRequest  *i nSortlnfo, 

QTAtomContai ner  *outReassembl erLi st  ); 

i nPayl oadID 

An  IETF  payload  number, 
i nSortlnfo 

A  pointer  to  a  RTPPayl  oadSortRequest  (IV-2410)  structure  that  specifies  the  sort 
order  for  the  list  of  reassemblers. 

outReassembl erLi st 

On  entry,  a  pointer  to  a  handle  to  a  QT  atom  container.  On  return,  this  container 
will  be  filled  with  a  sorted  list  of  available  reassemblers  for  the  specified  track. 
The  list  will  be  sorted  in  the  order  specified  by  i  nSortlnfo. 


11-1234 


Inside  QuickTime:  Function  l-Q 


QTSFindReassemblerForPayloadName 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


QTSFindReassemblerForPayloadName 

Creates  a  list  of  streaming  reassemblers  for  a  specified  payload  name. 

OSErr  QTSFi ndReassembl erForPayl oadName  ( 

const  char  *i nPayl oadName , 

RTPPayl oad Sort Request  *i nSortlnf o , 

QTAtomContai ner  *outReassembl erLi st  ); 

i nPayl oadName 

A  payload  name  string, 
i nSortlnfo 

A  pointer  to  a  RTPPayl  oadSortRequest  (IV-2410)  structure  that  specifies  the  sort 
order  for  the  list  of  reassemblers. 
outReassembl erLi  st 

On  entry,  a  pointer  to  a  handle  to  a  QT  atom  container.  On  return,  this  container 
will  be  filled  with  a  sorted  list  of  available  reassemblers  for  the  specified  track. 
The  list  will  be  sorted  in  the  order  specified  by  i  nSortlnfo. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


QTSFlattenMessage 


Undocumented 

QTSStreamBuf fer  *  QTSFlattenMessage  ( 

QTSStreamBuf f er  *i nStreamBuf fer  ); 


Inside  QuickTime:  Function  l-Q 


11-1235 


QTSFreeMessage 


i nStreamBuffer 

A  pointer  to  a  QTSStreamBuf  fer  (IV-2385)  structure. 
function  result  A  pointer  to  a  QTSStreamBuffer  (IV-2385)  structure. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


QTSFreeMessage 


Undocumented 

void  QTSFreeMessage  ( 

QTSStreamBuffer  *1 nStreamBuffer  ); 

1 nStreamBuffer 

A  pointer  to  a  QTSStreamBuffer  (IV-2385)  structure. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i  meStreami  ng .  h 


QTSGetErrorString 

Undocumented 

Boolean  QTSGetErrorString  ( 

SInt32  inErrorCode, 

UInt32  i nMaxErrorStri ngLength , 
char  *outErrorStri ng , 

SInt32  i n Ft ags  ) ; 

i nErrorCode 

Undocumented 
i nMaxErrorStri ngLength 
Undocumented 
outErrorStri ng 
Undocumented 


11-1236 


Inside  QuickTime:  Function  l-Q 


QTSG  etNetworkAppName 


i  n FI  ags 

Undocumented 

function  result  Undocumented 

inFlags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSGetNetworkAppName 

Gets  the  name  of  a  streaming  network  application. 

OSErr  QTSGetNetworkAppName  ( 

SInt32  inFlags, 

char  **outCStri ngPtr  ); 

i  n  FI  ags 

A  flag  (see  below)  that  determines  whether  the  application  name  is  a  full 
pathname. 

outCStri ngPtr 

A  Ptr  to  a  CStri  ngPtr;  see  MacTypes.h.  This  information  is  sent  back  to  servers 
in  HTTP  and  RTSP  headers,  so  they  can  work  out  client  statistics.  A  typical 
default  string  is  QTS  (qtver=4 . 1 . 1 ; cpu=PPC ; os=Mac  9.0.4). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inFlags  Constants 

kQTSNetworkAppNamelsFul  1  Name FI  a g 

The  application  name  is  a  full  pathname. 

Discussion 

Following  is  an  example  of  calling  this  function: 

Ptr  networkAppName  =  NIL; 

err  =  QTSGetNetworkAppNameCOL,  &networkAppName) ; 
printfC'The  NetworkAppName  is  % s",  networkAppName); 

Di sposePtrl networkAppName) ; 


Inside  QuickTime:  Function  l-Q 


11-1237 


QTSGetOrMakeStatAtomForStream 


//  This  call  prints 

//  The  NetworkAppName  is  QTS  ( qtver=4 . 1 . 1 ; cpu=PPC ; os=Mac  9.0.4) 

//  or 

//  The  NetworkAppName  is  QTS  ( qtver=4 . 0 ; os=Wi ndows  NT  4.0  Service  Pack  3) 
//  If  you  set  it  from  your  app,  that  will  be  returned  instead. 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 

See  Also 

For  the  corresponding  set  function,  see  QTSSetNetworkAppName  (11-1305). 


QTSGetOrMakeStatAtomForStream 


Gets  the  statistics  atom  for  a  stream  or  creates  a  new  statistics  atom  for  it. 

OSErr  QTSGetOrMakeStatAtomForStream  ( 

QTAtomContai ner  inContainer, 

QTSStream  inStream, 

QTAtom  *outParentAtom  ); 


i nContai ner 

An  atom  container  that  holds  the  statistics  atoms  for  the  specified  stream, 
i nStream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure  that  defines  a  stream. 
outParentAtom 

On  entry,  a  pointer  to  a  variable  of  type  QT Atom;  on  return,  this  variable  is  set  to 
the  atom  that  holds  the  statistics  for  this  stream.  If  no  such  atom  exists  for  that 
stream,  then  the  function  creates  a  statistics  atom. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

This  function  is  to  be  used  only  by  stream  components  to  put  stream  statistics  into 
an  atom  container;  applications  should  not  call  it. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i  meStreami  ng .  h 


11-1238 


Inside  QuickTime:  Function  l-Q 


QTSGetStreamPresentation 


QTSGetStreamPresentation 


Gets  the  presentation  for  a  stream. 

QTSPresentati on  QTSGetStreamPresentation  ( 

QTSStream  inStream  ); 

l nStream 

A  pointer  to  a  QTSStream  Re  cord  (IV-2387)  structure  that  defines  a  stream. 
function  result  A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSInitializeMediaParams 


Undocumented 

OSErr  QTSInitializeMediaParams  ( 

QTSMedi aParams  *inMedi aParams  ); 

i nMedi aParams 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSInsertStatistic 


Inserts  statistics  data  into  the  statistic  atom  for  a  stream. 

OSErr  QTSInsertStatistic  ( 

QTAtomContai ner  inContainer, 

QTAtom  i nParentAtom, 

OSType  inStatType, 


Inside  QuickTime:  Function  l-Q 


11-1239 


QTSInsertStatistic 


void  *inStatData, 

UInt32  inStatDataLength , 

OSType  inStatDataFormat , 

SInt32  i n FI ags  ) ; 

i nContai ner 

A  handle  to  the  atom  container  that  contains  the  statistic  atom, 
i nParentAtom 

The  atom  that  will  hold  a  new  atom  containing  the  specified  statistic  data, 
i nStatType 

A  constant  (see  below)  that  identifies  the  type  of  statistic  atom  to  insert  the  data 
into. 

i nStatData 

A  pointer  to  a  structure  containing  the  data  to  insert, 
i nStatDataLength 

The  length,  in  bytes,  of  the  statistic  data, 
i nStatDataFormat 

A  constant  (see  below)  that  identifies  the  format  of  the  inserted  statistic  atom, 
i  n FI  ags 

Currently  no  flags  are  defined;  pass  0  in  this  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inStatType  Constants 

kQTSStati sti csStreamAtomType 

Stream  atom  type;  value  is  '  s t  rm ' . 
kQTSStati sti csNameAtomType 

Name  atom  type;  value  is  'name ' . 
kQTSStati sti csDataFormatAtomType 

Data  format  atom  type;  value  is  '  f  rmt ' . 
kQTSStati sti csDataAtomType 

Data  atom  type;  value  is  '  data  ' . 
kQTSStati  sti  csllni  tsAtomType 

Units  atom  type;  value  is  'unit'. 
kQTSStati sti cs Uni tsNameAtomType 

Units  name  atom  type;  value  is  'unin'. 

inStatDataFormat  Constants 

kQTSStati sti csS I nt 32 Data  Format 

Signed  32-bit  integer  format;  value  is  '  s i  32 ' . 


11-1240 


Inside  QuickTime:  Function  l-Q 


QTSInsertStatisticName 


kQTSStati sti csUInt32DataFormat 

Unsigned  32-bit  integer  format;  value  is  '  u  1 3  2 ' . 
kQTSStati sti cs S I ntl6Data Format 

Signed  16-bit  integer  format;  value  is  '  s  i  1 6 ' . 
kQTSStati sti csUIntl6DataFormat 

Unsigned  16-bit  integer  format;  value  is  '  ui  16 ' . 
kQTSStati sti csFixedDataFormat 

Fixed  integer  numeric  format;  value  is  '  f  i  xd ' . 
kQTSStati sti csStri ng Data  Format 
String  format;  value  is  '  strg ' . 
kQTSStati sti csOSTypeDataFormat 

OSType  (32-bit)  format;  value  is  '  ostp ' . 

Special  Considerations 

This  function  is  to  be  used  only  by  stream  components  to  put  stream  statistics  into 
an  atom  container;  applications  should  not  call  it. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSInsertStatisticName 


Inserts  the  name  and  type  of  a  statistic  datum  into  the  statistic  atom  for  a  stream. 


OSErr  QTSInsertStatisticName  ( 


QTAtomContai ner 

QTAtom 

OSType 

const  char 

UInt32 


i nContai ner , 
i nParentAtom, 
i nStatType , 

*i nStatName , 
i nStatNameLength  ); 


i nContai ner 

A  handle  to  the  atom  container  that  contains  the  statistic  atom.  Both  the  atom 
container  and  the  parent  atom  must  already  exist, 
i nParentAtom 

The  atom  that  will  hold  a  new  atom  containing  the  specified  statistic  name  and 
type. 


Inside  QuickTime:  Function  l-Q 


11-1241 


QTSInsertStatisticUnits 


i nStatType 

A  constant  (see  below)  that  identifies  the  type  of  statistic  atom  to  insert  the  data 
into. 

i nStatName 

A  pointer  to  the  name  string  to  be  inserted. 

1 nStatNameLength 

The  length  of  the  name  string  in  characters. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inStatType  Constants 

kQTSStati sti csStreamAtomType 

Stream  atom  type;  value  is  '  s t  rm ' . 
kQTSStati sti csNameAtomType 

Name  atom  type;  value  is  'name ' . 
kQTSStati sti csDataFormatAtomType 

Data  format  atom  type;  value  is  '  f  rmt ' . 
kQTSStati sti csDataAtomType 

Data  atom  type;  value  is  '  data  ' . 
kQTSStati sti cs Uni tsAtomType 

Units  atom  type;  value  is  'unit'. 
kQTSStati sti cs Uni tsNameAtomType 

Units  name  atom  type;  value  is  '  un  i  n ' . 

Special  Considerations 

This  function  is  to  be  used  only  by  stream  components  to  put  stream  statistics  into 
an  atom  container;  applications  should  not  call  it. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


QTSInsertStatisticUnits 


Inserts  the  name  and  type  of  statistic  units  into  the  statistic  atom  for  a  stream. 

OSErr  QTSInsertStatisticUnits  ( 

QTAtomContai ner  inContainer, 

QTAtom  InParentAtom, 

OSType  InStatType, 


11-1242 


Inside  QuickTime:  Function  l-Q 


QTSInsertStatisticUnits 


OSType  inllnitsType, 

const  char  *i  nllni  tsName , 

UInt32  i nllni tsNameLength  ); 

i nContai ner 

A  handle  to  the  atom  container  that  contains  the  statistic  atom.  Both  the  atom 
container  and  the  parent  atom  must  already  exist, 
i nParentAtom 

The  atom  that  will  hold  a  new  atom  containing  the  specified  statistic  name  and 
type. 

i nStatType 

A  constant  (see  below)  that  identifies  the  type  of  statistic  atom  to  insert  the  data 
into. 

i  nllni  tsType 

A  constant  (see  below)  that  identifies  the  type  of  units  atom  to  insert  the  data 
into. 

i  nllni  tsName 

A  pointer  to  the  units  name  string  to  be  inserted, 
i  nllni  tsNameLength 

The  length  of  the  units  name  string  in  characters. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inStatType  Constants 

kQTSStati sti csStreamAtomType 

Stream  atom  type;  value  is  '  strm ' . 
kQTSStati sti csNameAtomType 

Name  atom  type;  value  is  '  name ' . 
kQTSStati sti csDataFormatAtomType 

Data  format  atom  type;  value  is  '  f  rmt ' . 
kQTSStati sti csDataAtomType 

Data  atom  type;  value  is  '  data ' . 
kQTSStati  sti  csllni  tsAtomType 

Units  atom  type;  value  is  'unit'. 
kQTSStati  sti  csllni  tsNameAtomType 

Units  name  atom  type;  value  is  '  un  i  n ' . 

inllnitsType  Constants 

kQTSStati sti csNoUni tsType 
No  unit  type;  value  is  0. 


Inside  QuickTime:  Function  l-Q 


11-1243 


QTSMediaGetlndStreamlnfo 


kQTSStati sticsPercentUnitsType 

Percent  unit  type;  value  is  '  pent ' . 
kQTSStati  sticsBitsPerSectlnitsType 

Bits  per  second  unit  type;  value  is  '  bps  ' . 
kQTSStati sticsFramesPerSeclInitsType 

Frames-per-second  unit  type;  value  is  '  f  ps  ' . 

Special  Considerations 

This  function  is  to  be  used  only  by  stream  components  to  put  stream  statistics  into 
an  atom  container;  applications  should  not  call  it. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


QTSMediaGetlndStreamlnfo 


Undocumented 

t  QTSMediaGetlndStreamlnfo  ( 
er  mh , 

inindex, 
i nSel ector , 

*i oParams  ) ; 


ComponentResul 
Medi aHandl 
SInt32 
OSType 
voi  d 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 
i nlndex 

Undocumented 
i nSel ector 

A  constant  (see  below)  that  identifies  the  type  of  information  to  be  retrieved, 
i oParams 

A  pointer  to  returned  information  in  a  format  determined  by  inSelector  (see 
below). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


11-1244 


Inside  QuickTime:  Function  l-Q 


QTSMediaGetlnfo 


inSelector  Constants 

kQTSMedi aPresentati  onlnfo 

The  i  oParams  parameter  returns  a  QTSMedi  aPresentati  onParams  (IV-2375) 
structure  identifying  the  presentation.  Constant  value  is  '  pres  ' . 

kQTSMedi aNoti fi cati  onlnfo 

The  i  oParams  parameter  returns  a  QTSMedi  aNoti  f  i  cati  onParams  (IV-2374) 
structure  identifying  the  notification  process.  Constant  value  is  '  noti ' . 
kQTSMedi aTotal Data  Rate  Info 

The  i  oParams  parameter  returns  a  UInt32  value  representing  bits  per  second. 
Constant  value  is  'dtrt'. 
kQTSMedi aLostPercentlnfo 

The  i  oParams  parameter  returns  a  fixed  integer  value  representing  the 
percentage  of  data  lost.  Constant  value  is  '  1  spc ' . 

kQTSMedi aNumStreamsInfo 

The  i  oParams  parameter  returns  a  UInt32  value  representing  the  number  of 
streams.  Constant  value  is  '  nstr ' . 
kQTSMedi alndSampl eDescri  pti  onlnfo 

The  i  oParams  parameter  returns  a  QTSMedi  alndSampl  eDescri  pti  onParams 
(IV-2373)  structure  identifying  the  sample  data.  Constant  value  is  '  i  sdc ' . 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTSMovi  e .  h 

See  Also 

For  the  corresponding  set  function,  see  QTSMedi  aSetlndStreamlnfo  (11-1246). 


QTSMediaGetlnfo 


Gets  information  about  a  streaming  media. 

ComponentResul t  QTSMediaGetlnfo  ( 
MediaHandler  mh, 

OSType  inSelector, 

void  *i oParams  ); 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMedi  aHandl  er  (1-432). 


Inside  QuickTime:  Function  l-Q 


11-1245 


QTSMediaSetlndStreamlnfo 


i nSel ector 

A  constant  (see  below)  that  identifies  the  type  of  information  to  be  retrieved, 
i oParams 

A  pointer  to  returned  information  in  a  format  determined  by  inSelector  (see 
below). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inSelector  Constants 

kQTSMedi aPresentationlnfo 

The  i oParams  parameter  returns  a  QTSMedi  aPresentati onParams  (IV-2375) 
structure  identifying  the  presentation.  Constant  value  is  '  pres ' . 
kQTSMedi aNoti fi cati  onlnfo 

The  i  oParams  parameter  returns  a  QTSMedi  aNoti  fi  cati  onParams  (IV-2374) 
structure  identifying  the  notification  process.  Constant  value  is  '  noti ' . 
kQTSMedi aTotalDataRatelnfo 

The  i  oParams  parameter  returns  a  UInt32  value  representing  bits  per  second. 
Constant  value  is  '  d  t  r  t ' . 

kQTSMedi aLostPercentlnfo 

The  i  oParams  parameter  returns  a  fixed  integer  value  representing  the 
percentage  of  data  lost.  Constant  value  is  '  1  spc ' . 
kQTSMedi a NumSt reams  Info 

The  i  oParams  parameter  returns  a  UInt32  value  representing  the  number  of 
streams.  Constant  value  is  '  nstr ' . 
kQTSMedi alndSampleDescripti  onlnfo 

The  i  oParams  parameter  returns  a  QTSMedi  a  I ndSampl  eDescri  pti  onParams 
(IV-2373)  structure  identifying  the  sample  data.  Constant  value  is  '  i  sdc ' . 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTSMovi e .  h 

See  Also 

For  the  corresponding  set  function,  see  QTSMedi  aSetlnfo  (11-1248). 


QTSMediaSetlndStreamlnfo 

Undocumented 


11-1246 


Inside  QuickTime:  Function  l-Q 


QTSMediaSetlndStreamlnfo 


Component Res ul t  QTSMedi aSetlndStreamlnfo 
MediaHandler  mh, 

SInt32  inindex, 

OSType  inSelector, 

void  *i oParams  ); 


( 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMediaHandler  (1-432). 
i n Index 

Undocumented 
l nSel ector 

A  constant  (see  below)  that  identifies  the  type  of  information  to  be  set. 
i oParams 

A  pointer  to  information  in  a  format  determined  byinSelector  (see  below). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inSelector  Constants 

kQTSMedi aPresentati  onlnfo 

The  i  oParams  parameter  returns  a  QTSMedi  aPresentati  onParams  (IV-2375) 
structure  identifying  the  presentation.  Constant  value  is  '  pres ' . 
kQTSMedi aNoti fi cati  onlnfo 

The  i  oParams  parameter  returns  a  QTSMedi  aNoti  f  i  cati  onParams  (IV-2374) 
structure  identifying  the  notification  process.  Constant  value  is  '  noti ' . 

kQTSMedi aTotalDataRatelnfo 

The  i  oParams  parameter  returns  a  UInt32  value  representing  bits  per  second. 
Constant  value  is  'dtrt'. 
kQTSMedi aLostPercentlnfo 

The  i  oParams  parameter  returns  a  fixed  integer  value  representing  the 
percentage  of  data  lost.  Constant  value  is  '  1  spc  ’ . 
kQTSMedi aNumStreamsInfo 

The  i  oParams  parameter  returns  a  UInt32  value  representing  the  number  of 
streams.  Constant  value  is  '  nstr ' . 

kQTSMedi alndSampl eDescri  pti  onlnfo 

The  i  oParams  parameter  returns  a  QTSMedi  alndSampl  eDescri  pti  onParams 
(IV-2373)  structure  identifying  the  sample  data.  Constant  value  is  '  i  sdc ' . 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTSMovi  e .  h 
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QTSMediaSetlnfo 


See  Also 

For  the  corresponding  get  function,  see  QTSMedi  aGetlndStreamlnfo  (11-1244). 


QTSMediaSetlnfo 


Sets  information  about  a  streaming  media. 

ComponentResul t  QTSMediaSetlnfo  ( 
MediaHandler  mh, 

OSType  inSelector, 

voi d  *1 oParams  ) ; 


mh 

A  media  handler.  You  can  obtain  this  reference  from  GetMediaHandler  (1-432). 
i nSel ector 

A  constant  (see  below)  that  identifies  the  type  of  information  to  be  set. 
i oParams 

A  pointer  to  information  in  a  format  determined  by  inSelector  (see  below). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inSelector  Constants 

kQTSMedi aPresentationlnfo 

The  i oParams  parameter  returns  a  QTSMedi  aPresentati onParams  (IV-2375) 
structure  identifying  the  presentation.  Constant  value  is  '  pres ' . 

kQTSMedi aNotificationlnfo 

The  i oParams  parameter  returns  a  QTSMedi  aNoti fi  cati onParams  (IV-2374) 
structure  identifying  the  notification  process.  Constant  value  is  '  noti ' . 

kQTSMedi aTotalDataRatelnfo 

The  i  oParams  parameter  returns  a  UInt32  value  representing  bits  per  second. 
Constant  value  is  '  d  t  r  t ' . 
kQTSMedi aLostPercentlnfo 

The  i  oParams  parameter  returns  a  fixed  integer  value  representing  the 
percentage  of  data  lost.  Constant  value  is  '  1  spc ' . 

kQTSMedi a NumSt reams  Info 

The  i  oParams  parameter  returns  a  UInt32  value  representing  the  number  of 
streams.  Constant  value  is  '  nstr ' . 

kQTSMedi alndSampleDescriptionlnfo 

The  i  oParams  parameter  returns  a  QTSMedi  a  I ndSampl  eDescri  pti  onParams 
(IV-2373)  structure  identifying  the  sample  data.  Constant  value  is  '  i  sdc ' . 
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QTSMessageLength 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTSMovi  e .  h 

See  Also 

For  the  corresponding  get  function,  see  QTSMedi  aGetlnfo  (11-1245). 

QTSMessageLength 

Undocumented 

SInt32  QTSMessageLength  ( 

QTSStreamBuf fer  *i nStreamBuf f er  ); 

i nStreamBuf fer 

A  pointer  to  a  QTSStreamBuffer  (IV-2385)  structure. 
function  result  The  message  length. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSNewHandle 


Allocates  a  new  handle  for  data,  with  options  and  checking. 

Handle  QTSNewHandle  ( 

UInt32  inByteCount, 

SInt32  inFlags, 

SInt32  *outFlags  ); 

i nByteCount 

The  requested  size  in  bytes  of  the  relocatable  block, 
i n FI  ags 

Flags  (see  below)  that  control  memory  allocation  options. 
outFl  ags 

A  pointer  to  memory  where  return  flags  (see  below)  report  on  the  block's  actual 
memory  location. 


Inside  QuickTime:  Function  l-Q 
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QTSNewPresentation 


function  result  The  new  handle. 

inFlags  Constants 

kQTSMemAl 1 ocCl  ear Mem 

Set  all  bits  in  the  allocated  block  to  0. 
kQTSMemAl 1 ocDontUseTempMem 

Don't  allocate  the  block  in  temporary  memory. 
kQTSMemAl 1 ocT  ryTempMemFi rst 

Try  first  to  allocate  the  block  in  temporary  memory. 
kQTSMemAl 1 ocDontUseSystemMem 

Don't  allocate  the  block  in  system  memory. 
kQTSMemAl 1 ocT rySystemMemFi  rst 

Try  first  to  allocate  the  block  in  system  memory. 
kQTSMemAl  1  octlol  dMemory 

Make  the  block  resident  in  physical  memory  and  ineligible  for  paging. 
kQTSMemAl locIsInterruptTime 

This  function  is  being  called  during  an  interrupt. 

outFlags  Constants 

kQTSMemAl 1 ocAl 1 ocatedlnTempMem 

The  block  was  allocated  in  temporary  memory. 
kQTSMemAl 1 ocAl 1 ocatedlnSystemMem 

The  block  was  allocated  in  system  memory. 

Discussion 

This  function  is  a  handy  way  to  allocate  memory  without  overflowing  the 
application  heap,  which  is  mostly  a  concern  with  Mac  OS  versions  7  through  9.  It  is 
often  used  for  streaming  data. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


QTSNewPresentation 


Creates  a  new  streaming  presentation. 


*i nParams , 
*outPresentati on  ) ; 


OSErr  QTSNewPresentation  ( 

const  QTSNewPresentationParams 
QTSPresentati on 
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QTSNewPresentationFromData 


i nParams 

A  pointer  to  a  QTSNewPresentati  onParams  (IV-2376)  structure  that  specifies  the 
presentation. 
outPresentati on 

A  pointer  to  a  pointer  to  a  new  QTSPresentationRecord  (IV-2379)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSNewPresentationFromData 


Undocumented 


OSErr  QTSNewPresentati on 
OSType 
const  void 
const  SInt64 
const  QTSPresParams 
QTSPresentati on 


FromData  ( 
i  nDataType , 

*i nData , 

*i nData  Length , 

*i nPresParams , 
*outPresentati on  ); 


i nDataType 

Undocumented 
i nData 

Undocumented 
i nDataLength 

Undocumented 
i nPresParams 

Undocumented 
outPresentati on 
Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 
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QTSNewPresentationFromDataRef 


QTSNewPresentationFromDataRef 

Undocumented 

OSErr  QTSNewPresentationFromDataRef  ( 

Handle  inDataRef, 

OSType  i nDataRefType , 

const  QTSPresParams  *inPresParams , 

QTSPresentati on  *outPresentati on  ); 

i nDataRef 

Undocumented 
i nDataRefType 

Undocumented 
i nPresParams 

Undocumented 
outPresentati on 
Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


QTSNewPresentationFromFile 

Undocumented 

OSErr  QTSNewPresentationFromFile  ( 

const  FSSpec  *inFileSpec, 

const  QTSPresParams  *inPresParams , 

QTSPresentati on  *outPresentati on  ); 

inFi  1  eSpec 

Undocumented 
i nPresParams 

Undocumented 
outPresentati on 
Undocumented 
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QTSNewPtr 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTimeSt rearin'  ng .  h 


QTSNewPtr 

Allocates  a  block  of  memory  for  streaming  data,  with  options  and  checking,  and 
returns  a  pointer  to  it. 

Ptr  QTSNewPtr  ( 

UInt32  inByteCount, 

SInt32  inFlags, 

SInt32  *outFlags  ); 

i nByteCount 

The  requested  size  in  bytes  of  the  new  memory  block, 
i  n  FI  ags 

Flags  (see  below)  that  control  memory  allocation  options. 
outFl  ags 

A  pointer  to  memory  where  return  flags  (see  below)  report  on  the  block's  actual 
memory  location. 

function  result  A  pointer  to  the  newly  allocated  block. 

inFlags  Constants 

kQTSMemAl 1 ocCl earMem 

Set  all  bits  in  the  allocated  block  to  0. 
kQTSMemAl 1 ocDontUseTempMem 

Don't  allocate  the  block  in  temporary  memory. 
kQTSMemAl 1 ocT  ryTempMemFi rst 

Try  first  to  allocate  the  block  in  temporary  memory. 
kQTSMemAl 1 ocDontUseSystemMem 

Don't  allocate  the  block  in  system  memory. 
kQTSMemAl 1 ocT rySystemMemFi  rst 

Try  first  to  allocate  the  block  in  system  memory. 
kQTSMemAl 1 ocHol dMemory 

Make  the  block  resident  in  physical  memory  and  ineligible  for  paging. 
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QTSNewSourcer 


kQTSMemAl 1 ocIsInterruptT ime 

This  function  is  being  called  during  an  interrupt. 

outFlags  Constants 

kQTSMemAl 1 ocAl 1 ocatedlnTempMem 

The  block  was  allocated  in  temporary  memory. 
kQTSMemAl 1 ocAl 1 ocatedlnSystemMem 

The  block  was  allocated  in  system  memory. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


QTSNewSourcer 


Undocumented 


OSErr  QTSNewSourcer  ( 
voi  d 

const  QTSSourcerlni tParams 
SInt32 

Componentlnstance 


*params , 

*i nlni tParams , 
i  n FI  ags  , 
*outSourcer  ) ; 


params 

Undocumented 
i nlni tParams 

Undocumented 
i  n FI  ags 

Undocumented 

outSourcer 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 
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C  interface  file:  QTStreami  ngComponents .  h 
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QTSNewStatHelper 


QTSNewStatHelper 


Creates  a  new  statistics  helper  for  a  stream  or  presentation. 


OSErr  QTSNewStatHelper 
QTSPresentati on 
QTSStream 
OSType 
SInt32 

QTSStatHel per 


( 

i nPresentati on 
i nStream, 
i nStatType , 
i  n FI  ags  , 
*outStatHel per 


); 


i nPresentati on 

A  pointer  to  a  QTSPresentati  on  Re  cord  (IV-2379)  structure  that  defines  the 
presentation  to  keep  statistics  on.  To  create  a  statistics  helper  for  a  particular 
stream,  pass  in  kQTSInval  idPresentati on. 

i nStream 

A  pointer  to  a  QTSStream  Re  cord  (IV-2387)  structure  that  defines  the  stream  to 
keep  statistics  on.  To  create  a  statistics  helper  for  a  whole  presentation,  pass  in 
kQTSAl 1  Streams, 
i nStatType 

A  constant  (see  below)  that  defines  the  type  of  statistic  you  want  the  statistics 
helper  to  gather, 
i  nFl  ags 

Constants  (see  below)  governing  the  action  of  the  statistics  helper. 
outStatHel per 

On  entry,  a  pointer  to  a  variable  of  type  QTSStatHel  per;  on  return,  this  variable 
is  set  to  the  new  statistics  helper. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inStatType  Constants 

kQTSAl 1 Stati sti csType 

Create  a  full  statistics  helper  for  all  statistics;  constant  value  is  '  a  1 1  ' . 
kQTSShortStati sti csType 

Create  a  short  statistics  helper;  constant  value  is  '  s h  rt ' . 
kQTSSummaryStati sti csType 

Create  a  summary  statistics  helper;  constant  value  is  '  summ ' . 

inFlags  Constants 

kQTSGetNameStati sti csFl  ag 

The  statistics  helper  is  to  get  name  statistics. 
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QTSNewStreamBuffer 


kQTSDontGetDataStati sti csFl  ag 

The  statistics  helper  is  to  get  data  statistics. 
kQTSUpdateAtomsStati sties  FI  ag 

The  statistics  helper  is  to  update  statistics  atoms. 
kQTSGetUni tsStatisticsFlag 

The  statistics  helper  is  to  get  units  statistics. 

Discussion 

A  statistics  helper  is  a  set  of  utility  functions  that  you  can  use  to  retrieve  and  parse 
statistics  from  a  stream  component.  You  need  to  instantiate  a  statistics  helper  for 
every  stream  from  which  you  want  to  gather  statistics. 

Special  Considerations 

When  you  are  done  using  the  statistics  helper,  call  QTSDisposeStatHelper  (11-1221). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


QTSNewStreamBuffer 

Undocumented 

OSErr  QTSNewStreamBuffer  ( 

UInt32  inDataSize, 

SInt32  inFlags, 

QTSStreamBuffer  **outStreamBuffer  ); 

i nDataSi ze 

Undocumented 

i  n FI  ags 

Undocumented 

outStreamBuffer 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 
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C  interface  file:  Qui  ckT i  meStreami  ng .  h 
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QTSPrefsAddConnectionSetting 


QTSPrefsAddConnectionSetting 


Undocumented 

OSErr  QTSPrefsAddConnectionSetting  ( 

OSType  protocol  , 

SInt32  portID, 

UInt32  flags, 

UInt32  seed  ); 

protocol 

A  constant  (see  below)  that  identifies  the  connection  protocol. 
portID 

Undocumented 
fl  ags 

Undocumented 


seed 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

protocol  Constants 

kQTSDi rectConnectHTTPProtocol 

HTTP  protocol;  constant  value  is  '  http ' . 
kQTSDi rectConnectRTSPProtocol 

RTSP  protocol;  constant  value  is  '  rtsp ' . 

flags  Constants 

Undocumented 

Undocumented 


Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSPrefsAddProxySetting 


Undocumented 

OSErr  QTSPrefsAddProxySetting  ( 
OSType  proxyType, 


Inside  QuickTime:  Function  l-Q 
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QTSPrefsAddProxyUserlnfo 


SInt32  portID, 

UInt32  flags, 

UInt32  seed, 

Str255  srvrURL  ) ; 

proxyType 

A  constant  (see  below)  that  defines  the  proxy  type. 
portID 

Undocumented 
fl  ags 

Undocumented 

seed 

Undocumented 

srvrURL 

A  string  containing  the  server's  URL. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

proxyType  Constants 

kQTSHTTPProxyPrefsType 

HTTP  proxy;  constant  value  is  '  http ' . 
kQTSRTSPProxyPrefsType 

RTSP  proxy;  constant  value  is  '  rtsp ' . 
kQTSSOCKSProxyPrefsType 

SOCKS  proxy;  constant  value  is  '  scks ' . 
kQTSDont Proxy Da taType 

No  proxy;  constant  value  is  '  data ' . 

flags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  4.1. 
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C  interface  file:  Qui  ckT i meStreami  ng .  h 


QTSPrefsAddProxyUserlnfo 

Undocumented 
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QTSPrefsFindConnectionByType 


OSErr  QTSPrefsAddProxyUserlnfo 


OSType 
SInt32 
SInt32 
Stri ngPtr 
Stri  ngPtr 


proxyType, 
fl ags , 
fl agsMask, 
username , 
password  ); 


( 


proxyType 

Undocumented 
fl  ags 

Undocumented 
fl agsMask 

Undocumented 

username 

Undocumented 

password 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Version  Notes 

Introduced  in  QuickTime  5. 
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C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSPref  sFindConnectionByT  ype 


Undocumented 

OSErr  QTSPrefsFindConnectionByType  ( 

OSType  protocol  , 

UInt32  flags, 

UInt32  flagsMask, 

QTSTransportPref  **connecti onHndl  , 

SIntl6  *count  ); 

protocol 

A  constant  (see  below)  that  identifies  the  connection  protocol, 
fl  ags 

Undocumented 


Inside  QuickTime:  Function  l-Q 
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QTSPrefsFindProxyByType 


f  1  agsMask 

Undocumented 
connecti onHndl 

A  handle  to  a  QTST ransportPref  (IV-2388)  structure, 
count 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

protocol  Constants 

kQTSDi rectConnectHTTPProtocol 

HTTP  protocol;  constant  value  is  '  http ' . 
kQTSDi rectConnectRTSPProtocol 

RTSP  protocol;  constant  value  is  '  rtsp ' . 

flags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  4.1. 
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C  interface  file:  Qui  ckT i meStreami  ng .  h 


QTSPrefsFindProxyByType 


Undocumented 


OSErr  QTSPrefsFindProxyByType  ( 


OSType 

UInt32 

UInt32 

QTSProxyPref 

SIntl6 


proxyType , 
fl  ags , 
f  1  agsMask , 
**proxyHndl 
*count  ) ; 


proxyType 

A  constant  (see  below)  that  defines  the  proxy  type, 
fl  ags 

Undocumented 
f 1 agsMask 

Undocumented 


11-1260 
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QTSPrefsFindProxyUserlnfoByType 


proxyHndl 

A  handle  to  a  QTSProxyPref  (IV-2380)  structure, 
count 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

proxyType  Constants 

kQTSHTTPProxyPref sType 

HTTP  proxy;  constant  value  is  '  http ' . 
kQTSRTSPProxyPref sType 

RTSP  proxy;  constant  value  is  '  rtsp ' . 
kQTSSOCKSProxyP ref sType 

SOCKS  proxy;  constant  value  is  '  scks ' . 
kQTSDont Proxy Da taType 

No  proxy;  constant  value  is  '  data  ' . 

flags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSPrefsFindProxyUserlnfoByType 


Undocumented 


OSErr  QTSPrefsFi nd Proxy User  I nfoByType 
OSType  proxyType, 

SInt32  flags, 

SInt32  flagsMask, 

StringPtr  username, 

StringPtr  password  ); 


( 


proxyType 

Undocumented 
fl  ags 

Undocumented 
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QTSPrefsGetActiveConnection 


f  1  agsMask 

Undocumented 

username 

Undocumented 

password 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


QTSPrefsGetActiveConnection 

Undocumented 

OSErr  QTSPrefsGetActiveConnection  ( 

OSType  protocol , 

QTSTransportPref  *connectInfo  ); 

protocol 

A  constant  (see  below)  that  identifies  the  connection  protocol, 
connectlnfo 

A  pointer  to  a  QTSTransportPref  (IV-2388)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

protocol  Constants 

kQTSDi rectConnectHTTPProtocol 

HTTP  protocol;  constant  value  is  '  http ' . 
kQTSDi rectConnectRTSPProtocol 

RTSP  protocol;  constant  value  is  '  rtsp ' . 

Version  Notes 

Introduced  in  QuickTime  4.1. 
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C  interface  file:  Qui  ckT i  meStreami  ng .  h 
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QTSPrefsGetNoProxyURLs 


QTSPrefsGetNoProxyURLs 

Undocumented 

OSErr  QTSPrefsGetNoProxyURLs  ( 

QTSNoProxyPref  **noProxyHndl  ); 

noProxyHndl 

A  handle  to  a  QTSNoProxyPref  (IV-2378)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 

See  Also 

For  the  corresponding  set  function,  see  QTSPref  sSetNoProxyURLs  (11-1263). 


QTSPrefsSetNoProxyURLs 

Undocumented 

OSErr  QTSPrefsSetNoProxyURLs  ( 
char  *urls, 

UInt32  flags, 

UInt32  seed  ); 

url  s 

A  pointer  to  URL  strings, 
fl  ags 

Undocumented 

seed 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

Undocumented 

Undocumented 


Version  Notes 

Introduced  in  QuickTime  4.1. 
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QTSPresAddSourcer 


Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 

See  Also 

For  the  corresponding  get  function,  see  QTSPrefsGetNoProxyURLs  (11-1263). 


QTSPresAddSourcer 

Undocumented 


OSErr  QTSPresAddSourcer 
QTSPresentati on 
QTSStream 
Componentlnstance 
SInt32 

i nPresentati on 
Undocumented 
i nStream 

Undocumented 
1  nSourcer 

Undocumented 
1  n FI  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 
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C  interface  file:  Qui  ckT i  meStreami  ng .  h 


( 

i  nPresentati on , 
i nStream , 
i nSourcer , 
i  n FI  ags  ) ; 


QTSPresExport 


Undocumented 


i nPresentati on , 
i nStream , 

*i nExportParams  ) ; 


OSErr  QTSPresExport  ( 
QTSPresentati on 
QTSStream 
QTSExportParams 


11-1264 
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QTSPresGetActiveSegment 


i nPresentati on 
Undocumented 
i nStream 

Undocumented 
i nExportParams 
Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 

QTSPresGetActiveSegment 

Undocumented 

OSErr  QTSPresGetActiveSegment  ( 

QTSPresentation  i nPresentati on, 

QTSStream  inStream, 

TimeValue64  *outStartTime, 

TimeValue64  *outDuration  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentation  Re  cord  (IV-2379)  structure, 
i nStream 

A  pointer  to  a  QTSStream  Re  cord  (IV-2387)  structure  that  defines  a  stream. 
outStartTime 

Undocumented 
outDurati on 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


Inside  QuickTime:  Function  l-Q 


11-1265 


QTSPresGetClip 


See  Also 

For  the  corresponding  set  function,  see  QTSPresSetActi  veSegment  (11-1288). 


QTSPresGetClip 

Gets  the  clipping  region  for  a  streaming  presentation. 

OSErr  QTSPresGetClip  ( 

QTSPresentati on 
QTSStream 
RgnHandl e 

i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure  that  defines  a 
presentation. 

i nStream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure  that  defines  a  stream. 
outCl i p 

A  pointer  to  a  handle  to  a  MacRegi  on  (IV-2303)  structure  that  defines  a  clipping 
region. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 

See  Also 

For  the  corresponding  set  function,  see  QTSPresSetCl  i  p  (11-1289). 


QTSPresGetDimensions 

Gets  the  dimensions  of  a  streaming  presentation. 

OSErr  QTSPresGetDimensions  ( 

QTSPresentati on  inPresentation, 
QTSStream  inStream, 

Fixed  *outWidth, 

Fixed  *outHeight  ); 


i nPresentati on , 
i nStream , 
*outClip  ); 


11-1266 


Inside  QuickTime:  Function  l-Q 


QTSPresGetEnable 


i nPresentati on 

A  pointer  to  a  QTSPresentationRecord  (IV-2379)  structure  that  defines  a 
presentation, 
i nStream 

A  pointer  toaQTSStreamRecord  (IV-2387)  structure  that  defines  a  stream. 
outWi dth 

A  pointer  to  the  width  in  pixels. 
outHei ght 

A  pointer  to  the  height  in  pixels. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 

See  Also 

For  the  corresponding  set  function,  see  QTSPresSetDi mensi  ons  (11-1290). 

QTSPresGetEnable 

Determines  whether  or  not  a  presentation  is  enabled. 

OSErr  QTSPresGetEnable  ( 

QTSPresentati on  i nPresentati on , 

QTSStream  inStream, 

Boolean  *outEnabl eMode  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentati  on  Re  cord  (IV-2379)  structure, 
i nStream 

A  pointer  to  a  QTSStream  Re  cord  (IV-2387)  structure  that  defines  a  stream. 
outEnabl eMode 

A  pointer  to  a  Bool  ean  that  is  TRUE  if  the  presentation  is  enabled,  FALSE 
otherwise. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 


Inside  QuickTime:  Function  l-Q 


11-1267 


QTSPresGetFlags 


Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 

See  Also 

For  the  corresponding  set  function,  see  QTSPresSetEnabl  e  (11-1290). 


QTSPresGetFlags 

Gets  the  flags  currently  set  for  a  presentation. 

OSErr  QTSPresGetFl ags  ( 

QTSPresentati on  inPresentation, 

SInt32  *outFlags  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure  that  defines  a 
presentation. 

outFl  ags 

On  entry,  the  address  of  a  variable  of  type  S I  n  1 3  2;  on  return,  this  variable  is  set 
to  the  current  flags  (see  below)  for  the  specified  presentation. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

outFlags  Constants 

kQTSAutoModeFl ag 

Automatic  presentation  mode. 
kQTSDontShowStatusFl  ag 
Don't  show  status. 
kQTSSendMedi a  FI ag 
Send  media. 
kQTSRecei veMediaFl  ag 
Receive  media. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i  meStreami  ng .  h 

See  Also 

For  the  corresponding  set  function,  see  QTSPresSetFl  ags  (11-1291). 


11-1268 


Inside  QuickTime:  Function  l-Q 


QTSPresGetGraphicsMode 


QTSPresGetGraphicsMode 


Gets  the  graphics  mode  and  blend  color  in  use  for  video  display  by  a  stream  or 
presentation. 


OSErr  QTSPresGetGraphicsMode  ( 

QTSPresentati on  i n Present a ti on , 
QTSStream  inStream, 

short  *outMode, 

RGBColor  *outOpColor  ); 


i nPresentati on 

A  pointer  to  a  QTSPresentati  on  Re  cord  (IV-2379)  structure  that  defines  a 
presentation.  If  you  want  the  graphics  mode  for  a  specific  stream,  pass  the 
value  kQTSInval  idPresentation. 
i nStream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure  that  defines  a  stream.  If  you 
want  the  graphics  mode  for  the  presentation  as  a  whole,  pass  the  value 
kQTSAl 1  Streams. 

outMode 

On  entry,  a  pointer  to  a  short  integer;  on  return,  this  variable  is  set  to  the 
graphics  mode  of  the  specified  presentation  or  stream.  See  "Graphics  Transfer 
Modes"  (IV-2670). 
outOpCol or 

On  entry,  the  address  of  an  RGBCol  or  (IV-2403)  structure;  on  return,  this 
structure  is  filled  in  with  information  about  the  color  used  for  blending  and 
transparent  operations.  The  stream  handler  passes  this  color  to  QuickDraw  as 
appropriate  when  you  draw  in  addPin,  subPin,  blend,  or  transparent  mode. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 

See  Also 

For  the  corresponding  set  function,  see  QTSPresSetGraphi  csMode  (11-1292). 


Inside  QuickTime:  Function  l-Q 


11-1269 


QTSPresGetGWorld 


QTSPresGetGWorld 

Gets  the  graphics  port  and  graphics  device  in  use  by  a  stream  or  presentation. 

OSErr  QTSPresGetGWorld  ( 

QTSPresentati on  inPresentation, 

QTSStream  inStream, 

CGrafPtr  *outGWorld, 

GDHandle  *outGDHandle  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure  that  defines  a 
presentation.  If  you  want  the  graphics  mode  for  a  specific  stream,  pass  the 
value  kQTSInval  i dPresentati on. 
i nStream 

A  pointer  to  a  QTSStream  Re  cord  (IV-2387)  structure  that  defines  a  stream.  If  you 
want  the  graphics  mode  for  the  presentation  as  a  whole,  pass  the  value 
kQTSAl 1  Streams. 

outGWorl d 

On  entry,  the  address  of  a  variable  of  type  CGrafPtr;  on  return,  this  variable  is 
set  to  a  pointer  to  a  CGraf  Port  (IV-2168)  structure  that  defines  the  offscreen 
graphics  world,  color  graphics  port,  or  basic  graphics  port  in  use  by  the 
specified  presentation  or  stream. 
outGDHandl e 

On  entry,  the  address  of  a  variable  of  type  GDHandl  e;  on  return,  this  variable  is 
set  to  the  handle  of  a  GDevi  ce  (IV-2264)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 

See  Also 

For  the  corresponding  set  function,  see  QTSPresSetGWorl  d  (11-1292). 

QTSPresGetlndSourcer 

Undocumented 

OSErr  QTSPresGetlndSourcer  ( 


11-1270 


Inside  QuickTime:  Function  l-Q 


QTSPresGetlndStream 


QTSPresentati on  inPresentation, 

QTSStream  inStream, 

UInt32  inindex, 

Componentlnstance  *outSourcer  ); 

1 nPresentati on 
Undocumented 
l nStream 

Undocumented 
l n Index 

Undocumented 

outsourcer 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 

QTSPresGetlndStream 

Get  a  stream  associated  with  a  presentation,  based  on  its  index  number. 

QTSStream  QTSPresGetlndStream  ( 

QTSPresentati on  i nPresentati on , 

UInt32  inindex  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentati  on  Re  cord  (IV-2379)  structure, 
i n Index 

The  index  number  of  the  stream. 

function  result  A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


Inside  QuickTime:  Function  l-Q 


11-1271 


QTSPresGetlnfo 


QTSPresGetlnfo 

Gets  information  about  a  presentation  or  stream. 

OSErr  QTSPresGetlnfo  ( 

QTSPresentati on 
QTSStream 
OSType 
voi  d 

i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure  that  defines  a 
presentation.  If  you  want  information  for  a  specific  stream,  pass  the  value 
kQTSInval i dPresentati on. 
i nStream 

A  pointer  to  a  QTSStream  Re  cord  (IV-2387)  structure  that  defines  a  stream.  If  you 
want  information  for  the  presentation  as  a  whole,  pass  the  value 
kQTSAl  1  Streams. 

i nSel ector 

A  constant  (see  below)  that  defines  the  information  to  be  retrieved, 
i oParam 

A  pointer  to  the  retrieved  information  in  the  format  shown  below. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inSelector  Constants 

kQTSGetURLLi nk 

A  URL  as  a  QTSGetURLLi  nkRecord  (IV-2371)  structure;  constant  value  is  'gull  '. 
kQTSTargetBufferDurati  on  Info 

The  expected  (not  necessarily  actual)  buffer  duration  in  seconds,  as  a  Fixed 
value;  constant  value  is  '  buf  r ' . 
kQTSTargetBufferDurati  on  Info 

The  expected  (not  necessarily  actual)  buffer  duration  in  seconds,  as  a  Fixed 
value;  constant  value  is  '  buf  r ' . 
kQTSDurati onlnfo 

Duration  as  a  QTSDurati  onAtom  (IV-2369)  structure;  constant  value  is  '  dura  ' . 
kQTSSourceT  rackIDInfo 

The  source  track  ID  as  a  U I  nt32;  constant  value  is  '  oti  d  ' . 
kQTSSource Layer  Info 

The  source  layer  number  as  a  U I  n  1 1 6;  constant  value  is  '  o  1  y  r ' . 


i nPresentati on , 
i nStream , 
i nSel ector , 

*i oParam  ) ; 


11-1272 


Inside  QuickTime:  Function  l-Q 


QTSPresGetlnfo 


kQTSSourceLanguagelnf o 

The  source  language  code  as  a  U Inti 6;  constant  value  is  '  ol  ng See 
"Localization  Codes"  (IV-2673). 
kQTSSourceTrackFl agslnfo 

The  source  track  flag  set  as  an  SInt32;  constant  value  is  '  otf  1 ' . 
kQTSSourceDi mens  ions  Info 

The  source  dimensions  as  a  QTSDimensionParams  (IV-2368)  structure;  constant 
value  is  '  odim' . 
kQTSSourceVol umes Info 

The  source  sound  volumes  as  a  QTSVol  umesParams  (IV-2390)  structure;  constant 
value  is  '  ovol  ' . 
kQTSSourceMatrixInf o 

The  source  matrix  as  a  Matri  xRecord  (IV-2304)  structure;  constant  value  is 
’  omat ' . 

kQTSSourceCl i pRectlnfo 

The  source  clipping  rectangle  as  a  Rect  (IV-2399)  structure;  constant  value  is 
'  ocl  p ' . 

kQTSSourceGraphi csModelnfo 

The  source  graphics  mode  as  a  QTSGraphi  csModeParams  (IV-2372)  structure; 
constant  value  is  'ogriti'. 
kQTSSourceScal elnfo 

The  source  scaling  factors  as  a  Point  (IV-2339)  structure;  constant  value  is 
’ oscl  ' . 

kQTSSourceBoundi ng Rect Info 

The  source  bounding  rectangle  as  a  Rect  (IV-2399)  structure;  constant  value  is 
' orct ' . 

kQTSSourcellserData  Inf  o 

The  source's  user  data  as  a  UserDataRecord  (IV-2496)  structure;  constant  value 
is  1  oudt ' . 

kQTSSourcelnputMapInf o 

The  source  input  map  as  a  QT  atom  container;  constant  value  is  '  oi  mp ' . 
kQTSStati sti cslnfo 

Statistics  asaQTSStatisticsParams  (IV-2384)  structure;  constant  value  is  '  stat ' . 
kQTSMi nStatusDimensi onslnfo 

The  minimum  status  dimensions  as  a  QTSDi  men  si  on  Pa  rams  (IV-2368)  structure; 
constant  value  is  'mstd'. 


Inside  QuickTime:  Function  l-Q 


11-1273 


QTSPresGetlnfo 


kQTS Normal StatusDimensionsInfo 

The  normal  status  dimensions  as  a  QTSDimensionParams  (IV-2368)  structure; 
constant  value  is  '  nstd ' . 
kQTSTotal Data  Rate  Info 

The  total  data  rate  as  a  U I  nt32  added  to  the  existing  data  rate;  constant  value  is 
'  drtt ' . 

kQTSTotal DataRatelnlnfo 

The  total  data  rate  coming  in  as  a  U I  nt32  added  to  the  existing  input  data  rate; 
constant  value  is  '  drti ' . 
kQTSTotal DataRateOutlnfo 

The  total  data  rate  going  out  as  a  U I  nt32  added  to  the  existing  output  data  rate; 
constant  value  is  '  d  r  t  o ' . 
kQTSDataRateHi story  Info 

The  data  rate  history  as  a  QTSDataRateHi  story  Pa  rams  (IV-2368)  structure; 
constant  value  is  '  d  r  t  h ' . 

kQTS Lost Percent  Info 

The  lost  data  percentage  combined  with  the  existing  percentage  as  a 
QTSLostPercentParams  (IV-2373)  structure;  constant  value  is  'Ipct'. 
kQTSMedi aTypelnfo 

The  media  type  as  an  OSTy pe;  constant  value  is  '  mty p ' . 
kQTSNamelnfo 

The  presentation  or  stream  name  as  a  QTSNamePa  rams  (IV-2376)  structure; 
constant  value  is  '  name ' . 

kQTSSampl eDescriptionlnfo 

A  handle  to  the  Sampl  eDescri  pti  on  (IV-2414)  structure;  constant  value  is 
' sdsc ' . 

kQTSCanHandl eSendDataType 

Information  about  whether  the  stream  or  presentation  can  handle  the  data  type 
as  a  QTSCanHandl  eSendDataTypeParams  (IV-2366)  structure;  constant  value  is 
'  chsd ' . 

kQTSAnnotati onslnfo 

Annotations  as  a  QT  atom  container;  constant  value  is  '  meta ' . 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


11-1274 


Inside  QuickTime:  Function  l-Q 


QTSPresGetMatrix 


See  Also 

For  the  corresponding  set  function,  see  QTSPresSetlnfo  (11-1293). 


QTSPresGetMatrix 

Gets  the  transformation  matrix  in  use  for  the  graphic  display  of  a  stream  or 
presentation. 

OSErr  QTSPresGetMatrix 
QTSPresentati on 
QTSStream 
Matri xRecord 

i nPresentati on 

A  pointer  to  a  QTSPresentati  on  Re  cord  (IV-2379)  structure  that  defines  a 
presentation.  If  you  want  to  get  the  matrix  for  a  specific  stream,  pass  the  value 
kQTSInval idPresentation. 

i nStream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure  that  defines  a  stream.  If  you 
want  to  get  the  matrix  for  the  presentation  as  a  whole,  pass  the  value 
kQTSAl 1  Streams. 

outMatri x 

On  entry,  the  address  of  a  Matri  xRecord  (IV-2304)  structure;  on  return,  this 
structure  is  filled  with  the  transformation  matrix  in  use  by  the  stream  handler. 
Note  that  the  matrix  passed  back  is  the  one  last  set  by  QTSPresSetMatri  x 
(11-1295),  regardless  of  any  additional  matrixes  that  might  have  been  used. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 

See  Also 

For  the  corresponding  set  function,  see  QTSPresSetMatri x  (11-1295). 


( 

i nPresentati on , 
i nStream, 
*outMatrix  ); 


QTSPresGetNotificationProc 

Gets  the  notification  callback  of  a  presentation. 


Inside  QuickTime:  Function  l-Q 


11-1275 


QTSPresGetNumSourcers 


OSErr  QTSPresGetNoti f i cati onProc  ( 

QTSPresentati on  i nPresentati on , 

QTSNotificationUPP  *outNoti f i cati onProc, 

void  **outRefCon  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure, 
out Not i f i cati onProc 

A  pointer  to  a  Universal  Procedure  Pointer  that  accesses  a 
QTSNoti  f  i  cati  onProc  (III— 2126)  callback.  The  callback  acts  as  a  back  channel 
from  a  presentation  to  its  creator.  The  presentation  sends  notification  of  various 
events,  such  as  a  presentation,  ending,  or  acknowledgment  of  a  preroll  request. 
outRefCon 

A  handle  to  a  constant  to  be  passed  to  your  QTSNoti  f  i  cati  onProc. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 

See  Also 

For  the  corresponding  set  function,  see  QTSPresSetNoti  f  i  cati  onProc  (11-1296). 


QTSPresGetNumSourcers 


Undocumented 

UInt32  QTSPresGetNumSourcers  ( 

QTSPresentati on  inPresentation, 

QTSStream  inStream  ); 

i nPresentati on 
Undocumented 
i nStream 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Version  Notes 

Introduced  in  QuickTime  5. 


11-1276 


Inside  QuickTime:  Function  l-Q 


QTSPresGetNumStreams 


Programming  Info 

C  interface  file:  Qui ckTi  meStreami  ng .  h 


QTSPresGetNumStreams 


Undocumented 

UInt32  QTSPresGetNumStreams  ( 

QTSPresentati on  i nPresentati on  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentati  on  Re  cord  (IV-2379)  structure. 
function  result  Undocumented 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTi  meStreami  ng .  h 


QTSPresGetPicture 


Undocumented 

OSErr  QTSPresGetPicture  ( 

QTSPresentati on  i nPresentati on , 

QTSStream  inStream, 

PicHandie  *outPicture  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentati  on  Re  cord  (IV-2379)  structure, 
i nStream 

A  pointer  to  a  QTSStream  Re  cord  (IV-2387)  structure  that  defines  a  stream. 
outPi cture 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Version  Notes 

Introduced  in  QuickTime  4. 


Inside  QuickTime:  Function  l-Q 


11-1277 


QTSPresGetPlayHints 


Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSPresGetPlayHints 

Undocumented 

OSErr  QTSPresGetPlayHints  ( 

QTSPresentati on  inPresentation, 

QTSStream  inStream, 

SInt32  *outFlags  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure, 
i nStream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure  that  defines  a  stream. 
outFl  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

outFlags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 

See  Also 

For  the  corresponding  set  function,  see  QTSPresSetPl  ayHi  nts  (11-1296). 


QTSPresGetPreferredRate 


Undocumented 

OSErr  QTSPresGetPreferredRate  ( 

QTSPresentati on  inPresentation, 

Fixed  *outRate  ); 


11-1278 


Inside  QuickTime:  Function  l-Q 


QTSPresGetPresenting 


i nPresentati on 

A  pointer  to  a  QTSPresentationRecord  (IV-2379)  structure. 
outRate 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 

See  Also 

For  the  corresponding  set  function,  see  QTSPresSetPreferredRate  (11-1297). 


QTSPresGetPresenting 

Determines  whether  presenting  is  enabled  or  disabled  for  a  presentation  or  stream. 

OSErr  QTSPresGetPresenting  ( 

QTSPresentation  i nPresentati on, 

QTSStream  inStream, 

Boolean  *outPresenti ngMode  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentationRecord  (IV-2379)  structure  that  defines  a 
presentation.  If  you  want  to  get  the  presenting  state  for  a  specific  stream,  pass 
the  value  kQTSInval  idPresentati  on. 
i nStream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure  that  defines  a  stream.  If  you 
want  to  get  the  presenting  state  for  the  presentation  as  a  whole,  pass  the  value 
kQTSAl 1  Streams. 

outPresenti ngMode 

A  pointer  to  a  Bool  ean  that  is  TRUE  if  presenting  is  enabled,  FALSE  if  it  is  disabled. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 
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C  interface  file:  Qui  ckTimeStreami  ng .  h 


Inside  QuickTime:  Function  l-Q 


11-1279 


QTSPresGetSettings 


See  Also 

For  the  corresponding  set  function,  see  QTSPresSetPresenti  ng  (11-1298). 


QTSPresGetSettings 


Undocumented 


OSErr  QTSPresGetSett 
QTSPresentati on 
QTSStream 
QTAtomContai ner 
SInt32 

i nPresentati on 
Undocumented 
i nStream 

Undocumented 
outSetti ngs 

Undocumented 
i  n  FI  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


ings  ( 

i nPresentati on , 
i nStream , 
*outSetti ngs , 
i  n Ff  ags  )  ; 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


QTSPresGetSettings  AsT  ext 


Undocumented 


OSErr  QTSPresGetSettingsAsText  ( 


QTSPresentati on 

QTSStream 

SInt32 

OSType 

Handl e 

QTSPanel FilterUPP 
voi  d 


i nPresentati on , 
i nStream , 
i  n FI  ags  , 
i nSetti ngsType , 

*outText , 

i nPanel Fi 1 terProc , 

*i nPanel Fi 1 terProcRefCon  ); 


11-1280 


Inside  QuickTime:  Function  l-Q 


QTSPresGetTimeBase 


i nPresentati on 
Undocumented 
i nStream 

Undocumented 
i  n  FI  ags 

Undocumented 
l nSetti ngsType 
Undocumented 
outText 

Undocumented 
i nPanel Fi 1 terProc 
Undocumented 
i n Panel Fi 1 terProc Ref Con 
Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSPresGetTimeBase 


Undocumented 

OSErr  QTSPresGetTimeBase  ( 

QTSPresentation  i nPresentati on, 

TimeBase  *outTimeBase  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentation  Re  cord  (IV-2379)  structure. 
outT i meBase 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 


Inside  QuickTime:  Function  l-Q 


11-1281 


QTSPresGetTimeScale 


Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSPresGetTimeScale 

Undocumented 

OSErr  QTSPresGetTimeScale  ( 

QTSPresentati on  inPresentation, 

TimeScale  *outTi meScal e  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure. 
outT i meScal e 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


QTSPresGetVolumes 

Gets  the  sound  volume  levels  of  a  stream  or  presentation. 

OSErr  QTSPresGetVolumes  ( 

QTSPresentati on  inPresentation, 

QTSStream  inStream, 

short  *outl_eftVol  ume , 

short  *outRi ghtVol ume  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure  that  defines  a 
presentation.  If  you  want  to  get  the  volumes  for  a  specific  stream,  pass  the  value 
kQTSInval i dPresentati on. 
i nStream 

A  pointer  to  a  QTSStream  Re  cord  (IV-2387)  structure  that  defines  a  stream.  If  you 
want  to  get  the  volumes  for  the  presentation  as  a  whole,  pass  the  value 
kQTSAl 1  Streams. 


11-1282 


Inside  QuickTime:  Function  l-Q 


QTSPresHasCharacteristic 


outLeftVol ume 

On  exit,  the  volume  level  of  the  left  channel  of  the  stream  or  presentation.  The 
values  returned  may  range  from  0x0000  (silence)  to  0x0100  (full  volume). 
outRi  ghtVol  ume 

On  exit,  the  volume  level  of  the  right  channel  of  the  stream  or  presentation.  The 
values  returned  may  range  from  0x0000  (silence)  to  0x0100  (full  volume). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 

See  Also 

For  the  corresponding  set  function,  see  QTSPresSetVol  umes  (11-1301). 

QTSPresHasCharacteristic 

Undocumented 

OSErr  QTSPresHasCharacteristic  ( 

QTSPresentation  inPresentation, 

QTSStream  inStream, 

OSType  i nCharacteri Stic, 

Boolean  *outHasIt  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentation  Re  cord  (IV-2379)  structure, 
i nStream 

A  pointer  to  a  QTSStream  Re  cord  (IV-2387)  structure  that  defines  a  stream, 
i nCharacteri sti c 
Undocumented 
outHas It 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


Inside  QuickTime:  Function  l-Q 


11-1283 


QTSPresIdle 


QTSPresIdle 

Undocumented 

void  QTSPresIdle  ( 

QTSPresentati on 
QTSPresIdl eParams 

i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure, 
i oParams 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 

QTSPresInvalidateRegion 

Undocumented 

OSErr  QTSPresInvalidateRegion  ( 

QTSPresentati on  inPresentation, 

RgnHandle  inRegion  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure, 
i nRegi on 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i  meStreami  ng .  h 

QTSPresNewStream 

Undocumented 


i nPresentati on , 
*i oParams  ) ; 


11-1284 


Inside  QuickTime:  Function  l-Q 


QTSPresPreroll 


OSErr  QTSPresNewStream  ( 


QTSPresentati  on 

OSType 

const  void 

UInt32 

SInt32 

QTSStream 


i nPresentati on , 
i nDataType , 

*i  nData , 
i nData  Length , 
i  n  FI  ags  , 
*outStream  ); 


l nPresentati on 

A  pointer  to  a  QTSPresentati  on  Re  cord  (IV-2379)  structure, 
i nDataType 

Undocumented 
i nData 

Undocumented 
i nDataLength 

Undocumented 
i n FI  ags 

Undocumented 

outStream 

A  pointer  to  a  QTSStream  Re  cord  (IV-2387)  structure  that  defines  a  stream. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inFlags  Constants 

Undocumented 

Undocumented 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSPresPreroll 


Undocumented 

( 

i nPresentati on , 
i nStream, 
i nT i meVal ue , 
i  nRate , 
inFlags  ); 


OSErr  QTSPresPreroll 
QTSPresentati on 
QTSStream 
UInt32 
Fi  xed 
SInt32 


Inside  QuickTime:  Function  l-Q 


11-1285 


QTSPresPreroll64 


i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure. 

1 nStream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure  that  defines  a  stream. 

1 nT imeVal ue 

Undocumented 
1 nRate 

Undocumented 
1  n FI  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inFlags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


QTSPresPreroll64 


Undocumented 


OSErr  QTSPresPrerol 1 64 
QTSPresentati on 
QTSStream 
const  TimeValue64 
Fi  xed 
SInt32 


i nPresentati on , 
i nStream , 

*i nPrerol 1 Ti me , 
i nRate , 
i  n FI  ags  )  ; 


i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure, 
i nStream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure  that  defines  a  stream, 
i nPrerol 1  Time 

Undocumented 


11-1286 


Inside  QuickTime:  Function  l-Q 


QTSPresPreview 


i  nRate 

Undocumented 
1  n FI  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inFlags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSPresPreview 


Undocumented 

OSErr  QTSPresPreview  ( 

QTSPresentati on 
QTSStream 
const  TimeValue64 
Fi  xed 
SInt32 

l nPresentati on 
Undocumented 
i nStream 

Undocumented 
i nT i meVal ue 

Undocumented 
i  nRate 

Undocumented 
i  n  FI  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 


i nPresentati on , 
i nStream, 

*i nTi meVal ue , 
i nRate , 
inFlags  ); 


Inside  QuickTime:  Function  l-Q 


11-1287 


QTSPresRemoveSourcer 


Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSPresRemoveSourcer 


Undocumented 


OSErr  QTSPresRemoveSo 
QTSPresentati on 
QTSStream 
Componentlnstance 
SInt32 

i nPresentati on 
Undocumented 
i nStream 

Undocumented 
i  nSourcer 

Undocumented 
i  n  FI  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


urcer  ( 

i nPresentati on , 
i nStream , 
i nSourcer , 
i  n FI  ags  ) ; 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


QTSPresSetActiveSegment 


Undocumented 


OSErr  QTSPresSetActiveSegment  ( 

QTSPresentati on  inPresentation, 

QTSStream  inStream, 

const  TimeValue64  *inStartTime, 

const  TimeValue64  *inDuration  ); 


i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure. 


11-1288 


Inside  QuickTime:  Function  l-Q 


QTSPresSetClip 


i nStream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure  that  defines  a  stream, 
i nStartTime 

Undocumented 
l nDurati on 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 

See  Also 

For  the  corresponding  get  function,  see  QTSPresGetActi  veSegment  (11-1265). 


QTSPresSetClip 

Undocumented 

OSErr  QTSPresSetClip  ( 

QTSPresentati on  i nPresentati on  , 

QTSStream  inStream, 

RgnHandle  inClip  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentati  on  Re  cord  (IV-2379)  structure, 
i nStream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure  that  defines  a  stream, 
i  nCl  i  p 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 

See  Also 

For  the  corresponding  get  function,  see  QTSPresGetCl  i  p  (11-1266). 


Inside  QuickTime:  Function  l-Q 


11-1289 


QTSPresSetDimensions 


QTSPresSetDimensions 


Undocumented 


OSErr  QTSPresSetDimensions  ( 

QTSPresentation  inPresentation, 
QTSStream  inStream, 

Fixed  inWidth, 

Fi xed  i nHei ght  ) ; 


i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure, 
i nStream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure  that  defines  a  stream, 
i nWi dth 

Undocumented 
i nHei ght 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 

See  Also 

For  the  corresponding  get  function,  see  QTSPresGetDimensi  ons  (11-1266). 


QTSPresSetEnable 


Undocumented 

OSErr  QTSPresSetEnable  ( 

QTSPresentation  inPresentation, 

QTSStream  inStream, 

Boolean  inEnableMode  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure, 
i nStream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure  that  defines  a  stream. 


11-1290 


Inside  QuickTime:  Function  l-Q 


QTSPresSetFlags 


i nEnabl eMode 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 

See  Also 

For  the  corresponding  get  function,  see  QTSPresGetEnabl  e  (11-1267). 


QTSPresSetFlags 


Undocumented 


OSErr  QTSPresSetFlags  ( 

QTSPresentation  inPresentation, 

SInt32  inFlags, 

SInt32  inFlagsMask  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentation  Re  cord  (IV-2379)  structure, 
i  n  FI  ags 

Undocumented 
i  n  FI  agsMask 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inFlags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 

See  Also 

For  the  corresponding  get  function,  see  QTSPresGetFl  ags  (11-1268). 


Inside  QuickTime:  Function  l-Q 


11-1291 


QTSPresSetGraphicsMode 


QTSPresSetGraphicsMode 

Sets  the  graphics  transfer  mode  for  a  streaming  presentation. 

OSErr  QTSPresSetGraphicsMode  ( 

QTSPresentati on  inPresentation, 

QTSStream  inStream, 

short  inMode, 

const  RGBColor  *inOpColor  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure, 
i nStream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure  that  defines  a  stream, 
i nMode 

A  short  integer;  see  "Graphics  Transfer  Modes"  (IV-2670). 
i nOpCol or 

A  pointer  to  an  RGBCol  or  (IV-2403)  structure.  This  is  the  blend  value  for  blends 
and  the  transparent  color  for  transparent  operations.  The  toolbox  supplies  this 
value  to  QuickDraw  when  you  draw  in  addPi  n,  subPi  n,  bl  end,  transparent,  or 
graphi  csModeStrai  ghtAl  phaBl  end  mode. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 

See  Also 

For  the  corresponding  get  function,  see  QTSPresGetGraphi  csMode  (11-1269). 

QTSPresSetGWorld 

Undocumented 

OSErr  QTSPresSetGWorld  ( 

QTSPresentati on  inPresentation, 

QTSStream  inStream, 

CGrafPtr  inGWorld, 

GDHandle  inGDHandle  ); 


11-1292 


Inside  QuickTime:  Function  l-Q 


QTSPresSetlnfo 


i nPresentati on 

A  pointer  to  a  QTSPresentationRecord  (IV-2379)  structure, 
i nStream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure  that  defines  a  stream, 
i  nGWorl  d 

Undocumented 
i nGDHandl e 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 

See  Also 

For  the  corresponding  get  function,  see  QTSPresGetGWorl  d  (11-1270). 


QTSPresSetlnfo 


Sets  information  for  a  presentation  or  stream. 

OSErr  QTSPresSetlnfo  ( 

QTSPresentati on 
QTSStream 
OSType 
void 

i nPresentati on 

A  pointer  to  a  QTSPresentati  on  Re  cord  (IV-2379)  structure  that  defines  a 
presentation.  If  you  want  to  set  information  for  a  specific  stream,  pass  the  value 
kQTSInval idPresentation. 
i nStream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure  that  defines  a  stream.  If  you 
want  to  set  information  for  the  presentation  as  a  whole,  pass  the  value 
kQTSAl 1  Streams. 

i nSel ector 

A  constant  (see  below)  that  defines  the  type  of  information  to  be  set. 


i nPresentati on , 
i nStream, 
i nSel ector , 
*ioParam  ); 


Inside  QuickTime:  Function  l-Q 


11-1293 


QTSPresSetlnfo 


i oParam 

A  pointer  to  the  information  to  be  set  in  the  format  shown  below. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inSelector  Constants 

kQTSGetURLLi nk 

A  URL  as  a  QTSGetURLLi  nkRecord  (IV-2371)  structure;  constant  value  is  'gull  '. 
kQTSTargetBufferDurati  on  Info 

The  expected  (not  necessarily  actual)  buffer  duration  in  seconds,  as  a  Fixed 
value;  constant  value  is  '  but r ' . 
kQTSDurati onlnfo 

Duration  as  a  QTSDurati  onAtom  (IV-2369)  structure;  constant  value  is  '  dura  ' . 
kQTSSourceT  rackIDInfo 

The  source  track  ID  as  a  UInt32;  constant  value  is  '  oti  d ' . 
kQTSSource Layer  Info 

The  source  layer  number  as  a  U I  n  1 1 6;  constant  value  is  '  o  1  y  r ' . 
kQTSSource Language  Info 

The  source  language  code  as  a  U Inti 6;  constant  value  is  '  ol  ng ' .  See 
"Localization  Codes"  (IV-2673). 
kQTSSourceT  rackLlagsInfo 

The  source  track  flag  set  as  an  S I  n  1 3  2;  constant  value  is  '  o t  f  1 ' . 
kQTSSourceDi mens i ons Info 

The  source  dimensions  as  a  QTSDi mensi  onParams  (IV-2368)  structure;  constant 
value  is  'odim'. 
kQTSSource Vo 1 umeslnfo 

The  source  sound  volumes  as  a  QTSVol  umes  Pa  rams  (IV-2390)  structure;  constant 
value  is  '  ovol  ' . 
kQTSSourceMatri xlnfo 

The  source  matrix  as  a  Matri  xRecord  (IV-2304)  structure;  constant  value  is 
' omat ' . 

kQTSSourceCl i pRectlnfo 

The  source  clipping  rectangle  as  a  Rect  (IV-2399)  structure;  constant  value  is 
'  ocl  p ' . 

kQTSSourceGraphi csModelnfo 

The  source  graphics  mode  as  a  QTSGraphi  csModeParams  (IV-2372)  structure; 
constant  value  is  'ogrm'. 


11-1294 


Inside  QuickTime:  Function  l-Q 


QTS  Pres  S  etMatrix 


kQTSSourceScal elnfo 

The  source  scaling  factors  as  a  Point  (IV-2339)  structure;  constant  value  is 
' oscl  ’ . 

kQTSSourceBoundi ngRectlnfo 

The  source  bounding  rectangle  as  a  Rect  (IV-2399)  structure;  constant  value  is 
' orct  ’ . 

kQTSSourceUserData Inf o 

The  source's  user  data  as  a  UserDataRecord  (IV-2496)  structure;  constant  value 
is  1  oudt 1 . 

kQTSSourcelnputMapInf o 

The  source  input  map  as  a  QT  atom  container;  constant  value  is  ’  oimp  ’ . 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 

See  Also 

For  the  corresponding  get  function,  see  QTSPresGetlnfo  (11-1272). 


QTSPresSetMatrix 


Sets  the  transformation  matrix  to  be  used  by  the  graphic  display  of  a  stream  or 
presentation. 

OSErr  QTSPresSetMatrix  ( 

QTSPresentati on 
QTSStream 
const  MatrixRecord 

i nPresentati on 

A  pointer  to  a  QTSPresentati  on  Re  cord  (IV-2379)  structure  that  defines  a 
presentation.  If  you  want  to  set  the  matrix  for  a  specific  stream,  pass  the  value 
kQTSInval idPresentation. 
i nStream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure  that  defines  a  stream.  If  you 
want  to  set  the  matrix  for  the  presentation  as  a  whole,  pass  the  value 
kQTSAl 1  Streams, 
i nMatri x 

A  pointer  to  a  MatrixRecord  (IV-2304)  structure. 


i nPresentati on , 
i nStream, 

*i nMatri x  ); 


Inside  QuickTime:  Function  l-Q 


11-1295 


QTSPresSetNotificationProc 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 

See  Also 

For  the  corresponding  get  function,  see  QTSPresGetMatri x  (11-1275). 


QTSPresSetNotificationProc 

Sets  the  notification  callback  for  a  presentation. 

OSErr  QTSPresSetNotificationProc  ( 

QTSPresentati on  inPresentation, 

QTSNotificationUPP  inNotificationProc, 
voi d  *i nRefCon  ) ; 

i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure, 
i nNoti f i cati onProc 

A  Universal  Procedure  Pointer  that  accesses  a  QTSNoti  f  i  cati  onProc  (III— 2126) 
callback.  The  callback  acts  as  a  back  channel  from  a  presentation  to  its  creator. 
The  presentation  sends  notification  of  various  events,  such  as  a  presentation, 
ending,  or  acknowledgment  of  a  preroll  request. 

i nRefCon 

A  pointer  to  data  to  be  passed  to  your  QTSNoti  f  i  cati  onProc. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i  meStreami  ng .  h 

See  Also 

For  the  corresponding  get  function,  see  QTSPresGetNoti  f  i  cati  onProc  (11-1275). 


QTSPresSetPlayHints 

Undocumented 


11-1296 


Inside  QuickTime:  Function  l-Q 


QTSPresSetPreferredRate 


OSErr  QTSPresSetPl  ayHi  nts  ( 

QTSPresentati on  i nPresentati on , 
QTSStream  inStream, 

SInt32  inFlags, 

SInt32  inFlagsMask  ); 


i nPresentati on 

A  pointer  to  a  QTSPresentati  on  Re  cord  (IV-2379)  structure  that  defines  a 
presentation.  If  you  want  to  set  the  play  hints  for  a  specific  stream,  pass  the 
value  kQTSInval  idPresentation. 
i nStream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure  that  defines  a  stream.  If  you 
want  to  set  the  play  hints  for  the  presentation  as  a  whole,  pass  the  value 
kQTSAl 1  Streams, 
i  nFl  ags 

Undocumented 
i nFl  agsMask 

Undocumented 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inFlags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 

See  Also 

For  the  corresponding  get  function,  see  QTSPresGetPl  ayHi  nts  (11-1278). 


QTSPresSetPreferredRate 


Undocumented 

OSErr  QTSPresSetPreferredRate  ( 

QTSPresentati on  i nPresentati on. 

Fixed  in  Rate, 

SInt32  inFlags  ); 


Inside  QuickTime:  Function  l-Q 


11-1297 


QTSPresSetPresenting 


i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure, 
i nRate 

Undocumented 
1  n FI  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inFlags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 

See  Also 

For  the  corresponding  get  function,  see  QTSPresGetPreferredRate  (11-1278). 


QTSPresSetPresenting 


Enables  or  disables  presentation  of  a  stream  to  the  user. 

OSErr  QTSPresSetPresenting  ( 

QTSPresentati on  inPresentation, 

QTSStream  inStream, 

Boolean  i nPresenti ngMode  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure  that  defines  a 
presentation.  If  you  want  to  enable  or  disable  the  presentation  for  a  specific 
stream,  pass  the  value  kQTSInval  i  dPresentati  on. 
i nStream 

A  pointer  toaQTSStreamRecord  (IV-2387)  structure  that  defines  a  stream.  If  you 
want  to  enable  or  disable  the  presentation  as  a  whole,  pass  the  value 
kQTSAl 1  Streams, 
i nPresenti ngMode 

Pass  TRUE  to  enable  the  presentation,  FALSE  to  disable  it. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


11-1298 


Inside  QuickTime:  Function  l-Q 


QTSPresSetSettings 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 

See  Also 

For  the  corresponding  get  function,  see  QTSPresGetPresenti  ng  (11-1279). 


QTSPresSetSettings 


Undocumented 


OSErr  QTSPresSetSett 
QTSPresentati on 
QTSStream 
QTAtomSpecPtr 
SInt32 

i nPresentati on 
Undocumented 
i nStream 

Undocumented 
l nSettl ngs 

Undocumented 
i  n  FI  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


i  n  g  s  ( 

i nPresentati on , 
i nStream, 
i nSetti ngs , 
inFlags  ); 


QTSPresSettingsDialog 


Undocumented 

OSErr  QTSPresSettingsDialog  ( 

QTSPresentati on  i nPresentati on  , 

QTSStream  inStream, 


Inside  QuickTime:  Function  l-Q 


11-1299 


QTSPresSettingsDialogWithFilters 


SInt32  inFlags, 

QTSModal FilterUPP  inFilterProc, 

void  *inFi 1 terProcRefCon  ); 

i nPresentati on 
Undocumented 
i nStream 

Undocumented 
i  n  FI  ags 

Undocumented 
inFi  1  terProc 

Undocumented 
inFi 1 terProcRefCon 
Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


QTSPresSettingsDialogWithFilters 


Undocumented 


OSErr  QTSPresSetti ngsDi 
QTSPresentati on 
QTSStream 
SInt32 

QTSModal FilterUPP 
voi  d 

QTSPanel FilterUPP 
voi  d 


1 ogWi t h F i 1 ters  ( 
i nPresentati on , 
i nStream , 
i  n FI  ags  , 
inFi  1  terProc , 

*inFil terProcRefCon, 
i nPanel Fi 1 terProc , 

*i nPanel Fi 1 terProcRefCon  ); 


i nPresentati on 
Undocumented 
i nStream 

Undocumented 
i  n  FI  ags 

Undocumented 


11-1300 


Inside  QuickTime:  Function  l-Q 


QTSPresSet  Volumes 


i n  F i 1 terProc 

Undocumented 
i nFi 1 terProc Ref Con 
Undocumented 
l nPanel Fi 1 terProc 
Undocumented 
i n Panel Fi 1 terProcRefCon 
Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 

QTSPresSetVolumes 

Sets  the  sound  volume  levels  of  a  stream  or  presentation. 

OSErr  QTSPresSetVolumes  ( 

QTSPresentati on  i nPresentati on  , 

QTSStream  inStream, 

short  i nLeftVol ume , 

short  i  nRi  ghtVol  ume  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentati  on  Re  cord  (IV-2379)  structure  that  defines  a 
presentation.  If  you  want  to  set  the  volume  of  a  specific  stream,  pass  the  value 
kQTSInval idPresentation. 

i nStream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure  that  defines  a  stream.  If  you 
want  to  set  the  volume  of  the  presentation  as  a  whole,  pass  the  value 
kQTSAl 1  Streams, 
i nLeftVol ume 

The  volume  level  to  be  set  for  the  left  channel  of  the  stream  or  presentation.  The 
values  may  range  from  0x0000  (silence)  to  0x0100  (full  volume). 

i  nRi  ghtVol  ume 

The  volume  level  to  be  set  for  the  right  channel  of  the  stream  or  presentation. 
The  values  may  range  from  0x0000  (silence)  to  0x0100  (full  volume). 


Inside  QuickTime:  Function  l-Q 


11-1301 


QTSPresSkipTo 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 

See  Also 

For  the  corresponding  get  function,  see  QTSPresGetVol  umes  (11-1282). 


QTSPresSkipTo 

Requests  that  a  presentation  skip  to  a  given  point,  specified  by  a  time  value. 

OSErr  QTSPresSkipTo  ( 

QTSPresentati on  inPresentation, 

UInt32  inTimeValue  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure, 
i nT imeVal ue 

The  time  value  to  skip  to,  expressed  in  the  time  scale  of  the  presentation. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i  meStreami  ng .  h 


QTSPresSkipT  o64 


Requests  that  a  streaming  presentation  skip  to  a  given  point,  specified  by  a  64-bit 
time  value. 

OSErr  QTSPresSkipTo64  ( 

QTSPresentati on  inPresentation, 

const  TimeValue64  *inTimeValue  ); 

i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure. 


11-1302 


Inside  QuickTime:  Function  l-Q 


QTSPresStart 


i nT i meVal ue 

A  pointer  to  a  signed  64-bit  integer  that  contains  the  time  value  to  skip  to, 
expressed  in  the  time  scale  of  the  presentation. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSPresStart 


Starts  a  streaming  presentation  or  a  stream. 

OSErr  QTSPresStart  ( 

QTSPresentati on 
QTSStream 
SInt32 

i nPresentati on 

A  pointer  to  a  QTSPresentati  on  Re  cord  (IV-2379)  structure  that  defines  a 
presentation.  If  you  want  to  start  a  specific  stream,  pass  the  value 
kQTSInval idPresentation. 

i nStream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure  that  defines  a  stream.  If  you 
want  to  start  the  presentation  as  a  whole,  pass  the  value  kQTSAl  1  Streams. 

i n FI  ags 

Flags  (see  below)  that  govern  the  starting  of  the  presentation  or  stream. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inFlags  Constants 

kQTSSyncControl FI ag 
Undocumented 

kQTSTi meBaseRunningControl  Flag 
Undocumented 

Discussion 

If  QTSPresPrerol  1  (11-1285)  has  not  been  called,  QuickTime  must  set  up  the  streams 
and  do  everything  that  would  have  been  done  in  preroll.  If  the  presentation  has 
already  been  prerolled,  it  should  be  ready  to  start  immediately. 


i nPresentati on , 
i nStream, 
inFlags  ); 


Inside  QuickTime:  Function  l-Q 


11-1303 


QTSPresStop 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


QTSPresStop 


Stops  a  streaming  presentation  or  stream. 

OSErr  QTSPresStop  ( 

QTSPresentati on 
QTSStream 
SInt32 

i nPresentati on 

A  pointer  to  a  QTSPresentati  onRecord  (IV-2379)  structure  that  defines  a 
presentation.  If  you  want  to  stop  a  specific  stream,  pass  the  value 
kQTSInval i dPresentati on. 

i nStream 

A  pointer  to  a  QTSStream  Re  cord  (IV-2387)  structure  that  defines  a  stream.  If  you 
want  to  stop  the  presentation  as  a  whole,  pass  the  value  kQTSAl  1  Streams.  All 
audio  and  video  output  will  cease, 
i  n FI  ags 

Flags  that  govern  the  stopping  of  the  presentation  or  stream.  No  flags  are 
currently  defined. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i  meStreami  ng .  h 


i nPresentati on , 
i nStream , 
i  n FI  ags  ) ; 


QTSReleaseMemPtr 


Disposes  of  a  pointer  to  a  streaming  buffer  that  will  be  recirculated. 

void  QTSReleaseMemPtr  ( 

QTSMemPtr  inMemPtr, 

SInt32  i n Ft ags  ) ; 


11-1304 


Inside  QuickTime:  Function  l-Q 


QTSSetNetworkAppName 


i nMemPtr 

A  pointer  to  an  opaque  structure, 
i  n  FI  ags 

Undocumented 

inFlags  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSSetNetworkAppName 


Sets  the  name  of  a  streaming  network  application. 

OSErr  QTSSetNetworkAppName  ( 
const  char  *inAppName, 

SInt32  inFlags  ); 


i  nAppName 

A  pointer  to  a  string  containing  the  application's  name, 
i  n FI  ags 

A  flag  (see  below)  that  determines  whether  the  name  is  a  full  pathname. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inFlags  Constants 

kQTSNetworkAppNamelsFul  1  Name FI  a g 

The  application  name  is  a  full  pathname. 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


See  Also 

For  the  corresponding  get  function,  see  QTSGetNetworkAppName  (11-1237). 


Inside  QuickTime:  Function  l-Q 


11-1305 


QTSSourcerGetEnable 


QTSSourcerGetEnable 


Undocumented 

ComponentResul t  QTSSourcerGetEnable  ( 

QTSSourcer  inSourcer, 

Boolean  *outEnabl eMode , 

SInt32  i n FI ags  ) ; 

i nSourcer 

Undocumented 

outEnabl eMode 

Undocumented 

i  n  FI  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


QTSSourcerGetlnfo 


Undocumented 

ComponentResul t  QTSSourcerGetlnfo  ( 

QTSSourcer  inSourcer, 

OSType  inSelector, 

voi d  *i oParams  ) ; 

i nSourcer 

Undocumented 

i nSel ector 

Undocumented 

i oParams 

Undocumented 

function  residt  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


11-1306 


Inside  QuickTime:  Function  l-Q 


QTS  S  ourcerG  etTime  S  cale 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


QTSSourcerGetTimeScale 

Undocumented 

ComponentResul t  QTSSourcerGetTimeScale  ( 

QTSSourcer  inSourcer, 

TimeScale  *outTimeScale  ); 

i nSourcer 

Undocumented 
outT i meScal e 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


QTSSourcerldle 


Undocumented 


ComponentResul t  QTSSourcerldle  ( 


QTSSourcer 

const  TimeValue64 

SInt32 

SInt32 


i nSourcer 
*inTime, 
i  n  FI  ags  , 
*outFl ags 


): 


i nSourcer 

Undocumented 

inTime 

Undocumented 


Inside  QuickTime:  Function  l-Q 


11-1307 


QTSSourcerlnitialize 


i  n FI  ags 

Undocumented 

outFl  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 

QTSSourcerlnitialize 

Undocumented 

ComponentResul t  QTSSourcerlnitialize  ( 

QTSSourcer  inSourcer, 

const  QTSSourcerlni tParams  *inlni tParams  ); 

i nSourcer 

Undocumented 

i nlni tParams 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 

QTSSourcerSetEnable 

Undocumented 

ComponentResul t  QTSSourcerSetEnable  ( 

QTSSourcer  inSourcer, 

Boolean  i nEnabl eMode , 

SInt32  i n FI ags  ) ; 


11-1308 


Inside  QuickTime:  Function  l-Q 


QTSSourcerSetlnfo 


i nSourcer 

Undocumented 
i nEnabl eMode 

Undocumented 
i  n  FI  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


QTSSourcerSetlnfo 


Undocumented 

ComponentResui t  QTSSourcerSetlnfo  ( 

QTSSourcer  inSourcer, 

OSType  inSelector, 

void  *ioParams  ); 

i nSourcer 

Undocumented 
i nSel ector 

Undocumented 
i oParams 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


QTSSourcerSetTimeScale 

Undocumented 


Inside  QuickTime:  Function  l-Q 


11-1309 


QTSStatHelperGetNumStats 


ComponentResul t  QTSSourcerSetTimeScale  ( 

QTSSourcer  inSourcer, 

TimeScale  inTimeScale  ); 

i nSourcer 

Undocumented 

inTimeScale 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


QTSStatHelperGetNumStats 


Gets  the  number  of  statistics  that  a  statistic  helper  is  reporting. 

UInt32  QTSStatHelperGetNumStats  ( 

QTSStatHel per  inStatHelper  ); 

i nStatHel per 

A  pointer  to  a  QTSStatHel  per  Re  cord  (IV-2384)  structure  that  defines  the 
component  instance  of  a  statistics  helper. 

function  result  The  number  of  statistics. 

Discussion 

You  can  also  find  the  number  of  statistics  that  a  statistics  helper  is  reporting  by 
calling  QTSStatHel  perResetlter  (11-1312),  then  calling  QTSStatHel  perNext  (11-1311) 
iteratively  until  it  returns  FALSE  and  counting  the  iterations. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


QTSStatHelperGetStats 


Tells  a  statistics  helper  to  update  its  statistics. 


11-1310 


Inside  QuickTime:  Function  l-Q 


QTSStatHelperNext 


OSErr  QTSStatHel perGetStats  ( 

QTSStatHel per  i nStatHel per  ); 

i nStatHel per 

A  pointer  to  a  QTSStatHel  per  Re  cord  (IV-2384)  structure  that  defines  the 
component  instance  of  a  statistics  helper. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Statistics  helpers  update  their  statistics  only  when  this  function  is  called.  You 
should  call  it  at  least  once  before  calling  QTSStatHel  per  Next  (11-1311),  to  ensure  that 
the  information  returned  is  valid  and  current.  The  normal  sequence  is  to  call  this 
function,  then  call  QTSStatHel  perResetlter  (11-1312),  then  make  a  series  of  calls  to 
QTSStatHel  perNext  (11-1311). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSStatHelperNext 


Gets  the  next  statistic  from  a  statistic  helper. 

Boolean  QTSStatHelperNext  ( 

QTSStatHel per  i nStatHel per , 

QTSStatHel perNextParams  *ioParams  ); 

i nStatHel per 

A  pointer  to  a  QTSStatHel  per  Re  cord  (IV-2384)  structure  that  defines  the 
component  instance  of  a  statistics  helper, 
i oParams 

On  entry,  a  pointer  to  a  QTSStatHel  perNextParams  (IV-2382)  structure;  on  return, 
this  structure  is  filled  in  with  information  about  the  next  statistic  from  the 
specified  statistic  helper. 

function  result  FALSE  if  the  last  statistic  has  been  returned,  TRUE  otherwise. 

Discussion 

You  need  to  call  this  function  once  to  retrieve  each  statistic.  The  normal  sequence  is 
to  call  QTSStatHel  perGetStats  (11-1310),  then  call  QTSStatHel  perResetlter  (11-1312), 
then  make  a  series  of  calls  to  this  function  until  it  returns  FALSE. 


Inside  QuickTime:  Function  l-Q 


11-1311 


QTSStatHelperResetlter 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


QTSStatHelperResetlter 


Reset  the  iteration  counter  of  a  statistics  helper,  so  the  next  call  toQTSStatHelperNext 
(11-1311)  returns  the  first  statistic. 

OSErr  QTSStatHelperResetlter  ( 

QTSStatHel per  inStatHelper  ); 

i nStatHel per 

A  pointer  to  a  QTSStatHel  per  Re  cord  (IV-2384)  structure  that  defines  the 
component  instance  of  a  statistics  helper. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i  meStreami  ng .  h 

See  Also 

See  QTSStatHel  perNext  (11-1311). 


QTSStreamBufferDatalnfo 


Undocumented 

void  QTSStreamBufferDatalnfo  ( 

QTSStreamBuffer  *i nStreamBuffer , 

unsigned  char  **outDataStart , 

UInt32  *outDataMaxl_ength  ); 

i nStreamBuffer 
Undocumented 
outDataStart 

Undocumented 


11-1312 


Inside  QuickTime:  Function  l-Q 


QTStandardParameterDialogDoAction 


outDataMaxLength 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTStandardParameterDialogDoAction 

Lets  you  change  some  of  the  default  behaviors  of  the  standard  parameter  dialog 
box. 

OSErr  QTStandardParameterDi al  ogDoAction  ( 

QTParameterDi alog  createdDialog, 

long  action, 

void  *params  ); 

createdDi al og 

The  reference  to  the  dialog  box  created  by  calling 
QTCreateStandardParameterDi  al  og  (11-1161). 

acti on 

Determines  which  of  the  actions  (see  below)  supported  by  this  function  will  be 
performed. 

params 

Optional  parameters  to  the  action.  The  type  passed  in  this  parameter  depends 
on  the  value  of  the  action  parameter. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

action  Constants 

pdActi onSetAppl eMenu 

Use  this  selector  to  make  the  Apple  menu  available  while  the  standard 
parameter  dialog  box  is  active.  Pass  the  MenuHandl  e  of  the  Apple  menu  in  the 
params  parameter. 
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QTStandardParameterDialogDoAction 


pdActi on Set  Ed i tMenu 

Use  this  action  to  make  your  application's  Edit  menu  available  while  the 
standard  parameters  dialog  box  is  active.  Pass  the  MenuHandle  of  the  Edit  menu 
in  the  pa  rams  parameter. 
pdActi onSetPreviewPicture 

Use  this  action  to  change  the  images  that  are  used  in  the  preview  window  of 
the  standard  parameters  dialog  box.  QuickTime  provides  default  images  but 
you  may  wish,  for  example,  to  use  thumbnail  images  taken  from  your 
application  instead.  The  params  parameter  contains  a  QTParamPrevi  ewPtr 
referencing  the  image  to  use. 

pdActi onSetDi al ogTi tl e 

Sets  the  title  of  the  standard  parameters  dialog  box.  The  params  parameters 
contains  a  Pascal  St r 255  string. 
pdActi onGetSubPanelMenu 

Returns  a  list  of  the  sub-panels  used  by  the  standard  parameters  dialog  box.  If 
there  are  more  parameter  controls  than  can  fit  into  the  available  area  of  the 
dialog  box,  the  parameters  are  automatically  split  into  sub-panels  (usually  by 
segmenting  the  set  of  parameters  by  group).  The  pop-up  menu  used  to  switch 
between  the  panels  is  returned  as  a  MenuHandl  e  in  the  params  parameter. 
pdActi onActivateSubPanel 

Sets  the  current  sub-panel.  The  params  parameter  contains  a  long  integer  that  is 
the  number  of  the  panel  to  be  displayed. 

pdActi onConductStopAler 

Displays  a  Stop  alert.  The  params  parameter  contains  a  Stri ngPtr  that  is 
displayed  in  the  alert.  This  feature  can  be  used  in  conjunction  with 
ImageCodecVal  i  dateParameters  (11-745)  to  inform  the  user  when  invalid 
parameter  values  have  been  entered. 

Discussion 

This  function  allows  you  to  change  some  of  the  default  behaviors  of  a  standard 
parameter  dialog  box  you  create  using  the  QTCreateStandardParameterDi  al  og 
(11-1161)  function.  To  choose  which  of  the  available  customizations  to  perform,  pass 
an  action  selector  value  in  the  action  parameter  and,  optionally,  a  single  parameter 
in  params. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "High-Level  Effects  Functions"  (V-2897) 
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QTSwapAtoms 


QTSwapAtoms 

Swaps  the  contents  of  two  atoms  in  an  atom  container. 

OSErr  QTSwapAtoms  ( 

QTAtomContai ner 
QTAtom 
QTAtom 

contai ner 

The  atom  container  for  this  operation, 
atoml 

Specifies  an  atom  to  be  swapped  with  the  atom  specified  by  atom2. 
atom2 

Specifies  an  atom  to  be  swapped  with  the  atom  specified  by  atoml. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

After  swapping,  the  ID  and  index  of  each  atom  remains  the  same.  The  two  atoms 
specified  must  be  of  the  same  type.  Either  atom  may  be  a  leaf  atom  or  a  container 
atom. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Copying  Existing  Atoms"  (V-2767) 

Related  Java  Methods 

qui cktime . std .movi es . AtomContai ner . swapAtoms ( ) 


contai ner, 
atoml , 
atom2  ); 


QTT  extToN  ati  veT  ext 


Undocumented 


OSErr  QTTextToNati veText  ( 
Handle  theText, 

long  encoding, 

long  flags  ); 
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QTUnlockContainer 


theText 

Undocumented 
encodi ng 

Undocumented 
fl  ags 

Flags  (see  below)  that  define  the  text  atom  type. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

flags  Constants 

kITextAtomType 

International  text  atom;  value  is  '  i  txt ' . 
kITextStri ngAtomType 

String  atom;  value  is  '  text ' . 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 


QTUnlockContainer 


Unlocks  an  atom  container  in  memory. 

OSErr  QTUnlockContainer  ( 

QTAtomContai ner  container  ); 

contai ner 

The  atom  container  to  be  unlocked. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

You  should  call  this  function  to  unlock  an  atom  container  when  you  have  finished 
accessing  a  leaf  atom's  data.  You  may  make  nested  pairs  of  calls  to  QTLockContai  ner 
(11—1187)  and  this  function;  you  don't  need  to  check  the  current  state  of  the  container 
first. 
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QTUnregisterAccessKey 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Retrieving  Atoms  and  Atom  Data"  (V-2768) 


QTUnregisterAccessKey 

Removes  a  previously  registered  access  key. 

OSErr  QTUnregisterAccessKey  ( 

Str255  accessKeyType , 

long  flags. 

Handle  accessKey  ); 

accessKeyType 

The  access  key  type  of  the  key  to  be  removed, 
fl  ags 

Flags  (see  below)  that  specify  the  operation  of  this  function.  To  remove  a  system 
access  key,  set  the  kAccessKeySystemFl  ag  flag.  To  remove  an  application  access 
key,  set  this  parameter  to  0. 
accessKey 

The  key  to  be  removed. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

flags  Constant 

kAccessKeySystemFl  ag 

Set  to  1  to  remove  a  system  access  key. 

Discussion 

Most  access  keys  are  strings.  A  string  stored  in  the  accessKey  handle  does  not 
include  a  trailing  zero  or  a  leading  length  byte. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Registering  and  Unregistering  Access  Keys"  (V-2771) 
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QTUpdateGWorld 


QTUpdateG  W  orld 


Changes  the  pixel  depth,  boundary  rectangle,  or  color  table  for  an  existing  offscreen 
graphics  world  with  a  non-Macintosh  pixel  format. 


GWorldFlags  QTUpda 
GWorl dPtr 
OSType 
const  Rect 
CTabHandl e 
GDHandl e 
GWorl  d FI  ags 


teGWorld  ( 
*offscreenGWorl d , 
Pi xel Format , 
*boundsRect , 
cTabl e , 
aGDevi ce , 
f 1 ags  ) ; 


offscreenGWorl d 

On  input,  a  pointer  to  an  existing  offscreen  graphics  world;  upon  completion, 
the  pointer  to  the  updated  offscreen  graphics  world. 

Pixel  Format 

The  updated  graphics  world's  pixel  format;  see  "Pixel  Formats"  (IV-2686). 

boundsRect 

A  pointer  to  the  boundary  rectangle  and  port  rectangle  for  the  updated 
offscreen  pixel  map.  This  becomes  the  boundary  rectangle  for  the  GDevi  ce 
structure,  if  this  function  creates  one.  If  you  specify  0  in  the  Pi  xel  Format 
parameter,  the  function  interprets  the  boundaries  in  global  coordinates  that  it 
uses  to  determine  which  screens  intersect  the  rectangle.  It  then  uses  the  pixel 
format,  color  table,  and  G  D  e  v  i  c  e  structure  from  the  screen  with  the  greatest  pixel 
depth  from  among  all  screens  whose  boundary  rectangles  intersect  this 
rectangle.  If  the  rectangle  you  specify  in  this  parameter  differs  from,  but  has  the 
same  size  as,  the  previous  boundary  rectangle,  the  function  realigns  the  pixel 
image  to  the  screen  for  optimum  performance  for  CopyBi  ts.  Typically,  your 
application  supplies  this  parameter  with  the  port  rectangle  for  the  onscreen 
window  into  which  your  application  will  copy  the  pixel  image  from  this 
offscreen  world. 

cTabl e 

A  handle  to  a  Col  orTabl  e  (IV-2210)  structure  for  the  updated  graphics  world.  If 
you  pass  N I L  in  this  parameter,  the  function  uses  the  default  color  table  for  the 
pixel  format  that  you  specify  in  the  Pi  xel  Format  parameter.  If  you  set  the 
Pixel  Format  parameter  to  0,  the  function  ignores  the  cTabl  e  parameter  and 
instead  copies  and  uses  the  color  table  of  the  graphics  device  with  the  greatest 
pixel  depth  among  all  graphics  devices  whose  boundary  rectangles  intersect 
the  rectangle  that  you  specify  in  the  boundsRect  parameter.  If  the  color  table  that 
you  specify  in  this  parameter  is  different  from  the  previous  color  table,  or  if  the 
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color  table  associated  with  the  GDevi ce  structure  that  you  specify  in  the 
aGDevi ce  parameter  is  different,  the  function  maps  the  pixel  values  in  the 
offscreen  pixel  map  to  the  new  color  table.  If  you  use  this  function  on  a 
computer  that  supports  only  basic  QuickDraw,  you  may  specify  only  N I L  in  this 
parameter. 

aGDevi ce 

A  handle  to  a  GDevi  ce  (IV-2264)  structure  that  is  used  only  when  you  specify 
the  noNewDevi  ce  flag  in  the  f  1  ags  parameter,  in  which  case  the  function  attaches 
this  structure  to  the  new  offscreen  graphics  world.  If  you  set  the  Pi  xel  Format 
parameter  to  0,  or  if  you  do  not  set  the  noNewDevi  ce  flag,  the  function  ignores 
this  parameter,  so  you  should  set  it  to  N I L.  If  you  set  the  Pi  xel  Format  parameter 
to  0,  the  function  uses  the  GDevi  ce  structure  for  the  graphics  device  with  the 
greatest  pixel  depth  among  all  graphics  devices  whose  boundary  rectangles 
intersect  the  rectangle  that  you  specify  in  the  boundsRect  parameter  .You  should 
pass  N I L  in  this  parameter  if  the  computer  supports  only  basic  QuickDraw. 
Generally,  your  application  should  never  create  GDevi  ce  structures  for  offscreen 
graphics  worlds. 

fl  ags 

Constants  (see  below)  that  identify  options  available  to  your  application.  You 
can  set  a  combination  of  these  flags.  If  you  don't  wish  to  use  any  of  them,  pass 
0  in  this  parameter.  In  this  case  the  default  behavior  is  to  create  an  offscreen 
graphics  world  where  the  base  address  for  the  offscreen  pixel  image  is 
unpurgeable,  the  graphics  world  uses  an  existing  GDevi  ce  structure  (if  you  pass 
0  in  the  depth  parameter)  or  creates  a  new  GDev  i  ce  structure,  it  uses  memory  in 
your  application  heap,  and  it  allows  graphics  accelerators  to  cache  the  offscreen 
pixel  image. 

function  result  A  constant  (see  below)  that  reports  on  the  operation  of  this  function. 

flags  Constants 

pi xPurge 

Make  base  address  for  the  offscreen  pixel  image  purgeable. 
noNewDevi ce 

Do  not  create  an  offscreen  GDevi  ce  structure. 
useTempMem 

Create  a  base  address  for  the  offscreen  pixel  image  in  temporary  memory. 
keepLocal 

Keep  the  offscreen  pixel  image  in  main  memory  where  it  cannot  be  cached  to  a 
graphics  accelerator  card. 
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Function  Result  Constants 

gwFl  agErr 

Function  unsuccessful;  the  offscreen  graphics  world  has  been  left  unchanged. 
mapPi x 

Colors  were  remapped  to  a  new  color  table. 
newDepth 

The  pixel  values  in  the  offscreen  pixel  image  were  translated  to  those  for  a 
different  pixel  depth, 
al 1 gnPi x 

The  offscreen  image  was  realigned  to  the  window. 
newRowBytes 

The  value  of  the  row  By  tes  field  in  the  Pi  xMap  structure  for  the  offscreen  graphics 
world  was  changed, 
real  1 ocPi x 

Memory  for  the  offscreen  pixel  image  had  to  be  reallocated;  your  application 
should  then  reconstruct  the  pixel  image,  or  draw  directly  in  a  window  instead 
of  preparing  the  image  in  an  offscreen  graphics  world, 
cl i pPi x 

The  pixel  image  was  clipped.  If  the  rectangle  you  specified  in  the  bounds  Rect 
parameter  is  smaller  than  the  previous  boundary  rectangle  the  pixel  image  was 
clipped  along  the  bottom  and  right  edges.  If  the  rectangle  you  specified  was 
bigger  than  the  previous  boundary  rectangle,  the  bottom  and  right  edges  of  the 
pixel  image  are  undefined. 

stretchPi x 

The  offscreen  image  was  stretched  or  shrunk.  If  the  rectangle  you  specified  in 
the  bounds  Rect  parameter  was  smaller  than  the  previous  boundary  rectangle, 
the  pixel  image  is  reduced  to  the  new  size.  If  the  rectangle  was  bigger  than  the 
previous  boundary  rectangle,  the  pixel  image  was  stretched  to  the  new  size, 
d  i  t  h  e  r  P  i  x 

The  offscreen  pixel  image  was  dithered. 

Discussion 

If  the  Memory  Manager  purged  the  base  address  for  the  offscreen  pixel  image,  this 
function  reallocates  the  memory  but  the  pixel  image  is  lost.  You  must  reconstruct  it. 

Special  Considerations 

This  function  may  move  or  purge  memory  blocks  in  the  application  heap.  Your 
application  should  not  call  this  function  at  interrupt  time. 


11-1320 


Inside  QuickTime:  Function  l-Q 


QTVideoOutputBegin 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


QTVideoOutputBegin 

Obtains  exclusive  access  to  the  video  hardware  controlled  by  a  video  output 
component. 

ComponentResul t  QTVideoOutputBegin  ( 

QTVideoOutputComponent  vo  ); 


vo 

The  instance  of  a  video  output  component.  Your  software  obtains  this  reference 
when  calling  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error.  If  this 
function  returns  the  vi  deoOutputlnllseErr  result  code  that  indicates 
that  the  video  hardware  is  currently  in  use,  your  software  can  get  the 
name  of  the  application  or  other  software  that  is  using  the  hardware 
by  calling  QTVi  deoOutputGetCurrentCl  i  entName  (11-1325).  You  can 
then  display  an  alert  to  the  user  that  says  that  the  video  hardware  is 
in  use  and  specifies  the  name  of  the  software  using  the  video 
hardware. 

Discussion 

When  your  software  calls  this  function,  the  video  output  component  acquires 
exclusive  access  to  the  video  hardware  controlled  by  the  specified  video  output 
component  or  returns  the  vi  deoOutputlnllseErr  result  code  if  the  video  hardware  is 
currently  in  use.  If  the  video  hardware  is  available,  the  video  output  component 
also  enables  the  display  mode  last  set  with  QTVi  deoOutputSetDi  spl  ayMode  (11-1332) 
and  enables  the  video  settings,  if  any,  that  were  most  recently  specified  by  the  user 
in  a  custom  video  configuration  dialog  box.  If  the  video  output  component  supports 
QTVi  deoOutputCustomConf  i  gureDi  spl  ay  (11-1322),  your  software  can  call  the  function 
to  display  a  custom  video  configuration  dialog  box.  When  your  software  no  longer 
needs  the  video  output  component,  release  it  by  calling  QTVi  deoOutputEnd  (11-1322). 

Special  Considerations 

If  your  software  needs  to  change  the  display  mode,  it  must  change  it  before  calling 
this  function.  It  cannot  change  the  display  mode  between  calls  to  this  function  and 
to  QTVi  deoOutputEnd  (11-1322). 
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QTVideoOutputCustomConfigureDisplay 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Video  Output"  (V-2893) 


QTVideoOutputCustomConfigureDisplay 


Displays  a  custom  video  configuration  dialog  box,  which  can  include  settings  that 
are  specific  to  the  video  device  controlled  by  the  video  output  component. 

ComponentResul t  QTVi deoOutputCustomConf i gureDi spl ay  ( 

QTVi deoOutputComponent  vo, 

Modal  Fi  1  terLIPP  filter  ); 


vo 

The  instance  of  a  video  output  component  for  this  request.  Your  software 
obtains  this  reference  when  calling  OpenComponent  (11-1130)  or 
OpenDef aul tComponent  (11-1131). 

filter 

AModalFilterProc  (III— 2098)  callback  for  the  video  output  component  to  use  for 
the  dialog  box.  The  filter  allows  the  software  to  process  events  while  the  dialog 
box  is  displayed. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  software  can  determine  if  a  video  output  component  supports  this  function  by 
calling  ComponentFuncti  onlmpl  emented  (I— 1 11)  for  the  component  with  the  routine 
selector  kQTVi deoOutputCustomConf i gureDi spl aySel ect. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Controlling  Video  Output"  (V-2893) 


QTVideoOutputEnd 

Releases  access  to  the  video  hardware  controlled  by  a  video  output  component. 
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QTVideoOutputGetClientName 


ComponentResul t  QTVideoOutputEnd  ( 
QTVi deoOutputComponent  vo  ); 


vo 

The  instance  of  a  video  output  component.  Your  software  obtains  this  reference 
when  calling  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  software  should  release  access  to  a  video  output  component  as  soon  as  it  is 
done  using  the  video  hardware  controlled  by  the  component.  If  you  close  the 
instance  of  a  video  output  component  that  currently  has  exclusive  access  to  video 
hardware,  the  video  output  component  automatically  calls  this  function  to  release 
the  hardware. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui ckTi  meComponents  .  h 

Programming  summary:  "Controlling  Video  Output"  (V-2893) 


QTVideoOutputGetClientName 


Obtains  the  name  of  the  application  or  other  software  that  is  registered  with  an 
instance  of  a  video  output  component. 

ComponentResul t  QTVideoOutputGetClientName  ( 

QTVi  deoOutputComponent  vo, 

Str255  str  ); 


vo 

The  instance  of  a  video  output  component  for  the  request.  Your  software 
obtains  this  reference  when  it  calls  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 

str 

The  name  of  the  application  or  other  software  that  is  registered  with  the 
component  instance. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Function  l-Q 


11-1323 


QTVideoOutputGetClock 


Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Registering  the  Name  of  Video  Output  Software" 
(V-2892) 

See  Also 

For  the  corresponding  set  function,  see  QTVi  deoOutputSetCl  i  entName  (11-1332). 


QTVideoOutputGetClock 


Returns  a  pointer  to  the  clock  component  associated  with  the  video  output 
component. 

ComponentResul t  QTVideoOutputGetClock  ( 

QTVi deoOutputComponent  vo, 

Componentlnstance  *clock  ); 


vo 

The  instance  of  a  video  output  component  for  this  request.  Your  software 
obtains  this  reference  when  calling  OpenComponent  (11-1130)  or 
OpenDef  aul  tComponent  (11-1131). 

cl  ock 

A  pointer  to  the  clock  component  associated  with  the  video  output  component. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  software  can  use  the  clock  component  returned  by  this  function  to 
synchronize  video  and  sound  for  a  movie  to  the  rate  of  the  display.  To  associate  the 
instance  of  the  clock  component  with  a  movie,  call  SetMovi  eMasterCl  ock  (III— 1620). 
Because  a  change  to  the  display  mode  could  affect  a  clock  component,  your 
software  should  call  this  function  only  between  calls  toQTVideoOutputBegin 
(11-1321)  and  QTVi  deoOutputEnd  (11-1322),  when  it  is  not  possible  to  change  the 
display  mode. 

Special  Considerations 

When  your  software  calls  QTVi  deoOutputEnd  (11-1322),  the  video  output  component 
disposes  of  the  instance  of  the  clock  component  returned  by  this  function.  Because 
of  this,  software  that  uses  the  clock  to  control  a  movie  must  reset  the  clock  for  the 
movie  to  the  default  clock,  by  calling  SetMovi  eMasterCl  ock  (III— 1620)  with  NI L  as  the 
value  of  the  clock  component,  before  calling  QTVi  deoOutputEnd. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Finding  Components  Associated  With  a  Video  Output" 
(V-2894) 

QTVideoOutputGetCurrentClientName 

Returns  the  name  of  the  software,  if  any,  that  has  exclusive  access  to  the  video 
hardware  controlled  by  a  video  output  component. 

ComponentResul t  QTVideoOutputGetCurrentCl ientName  ( 

QTVideoOutputComponent  vo, 

Str255  str  ); 


vo 

The  instance  of  a  video  output  component  for  this  request.  Your  software 
obtains  this  reference  when  calling  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 

str 

The  name  of  the  software  that  has  exclusive  access  to  the  video  hardware 
controlled  by  a  video  output  component,  or  a  zero-length  string  if  no  software 
currently  has  access. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

If  video  hardware  is  unavailable  because  other  software  is  using  it,  your  software 
can  inform  users  by  getting  the  name  of  the  software  with  this  function  and 
displaying  the  name  in  an  alert  box. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Registering  the  Name  of  Video  Output  Software" 
(V-2892) 

QTVideoOutputGetDisplayMode 


Returns  the  current  display  mode  for  a  video  output  component. 


Inside  QuickTime:  Function  l-Q 


11-1325 


QTVideoOutputGetDisplayModeList 


ComponentResul t  QTVi deoOutputGetDi spl ayMode  ( 
QTVi deoOutputComponent  vo, 

long  *displ ayModelD  ); 


vo 

The  instance  of  a  video  output  component.  Your  software  obtains  this  reference 
when  calling  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 
di spl ayModelD 

A  pointer  to  the  ID  of  the  current  display  mode,  or  0  if  no  display  mode  has 
been  selected.  The  ID  specifies  a  QT  atom  of  type  kQTVODi  spl  ayModeltem  in  the 
QT  atom  container  returned  by  QTVi  deoOutputGetDi  spl  ayModeLi  st  (11-1326). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error.  If  this 
function  returns  an  atom  ID  of  0,  it  indicates  that  no  display  mode 
has  been  selected. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  the  Video  Output  Display  Mode"  (V-2892) 

See  Also 

For  the  corresponding  set  function,  see  QTVi  deoOutputSetDi  spl  ayMode  (11-1332). 


QTVideoOutputGetDisplayModeList 


Returns  a  list  of  the  display  modes  supported  by  a  video  output  component. 

ComponentResul t  QTVi deoOutputGetDi spl ayModeLi st  ( 

QTVi deoOutputComponent  vo, 

QTAtomContai ner  *outputs  ); 


vo 

The  instance  of  a  video  output  component.  Your  software  obtains  this  reference 
when  calling  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

outputs 

A  pointer  to  the  QT  atom  container  that  lists  the  video  modes  supported  by  this 
component. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


11-1326 


Inside  QuickTime:  Function  l-Q 


QTVideoOutputGetGWorld 


Discussion 

After  your  software  calls  this  function,  it  must  dispose  of  the  QT  atom  container 
returned  by  the  function  by  calling  QTDi  sposeAtomContai  ner  (11-1164). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Controlling  the  Video  Output  Display  Mode"  (V-2892) 


QTVideoOutputGetGWorld 


Returns  a  pointer  to  the  graphics  world  used  by  a  video  output  component. 

ComponentResul t  QTVideoOutputGetGWorld  ( 

QTVi  deoOutputComponent  vo, 

GWorldPtr  *gw  ); 


vo 

The  instance  of  a  video  output  component  for  this  request.  Your  software 
obtains  this  reference  when  calling  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 

gw 

A  pointer  to  the  graphics  world  used  by  the  video  output  component  to  display 
images. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

If  the  pixel  format  of  the  graphics  world  is  1, 2, 4, 8, 16,  or  32,  your  software  can  use 
either  QuickDraw  or  QuickTime  to  draw  graphics  to  it.  If  the  graphics  world  has 
any  other  pixel  format,  your  software  must  use  QuickTime  functions  draw  to  it. 
Your  software  can  pass  the  pointer  returned  by  this  function  to  the  SetMovi  eGWorl  d 
(III — 1619),  DecompressSequenceBegi  n  (1-238),  DecompressSequenceBegi  nS  (1-239), 
Decompress  Image  (1-235),  and  FDecompressImage  (1-355)  functions. 

Your  software  can  call  QTVi  deoOutputGetGWorl  d  only  between  calls  to 
QTVideoOutputBegin  (11-1321)  and  QTVi  deoOutputEnd  (11-1322).  When  your  software 
calls  QTVi  deoOutputEnd,  the  video  output  component  automatically  disposes  of  the 
graphics  world.  If  your  software  needs  to  use  the  graphics  world  after  calling 
QTVi  deoOutputEnd,  it  must  call  this  function  again  after  the  next  time  it  calls 
QTVi deoOutputBegi n. 


Inside  QuickTime:  Function  l-Q 


11-1327 


QTVideoOutputGetGWorldParameters 


Special  Considerations 

Your  software  must  not  dispose  of  the  graphics  world  used  by  a  video  output 
component.  The  video  output  component  automatically  disposes  of  the  graphics 
world  when  your  software  calls  QTVIdeoOutputEnd  (11-1322). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Video  Output"  (V-2893) 


QTVideoOutputGetGWorldParameters 


Called  by  the  base  video  output  component  as  part  of  its  implementation  of 
QTVi  deoOutputGetGWorl  d  (11-1327). 

ComponentResul t  QTVi deoOutputGetGWorl dParameters  ( 

QTVi deoOutputComponent  vo, 

Ptr  *baseAddr, 

long  *rowBytes, 

CTabHandle  *colorTable  ); 


vo 

An  instance  of  your  video  output  component. 
baseAddr 

The  address  at  which  to  display  pixels.  If  your  video  output  component  does 
not  display  pixels,  return  0  for  this  parameter. 

rowBytes 

The  width  of  each  scan  line  in  bytes.  If  your  video  output  component  does  not 
display  pixels,  return  the  width  of  the  current  display  mode, 
col orTabl e 

The  Col  orTabl  e  (IV-2210)  structure  to  be  used.  If  your  video  output  component 
does  not  use  a  color  table,  return  NIL. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  not  called  by  applications  or  other  client  software. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


11-1328 


Inside  QuickTime:  Function  l-Q 


QTVideoOutputGetlndlmageDecompressor 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Controlling  Video  Output"  (V-2893) 


QTVideoOutputGetlndlmageDecompressor 


Undocumented 

ComponentResul t  QTVideoOutputGetlndlmageDecompressor  ( 
QTVi deoOutputComponent  vo, 

long  index. 

Component  *codec  ); 


vo 

Undocumented 
i  ndex 

Undocumented 

codec 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 


QTVideoOutputGetlndSoundOutput 


Determines  which  sound  output  components  are  associated  with  the  video  output 
component. 

ComponentResul t  QTVideoOutputGetlndSoundOutput  ( 

QTVi deoOutputComponent  vo, 

long  index. 

Component  *outputComponent  ); 


The  instance  of  a  video  output  component  for  this  request.  Your  software 
obtains  this  reference  when  calling  OpenComponent  (11-1130)  or 
OpenDef  aul  tComponent  (11-1131). 


Inside  QuickTime:  Function  l-Q 


11-1329 


QTVideoOutputRestoreState 


i  ndex 

Specifies  which  of  the  sound  output  components  to  return.  The  index  of  the  first 
component  is  1. 
outputComponent 

A  pointer  to  a  sound  output  component  associated  with  the  video  output 
component  that  is  specified  by  the  index  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  software  can  display  sound  output  components  returned  by  this  function  in  a 
dialog  box  and  let  the  user  choose  which  outputs  to  use  for  movie  playback. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Finding  Components  Associated  With  a  Video  Output" 
(V-2894) 

QTVideoOutputRestoreState 


Restores  the  previously  saved  state  of  a  video  output  component. 

ComponentResul t  QTVideoOutputRestoreState  ( 

QTVi deoOutputComponent  vo, 

QTAtomContai ner  state  ); 


vo 

The  instance  of  a  video  output  component  for  this  request.  Your  software 
obtains  this  reference  when  calling  OpenComponent  (11-1130)  or 
OpenDef  aul  tComponent  (11-1131). 

state 

A  QT  atom  container,  returned  earlier  by  QTVi  deoOutputSaveState  (11-1331), 
that  contains  state  information  for  the  video  output  component. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

If  your  software  saves  state  information  to  disk,  it  must  read  the  QT  atom  container 
structure  from  disk  before  calling  this  function.  When  your  software  restores  state 
information  for  a  video  output  component,  the  current  display  mode  may  change. 


11-1330 


Inside  QuickTime:  Function  l-Q 


QTVideoOutputSaveState 


Because  of  this,  your  software  must  call  this  function  before  calling 
QTVideoOutputBegi  n  (11-1321). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Saving  and  Restoring  Component  Configurations" 
(V-2894) 

QTVideoOutputSaveState 


Saves  state  information  for  an  instance  of  a  video  output  component. 

ComponentResul t  QTVideoOutputSaveState  ( 

QTVi  deoOutputComponent  vo, 

QTAtomContai ner  *state  ); 


vo 

The  instance  of  a  video  output  component  for  this  request.  Your  software 
obtains  this  reference  when  calling  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 

state 

A  pointer  to  complete  information  about  the  video  output  component's  current 
configuration. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

When  your  software  saves  state  information  for  an  instance  of  a  video  output 
component,  it  can  restore  this  information  when  reconnecting  to  the  component  by 
calling  QTVi  deoOutputRestoreState  (11-1330). 

Special  Considerations 

When  your  software  calls  this  function,  it  must  dispose  of  the  QT  atom  container 
returned  by  the  function  by  calling  QTDi  sposeAtomContai  ner  (11-1164). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Saving  and  Restoring  Component  Configurations" 
(V-2894) 


Inside  QuickTime:  Function  l-Q 


11-1331 


QTVideoOutputSetClientName 


QTVideoOutputSetClientName 


Registers  the  name  of  an  application  or  other  software  with  an  instance  of  a  video 
output  component. 

ComponentResul t  QTVideoOutputSetClientName  ( 

QTVi deoOutputComponent  vo, 

ConstStr255Param  str  ); 


vo 

The  instance  of  a  video  output  component  for  the  request.  Your  software 
obtains  this  reference  when  it  calls  OpenComponent  (11-1130)  or 
OpenDef  aul  tComponent  (11-1131). 

str 

The  name  of  the  application  or  other  software  to  be  registered. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  name  you  specify  with  this  function  can  later  be  used  by 

QTVi  deoOutputGetCurrentCl  i  entName  (11-1325)  to  specify  which  software  has 

exclusive  access  to  the  video  output  device  controlled  by  the  component. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Registering  the  Name  of  Video  Output  Software" 
(V-2892) 

See  Also 

For  the  corresponding  get  function,  see  QTVi  deoOutputGetCl  i  entName  (11-1323). 


QTVideoOutputSetDisplayMode 


Specifies  the  display  mode  to  be  used  by  a  video  output  component. 

ComponentResul t  QTVideoOutputSetDisplayMode  ( 

QTVi deoOutputComponent  vo, 

1 ong  di spl ayModelD  ) ; 


11-1332 


Inside  QuickTime:  Function  l-Q 


QTVideoOutputSetEchoPort 


VO 

The  instance  of  a  video  output  component  for  the  request.  Your  software 
obtains  this  reference  when  calling  OpenComponent  (11-1130)  or 
OpenDefaul tComponent  (11-1131). 
di spl ayModelD 

The  ID  of  the  display  mode  to  use.  The  ID  specifies  a  QT  atom  of  type 
kQTVODi  spl  ayModeltem  in  the  QT  atom  container  returned  by 
QTVi  deoOutputGetDi  spl  ayModeLi  st  (11-1326). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

When  software  changes  the  display  mode  with  this  function,  the  change  does  not 
take  effect  until  the  next  time  the  software  calls  QTVi  deoOutputBegi  n  (11-1321)  for  the 
video  output  component.  This  lets  the  software  change  other  output  settings  before 
displaying  the  video. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Controlling  the  Video  Output  Display  Mode"  (V-2892) 

See  Also 

For  the  corresponding  get  function,  see  QTVi  deoOutputGetDi  spl  ayMode  (11-1325). 


QTVideoOutputSetEchoPort 


Specifies  a  window  on  the  desktop  in  which  to  display  video  sent  to  the  device. 

ComponentResul t  QTVideoOutputSetEchoPort  ( 

QTVi deoOutputComponent  vo, 

CGrafPtr  echoPort  ); 


vo 

The  instance  of  a  video  output  component  for  this  request.  Your  software 
obtains  this  reference  when  calling  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 
echoPort 

The  window  on  the  computer's  desktop  in  which  to  display  the  video. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Inside  QuickTime:  Function  l-Q 


11-1333 


QTVRAnglesToCoord 


Discussion 

When  your  software  sends  video  to  the  window  you  specify,  the  video  is  both 
displayed  in  the  window  and  sent  to  the  normal  output  of  the  video  output  device. 
When  an  output  device  can  display  video  both  on  an  external  video  display  and  in 
a  window  on  a  computer's  desktop,  the  video  displayed  on  the  desktop  is  often  at 
a  smaller  size  and/or  lower  frame  rate. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Video  Output"  (V-2893) 


QTVRAnglesToCoord 


Obtains  a  floating-point  coordinate  determined  by  a  pair  of  pan  and  tilt  angles. 


OSErr  QTVRAnglesToCoord  ( 
QTVRInstance  qtvr, 

float  panAngle, 

float  tiltAngle, 

QTVRF1 oatPoi nt  *coord  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

panAngl e 

A  pan  angle, 
ti 1 tAngl e 

A  tilt  angle, 
coord 

On  entry,  a  pointer  to  a  QTVRF1  oatPoi  nt  (IV-2396)  structure.  On  return,  that 
structure  is  set  to  the  coordinate  of  the  specified  movie  that  corresponds  to  the 
specified  pan  and  tilt  angles. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

QTVRAngl  esToCoord  is  valid  only  for  panoramic  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


11-1334 


Inside  QuickTime:  Function  l-Q 


QTVRBeginUpdateStream 


Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Converting  Angles  and  Points"  (V-2911) 

See  Also 

Use  QTVRCoordToAngl  es  (11-1338)  to  get  a  pair  of  pan  and  tilt  angles  from  a 
floating-point  coordinate. 


QTVRBeginUpdateStream 


Begins  a  stream  of  immediate  updates  to  a  QuickTime  VR  movie. 

OSErr  QTVRBeginUpdateStream  ( 

QTVRInstance  qtvr, 

QTVRImagi ngMode  imagingMode  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

i magi ngMode 

An  imaging  mode  (see  below). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

ImagingMode  Constants 

kQTVRStati c 

The  panorama  is  static 
kQTVRMoti on 

The  panorama  is  in  motion;  that  is,  an  action  such  as  panning  or  zooming  is 
occurring. 

kQTVRAll Modes 

All  currently  defined  imaging  modes.  You  can  specify  this  imaging  mode  when 
calling  QTVRSetlmagi  ngProperty  (11-1422)  to  assign  a  value  to  a  particular 
imaging  property  for  all  imaging  modes.  You  can  also  use  this  imaging  mode 
in  the  imagingMode  field  of  a  QTVRPanoImagi  ngAtom  (IV-2398)  structure  to  indicate 
a  default  value  for  a  particular  imaging  property  for  all  imaging  modes. 

Discussion 

This  function  configures  the  QuickTime  VR  movie  specified  by  the  qtvr  parameter 
for  a  stream  of  immediate  updates  to  its  movie  image.  After  calling 
QTVRBegi  nUpdateStream,  you  perform  the  updates  by  calling  QTVRUpdate  (11-1445). 
When  you  are  finished  performing  the  updates,  call  QTVREndUpdateStream  (11-1343). 


Inside  QuickTime:  Function  l-Q 


11-1335 


QTVRCalllnterceptedProc 


Issuing  a  stream  of  image  updates  in  this  manner  is  significantly  faster  than  simply 
calling  QTVRUpdate  repeatedly  (that  is,  not  within  a  begin/end  update  sequence). 
Each  call  to  this  function  must  be  balanced  by  a  call  to  Q  T  V  R  E  n  d  U  p  d  a  t  e  S  t  r  e  a  m,  but  you 
can  nest  these  calls. 

Special  Considerations 

After  you  call  this  function  and  before  you  call  QTVREndUpdateStream  (11-1343),  you 
must  not  change  any  of  the  QuickTime  VR  movie's  imaging  properties. 

Calling  this  function  locks  down  large  blocks  of  memory.  As  a  result,  you  should 
minimize  the  amount  of  time  before  calling  QTVREndUpdateStream. 

This  function  is  valid  only  for  panoramic  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Imaging  Characteristics"  (V-2910) 

See  Also 

Use  QTVREndUpdateStream  (11-1343)  to  end  a  stream  of  immediate  updates  to  a 
QuickTime  VR  movie. 


QTVRCalllnterceptedProc 


Calls  an  intercepted  QuickTime  VR  function  from  within  an  intercept  procedure. 

OSErr  QTVRCalllnterceptedProc  ( 

QTVRInstance  qtvr, 

QTVRInterceptRecord  *qtvrMsg  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
qtvrMsg 

A  pointer  to  a  QTVRInterceptRecord  (IV-2396)  structure  that  specifies  the 
function  that  your  procedure  is  intercepting  and  the  parameters  for  that 
function.  This  should  be  the  same  intercept  record  passed  to  your  intercept 
procedure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


11-1336 


Inside  QuickTime:  Function  l-Q 


QTVRColumnToPan 


Discussion 

This  function  executes  the  QuickTime  VR  Manager  function  indicated  by  the 
sel  ector  field  of  the  qtvrMsg  intercept  record.  The  parameters  passed  to  that 
function  are  the  QuickTime  VR  movie  specified  by  the  qtvr  parameter  and  any 
other  parameters  contained  in  the  parameter  field  of  the  qtvrMsg  record.  You  can,  if 
you  wish,  change  the  parameters  in  that  field  before  calling  this  function. 

You  can  call  this  function  more  than  once  in  your  intercept  procedure.  In  addition, 
the  QuickTime  VR  Manager  will  call  the  intercepted  function  again  unless  your 
intercept  procedure  returns  TRUE  in  the  cancel  parameter. 

Special  Considerations 

You  should  call  QTVRCal  1  InterceptedProc  only  in  an  intercept  procedure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Intercepting  QuickTime  VR  Manager  Routines"  (V-2908) 

Related  Java  Methods 

qui cktime . vr . QTVRInstance .call Intercepted ProcC ) 


QT  VRColumnT  oPan 


Get  the  pan  angle  that  corresponds  to  a  column  number  in  the  object  image  array. 

float  QTVRColumnToPan  ( 

QTVRInstance  qtvr, 

short  column  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

col umn 

A  column  number. 

function  result  The  pan  angle  that  corresponds  to  the  zero-based  column  number  in 
the  object  image  array  specified  by  the  col  umn  parameter. 

Special  Considerations 

This  function  is  valid  only  for  object  nodes. 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Converting  Angles  and  Points"  (V-2911) 

Related  Java  Methods 

qui ckti me . vr . QTVRInstance .col umnToPan ( ) 


QT  VRCoordT  o  Angles 


Get  the  pan  and  tilt  angles  of  a  floating-point  coordinate  in  a  panorama. 

OSErr  QTVRCoordToAngles  ( 

QTVRInstance  qtvr, 

QTVRF1 oatPoi nt  *coord, 

float  *panAngle, 

f 1  oat  *ti 1 tAngl e  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

coord 

On  entry,  a  pointer  to  a  QTVRF1  oatPoi  nt  (IV-2396)  structure  that  specifies  a 
coordinate  in  the  full  panorama. 

panAngl e 

On  entry,  a  pointer  to  a  floating-point  value.  On  return,  that  value  contains  the 
pan  angle  of  the  specified  coordinate, 
ti 1 tAngl e 

On  entry,  a  pointer  to  a  floating-point  value.  On  return,  that  value  contains  the 
tilt  angle  of  the  specified  coordinate. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns,  in  the  floating-point  values  pointed  to  by  the  panAngl  e  and 
ti  1  tAngl  e  parameters,  the  pan  and  tilt  angles  of  the  point  specified  by  the  coord 
parameter.  This  function  is  useful  for  setting  up  angles  in  a  back  buffer  imaging 
procedure;  if  you  know  a  coordinate  in  the  back  buffer,  you  can  call 
QTVRCoordToAngl  es  to  get  the  corresponding  angles. 
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Special  Considerations 

QTVRCoordToAngl  es  is  valid  only  for  panoramic  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Converting  Angles  and  Points"  (V-2911) 

See  Also 

Use  QTVRAngl  esToCoord  (11-1334)  to  get  a  floating-point  coordinate  from  a  pair  of  pan 
and  tilt  angles. 


QT  VREnableF  rame  Animation 


Enables  or  disables  frame  animation  for  an  object  node. 

OSErr  QTVREnabl eFrameAnimati on  ( 

QTVRInstance  qtvr. 

Boolean  enable  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
enabl e 

A  Bool  ean  value  that  indicates  whether  to  enable  (TRUE)  or  disable  (FALSE)  frame 
animation  for  the  specified  object  node. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  enables  or  disables  the  frame  animation  state  for  the  object  node 
specified  by  the  qtvr  parameter,  according  to  the  value  of  the  enable  parameter.  The 
current  frame  rate,  set  by  the  function  QTVRSetFrameRate  (11-1421),  is  unaffected  by 
the  state  of  frame  animation  of  an  object  node. 

Special  Considerations 

This  function  is  valid  only  for  object  nodes.  You  should  use  this  function  instead  of 
standard  QuickTime  functions  to  control  object  animation. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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QTVREnableHotSpot 


Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Object  Nodes"  (V-2909) 

See  Also 

Use  QTVRGetFrameAni mati  on  (11-1361)  to  get  the  current  state  of  frame  animation  for 
an  object  node. 


QTVREnableHotSpot 


Enables  or  disables  one  or  more  QTVR  hot  spots. 

OSErr  QTVREnableHotSpot  ( 

QTVRInstance  qtvr, 

UInt32  enableFlag, 

UInt32  hotSpotVal ue , 

Bool ean  enabl e  ) ; 

qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
enabl  eFl  ag 

The  kind  of  hot  spot  or  hot  spots  to  enable  or  disable  (see  below). 
hotSpotVal ue 

The  desired  hot  spot  or  spots,  defined  by  the  specified  enabled  flag  (see  below), 
enabl e 

A  Bool  ean  value  that  indicates  whether  the  specified  hot  spots  are  to  be  enabled 
(TRUE)  or  disabled  (FALSE). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

enableFlag  Constants 

kQTVRHotSpotID 

The  hotSpotVal  ue  parameter  specifies  a  hot  spot  ID. 
kQTVRHotSpotType 

The  hotSpotVal  ue  parameter  specifies  a  hot  spot  type. 
kQTVRAll HotSpots 

Set  the  hotSpotVal  ue  parameter  to  0. 

Discussion 

This  function  either  enables  or  disables  the  hot  spot  or  spots  specified  by  the 
enabl  eFl  ag  and  hotSpotVal  ue  parameters,  according  to  the  value  of  the  enabl  e 
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parameter.  The  hot  spots  are  always  selected  from  among  the  hot  spots  in  the 
current  node  of  the  QuickTime  VR  movie  specified  by  the  qtvr  parameter. 

Normally,  all  hot  spots  in  a  node  are  enabled  (that  is,  the  cursor  automatically 
changes  shape  when  it  is  moved  over  a  hot  spot,  and  the  QTVRTriggerHotSpot 
(11-1443)  function  is  called  internally  when  the  user  clicks  a  hot  spot).  When  a  hot 
spot  is  disabled,  QuickTime  VR  behaves  as  if  the  hot  spot  were  not  present. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Hot  Spots"  (V-2906) 

Related  Java  Methods 

qui cktime . vr . QTVRInstance .enableHotSpotl) 


QT  VREnableT  ransition 


Enables  or  disables  a  transition  effect. 

OSErr  QTVREnableTransition  ( 
QTVRInstance  qtvr, 

UInt32  transitionType, 

Boolean  enable  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
transi ti onType 

A  type  of  transition  property  (see  below).  Currently  only  one  constant  is 
available  for  this  parameter. 

enabl e 

A  B  o  o  1  e  a  n  value  that  indicates  whether  the  specified  transition  property  is  to  be 
enabled  (TRUE)  or  disabled  (FALSE). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

transitionType  Constant 

kQTVRT  ransi ti onSwi ng 

A  transition  between  two  views  in  a  single  node. 
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QTVREnableViewAnimation 


Discussion 

This  function  enables  or  disables  the  transition  property  specified  by  the 
transitionType  parameter  for  the  movie  specified  by  the  qtvr  parameter,  as 
indicated  by  the  value  of  the  enable  parameter.  Once  a  transition  effect  is  enabled, 
it  is  used  at  the  appropriate  time  until  it  is  disabled  by  a  subsequent  call  to  this 
function. 

Special  Considerations 

QTVREnabl  eT ransi  ti  on  is  valid  only  for  panoramic  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Imaging  Characteristics"  (V-2910) 

See  Also 

Use  QTVRSetT ransi  ti  onProperty  (11-1435)  to  set  the  value  of  a  transition  property. 


QT  VREnable  V  iew  Animation 


Enables  or  disables  view  animation  for  an  object  node. 

OSErr  QTVREnableViewAnimation  ( 

QTVRInstance  qtvr, 

Bool ean  enabl e  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

enabl e 

A  Bool  ean  value  that  indicates  whether  to  enable  (TRUE)  or  disable  (FALSE)  view 
animation  for  the  specified  object  node. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  should  use  this  function  instead  of  standard  QuickTime  functions  to  control 
object  animation. 

Special  Considerations 

This  function  is  valid  only  for  object  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Object  Nodes"  (V-2909) 

See  Also 

Use  QTVRGetVi ewAnimati  on  (11-1377)  to  get  the  current  state  of  view  animation  for  an 
object  node. 


QTVREndUpdateStream 


Ends  a  stream  of  immediate  updates  to  a  QuickTime  VR  movie. 

OSErr  QTVREndUpdateStream  ( 

QTVRInstance  qtvr  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  unlocks  the  memory  locked  by  the  matching  call  to 
QTVRBegi  nUpdateStream  (11-1335)  for  the  QuickTime  VR  movie  specified  by  the  qtvr 
parameter  and  reverses  any  other  actions  performed  by  that  call.  Each  call  to 
QTVRBegi  nUpdateStream  must  be  balanced  by  a  call  to  this  function,  but  you  can  nest 
these  calls.  For  nested  calls,  only  the  final  call  to  this  function  unlocks  the  memory 
locked  by  the  first  call  to  QTVRBegi  nUpdateStream. 

Special  Considerations 

QTVREndUpdateStream  is  valid  only  for  panoramic  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Imaging  Characteristics"  (V-2910) 

See  Also 

Use  QTVRBegi  nUpdateStream  (11-1335)  to  begin  a  stream  of  immediate  updates  to  a 
QuickTime  VR  movie. 


Inside  QuickTime:  Function  l-Q 


11-1343 
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QTVRGetAngularUnits 


Obtains  the  type  of  unit  currently  used  when  specifying  angles. 

QTVRAngul arUni ts  QTVRGetAngularUnits  ( 

QTVRInstance  qtvr  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

function  result  The  type  of  unit  currently  used  (see  below). 

Function  Result  Constants 

kQTVRDegrees 

Angles  are  specified  using  degrees.  This  is  the  default  type  of  angle 
specification. 

kQTVRRadi ans 

Angles  are  specified  using  radians 

Discussion 

This  function  returns,  as  its  function  result,  a  constant  that  indicates  the  type  of 
angular  unit  currently  used  by  the  movie  instance  specified  by  the  qtvr  parameter. 
Angular  values  you  pass  to  other  QuickTime  VR  functions,  such  as  QTVRSetPanAngl  e 
(11-1431),  are  interpreted  in  those  units. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Converting  Angles  and  Points"  (V-2911) 

Related  Java  Methods 

qui ckti me . vr . QTVRInstance . getAngul arUni ts ( ) 


See  Also 

Use  QTVRSetAngul  arUni  ts  (11-1408)  to  set  the  type  of  angular  unit  used  by  a 
QuickTime  VR  movie. 


QTVRGetAnimationSetting 

Obtains  the  current  state  of  an  animation  setting  for  an  object  node. 
OSErr  QTVRGetAnimationSetting  ( 
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QTVRInstance  qtvr, 

QTVRObjectAnl mati on Sett i ng  setti ng  , 

Boolean  *enable  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
setti ng 

An  animation  setting  (see  below), 
enabl e 

On  entry,  a  pointer  to  a  Boolean  value.  On  return,  that  value  is  set  to  TRUE  if  the 
specified  animation  setting  is  currently  enabled  for  the  specified  object  node  or 
to  FALSE  otherwise. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

setting  Constants 

kQTVRPal i ndromeVi ewFrames 

Play  a  back-and-forth  animation  of  the  frames  of  the  current  view.  The  frames 
of  the  current  view  play  with  a  positive  or  negative  frame  rate;  the  frame  rate 
sign  is  switched  each  time  the  view  end  time  (equal  to  the  view  duration)  or  the 
view  start  time  (always  0)  is  reached. 
kQTVRStartFi rstVi ewFrames 

Play  the  frame  animation  starting  with  the  first  frame  in  the  view  (that  is,  at  the 
view  start  time).  This  setting  is  useful  if  a  sound  track  is  associated  by  time  with 
object  views.  Even  if  the  object  view  contains  no  animation,  setting  this  flag 
allows  any  sound  authored  to  play  with  the  view  to  play  from  the  beginning. 
When  this  flag  is  clear,  each  new  object  view  begins  playing  using  the  current 
view  time  of  the  previous  view. 

kQTVRDontLoopVi ewFrames 

Don't  loop  the  frame  animation.  Animation  frames  and  sound  stop  playing 
when  the  view  duration  is  reached. 
kQTVRPl ayEveryVi ewFrame 

Play  every  view  frame.  Animation  plays  all  frames  regardless  of  play  rate.  The 
play  rate  is  used  to  adjust  the  duration  in  which  a  frame  appears  but  no  frames 
are  skipped  so  the  rate  is  not  exact.  When  this  property  is  set,  sound  tracks  are 
not  played. 

kQTVRSyncVi ewToFrameRate 

Synchronize  the  view  animation  to  the  frame  animation.  When  view  animation 
is  enabled,  the  object  views  play  at  the  same  rate  and  animation  settings  as  the 
frame  animation  rate  and  settings.  This  is  useful  if  animation  must  be 
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QTVRGetAvailableResolutions 


synchronized  precisely  across  multiple  views  or  a  sound  track  is  to  be  played 
during  view  animation  instead  of  during  frame  animation. 

kQTVRPal 1 ndromeVi  ews 

Play  a  back-and-forth  animation  of  the  views  of  the  current  node.  When  view 
animation  is  enabled,  the  object  views  play  with  a  positive  or  negative  view 
rate;  the  view  rate  sign  is  switched  each  time  an  object's  pan  equals  the  object's 
minimum  pan  limit  or  the  object's  maximum  pan  limit  (the  first  column  in  a 
row  or  the  last  column  in  a  row,  respectively). 

kQTVRPl ayStreamingVi ews 

When  an  object  movie  is  streaming  in  from  a  network,  this  flag  indicates 
whether  the  frames  corresponding  to  the  row  in  which  the  default  view 
appears  are  to  be  played  as  they  are  loaded. 

Special  Considerations 

This  function  is  valid  only  for  object  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Object  Nodes"  (V-2909) 

See  Also 

Use  QTVRSetAni  mati  onSetti  ng  (11-1409)  to  set  the  state  of  an  animation  setting  for  an 
object  node. 


QTVRGetAvailableResolutions 


Obtains  the  image  resolutions  present  in  the  current  node. 

OSErr  QTVRGetAvailableResolutions  ( 

QTVRInstance  qtvr, 

UIntl6  *resol uti onsMask  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

resol uti onsMask 

On  entry,  a  pointer  to  an  unsigned  short  integer.  On  return,  that  integer  is  set 
to  a  bitmask  that  encodes  the  image  resolutions  (see  below)  available  at  the 
current  node. 
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function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

resolutionsMask  Constants 

kQTVRDef aul tRes 

The  default  resolution  of  the  image. 
kQTVRFul 1  Res 

The  full  resolution  of  the  image. 
kQTVRHal f Res 

One-half  the  full  resolution  of  the  image. 
kQTVRQuarterRes 

One-quarter  the  full  resolution  of  the  image. 

Discussion 

A  single  node  can  contain  multiple  resolutions  of  a  panorama  or  an  object.  The 
lowest  order  bit  is  always  set  and  corresponds  to  the  base  resolution  of  the  node. 
Each  succeeding  bit  corresponds  to  a  resolution  that  is  half  that  (both  horizontally 
and  vertically)  of  the  preceding  bit.  If  an  image  with  a  corresponding  resolution  is 
present  in  the  current  node,  that  bit  is  set. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  VR  Memory"  (V-2913) 


QTVRGetBackBufferMemlnfo 


Obtains  information  about  the  internal  back  buffer  that  QuickTime  VR  maintains 
for  caching  panoramic  images. 

OSErr  QTVRGetBackBufferMemlnfo  ( 

QTVRInstance  qtvr, 

UInt32  geometry, 

UIntl6  resolution, 

UInt32  cachePixel Format , 

SInt32  *mi nCacheBytes , 

SInt32  *suggestedCacheBytes , 

SInt32  *f ul 1 CacheBytes  ); 

qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
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geometry 

The  geometry  parameter  (see  below)  specifies  the  type  and  orientation  of  the 
panorama  data, 
resol uti on 

The  resolution  for  which  the  information  is  desired  (see  below). 
cachePi xel Format 

The  desired  pixel  format  for  the  back  buffer.  This  value  should  be  one  of  the 
defined  pixel  formats  (see  below), 
mi  nCacheBytes 

On  entry,  a  pointer  to  a  long  integer.  On  return,  that  long  integer  is  set  to  the 
minimum  size,  in  bytes,  of  the  back  buffer  required  to  display  the  specified 
panorama  with  a  severely  limited  maximum  field  of  view.  Set  this  parameter  to 
N I L  to  prevent  this  information  from  being  returned. 
suggestedCache Bytes 

On  entry,  a  pointer  to  a  long  integer.  On  return,  that  long  integer  is  set  to  the 
minimum  size,  in  bytes,  of  the  back  buffer  required  to  display  the  specified 
panorama  with  full  wide-angle  zooming.  Set  this  parameter  to  N I L  to  prevent 
this  information  from  being  returned. 

ful 1 CacheBytes 

On  entry,  a  pointer  to  a  long  integer.  On  return,  that  long  integer  is  set  to  the 
minimum  size,  in  bytes,  of  the  back  buffer  required  to  have  the  entire  panorama 
in  memory  at  once.  That  is  the  default  size  of  the  panorama  back  buffer.  Set  this 
parameter  to  N I L  to  prevent  this  information  from  being  returned. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

geometry  Constants 

kQTVRUseMovi eGeometry 
Value  is  0. 

kQTVRVerti cal Cyl  i  nder 

Vertical  cylinder  geometry.  Value  is  '  vcy  1 ' . 

resolution  Constants 

kQTVRDefaul tRes 

The  default  resolution  of  the  image. 
kQTVRFul 1  Res 

The  full  resolution  of  the  image. 
kQTVRHal f Res 

One-half  the  full  resolution  of  the  image. 


11-1348 


Inside  QuickTime:  Function  l-Q 


QTVRGetBackBufferMemlnfo 


kQTVRQuarterRes 

One-quarter  the  full  resolution  of  the  image. 

cachePixelFormat  Constants 

kQTVRMi ni mumCache 

The  minimum  cache  size  required  to  display  the  specified  movie. 
kQTVRSuggestedCache 

The  suggested  cache  size,  a  cache  large  enough  to  allow  full  zooming  out  of  the 
panorama. 

kQTVRFul 1  Cache 

The  full  cache  size  (that  is,  a  cache  that  is  large  enough  to  fit  the  entire  panorama 
in  memory).  This  is  the  default  cache  size. 

Discussion 

You  can  use  this  function  to  get  information  about  the  size  of  the  back  buffer  that 
would  be  required  for  caching  a  panoramic  image  of  a  specified  pixel  format, 
geometry,  and  resolution.  This  is  a  "what-if"  function:  you  specify  a  resolution  and 
a  pixel  format,  and  this  function  returns  several  buffer  sizes.  You  can  use  this 
information,  in  conjunction  with  QTVRSetBackBuf ferPrefs  (11-1412),  to  exercise  some 
control  over  the  size  of  the  back  buffer. 

The  resolution  at  which  an  image  is  to  be  displayed  is  specified  by  the  resolution 
parameter.  You  can  use  a  resolution  that  is  not  in  the  movie  file.  Relative  to  that 
resolution  and  the  pixel  depth  determined  by  the  cachePi  xel  Format  parameter,  this 
function  returns,  through  the  mi  nCacheBytes  parameter,  the  minimum  size  of  the 
buffer  needed  to  display  the  movie.  Using  a  buffer  of  that  size,  however,  may  result 
in  a  severely  limited  maximum  field  of  view.  You  can  call  the  QTVRGetVi  ewi  ngLimi  ts 
(11-1379)  function  to  determine  the  actual  maximum  field  of  view. 

To  allow  full  wide-angle  zooming,  you  should  use  a  buffer  whose  size  is  specified 
by  either  the  suggestedCacheBytes  parameter  or  the  ful  1  CacheBytes  parameter. 

Special  Considerations 

This  function  is  valid  only  for  panoramic  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  VR  Memory"  (V-2913) 
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QTVRGetBackBufferSettings 

Obtains  information  about  the  resolution,  pixel  format,  and  size  of  the  back  buffer 
maintained  internally  by  QuickTime  VR  for  caching  a  panoramic  image  in  a 
particular  pixel  format. 

OSErr  QTVRGetBackBufferSettings  ( 

QTVRInstance  qtvr, 

UInt32  *geometry, 

UIntl6  Resolution, 

UInt32  *cachePi xel Format , 

SIntl6  *cacheSize  ); 

qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

geometry 

The  type  and  orientation  of  the  panorama  data  (see  below), 
resol uti on 

On  entry,  a  pointer  to  an  unsigned  short  integer.  On  return,  that  integer  is  set 
to  the  index  of  the  current  image  resolution  (see  below). 
cachePi xel Format 

On  entry,  a  pointer  to  a  long  integer.  On  return,  that  long  integer  is  set  to  the 
pixel  format  of  the  current  panorama  back  buffer  (see  below). 

cacheSi ze 

On  entry,  a  pointer  to  a  short  integer.  On  return,  that  integer  is  set  to  a  value 
that  describes  the  size  of  the  current  panorama  back  buffer. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

geometry  Constants 

kQTVRUseMovi eGeometry 
Value  is  0. 

kQTVRVerti cal Cyl  i  nder 

Vertical  cylinder  geometry.  Value  is  '  vcy  1 ' . 

resolution  Constants 

kQTVRDefaul tRes 

The  default  resolution  of  the  image. 
kQTVRFul 1  Res 

The  full  resolution  of  the  image. 
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kQTVRHal f Res 

One-half  the  full  resolution  of  the  image. 
kQTVRQuarterRes 

One-quarter  the  full  resolution  of  the  image. 

cachePixelFormat  Constants 

kl6LE555Pixel Format 

16-bit  LE  RGB  555  (Windows) 
kl6BE565Pixel Format 
16-bit  BE  RGB  565 
kl6LE565Pi xel Format 
16-bit  LE  RGB  565 
k24BGRPi xel Format 
24-bit  BGR 
k32ARGBPixel Format 
32-bit  ARGB 
k32BGRAPixel Format 

32-bit  BGRA  (Matrox) 
k32ABGRPixel Format 
32-bit  ABGR 
k32RGBAPixel Format 
32-bit  RGBA 

cacheSize  Constants 

kQTVRMi ni mumCache 

The  minimum  cache  size  required  to  display  the  specified  VR  movie. 
kQTVRSuggestedCache 

The  suggested  cache  size,  a  cache  large  enough  to  allow  full  zooming  out  of  the 
panorama. 

kQTVRFul 1  Cache 

The  full  cache  size  (that  is,  a  cache  that  is  large  enough  to  fit  the  entire  panorama 
in  memory).  This  is  the  default  cache  size. 

Discussion 

This  function  returns,  through  the  resol  uti  on  parameter,  the  index  of  the  current 
resolution  for  the  QuickTime  VR  movie  specified  by  the  qtvr  parameter.  The  index 
indicates  which  bit  in  the  mask  value  returned  by  QTVRGetAvai  1  able  Resolut  ions 
(11-1346)  specifies  the  current  resolution.  For  example,  if  the  returned  index  is  1,  the 
base  resolution  is  being  used.  If  the  returned  index  is  2,  then  a  resolution  of  half  the 
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base  resolution  is  being  used.  This  function  also  returns  the  pixel  format  and  the 
cache  size  in  the  cachePixel  Format  and  cacheSi  ze  parameters,  respectively. 

The  QuickTime  VR  file  might  not  contain  an  image  track  corresponding  to  the 
resolution  indicated  by  the  resolution  value  returned.  The  QuickTime  VR  Manager 
may  have  set  a  lower  resolution  because  memory  is  low,  or  the  resolution  may  have 
been  set  by  a  call  to  QTVRSetBackBuf ferPref s  (11-1412). 

Special  Considerations 

This  function  is  valid  only  for  panoramic  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  VR  Memory"  (V-2913) 

See  Also 

Use  QTVRSetBackBuf  ferPref  s  (11-1412)  to  set  the  resolution,  cache  depth,  and  cache 
size  of  the  panorama  back  buffer  maintained  internally  by  QuickTime  VR  for 
caching  an  image.  Use  QTVRGetAvai  1  abl  eResol  uti  ons  (11-1346)  to  determine  which 
resolutions  are  supported  by  a  node.  Use  QTVRGetBackBufferMemlnfo  (11-1347)  to 
determine  the  memory  requirements  for  the  preferred  settings. 


QTVRGetConstraints 


Obtains  the  current  constraints  of  a  QuickTime  VR  movie. 

OSErr  QTVRGetConstraints  ( 

QTVRInstance  qtvr, 

UIntl6  kind, 

float  *minValue, 

f 1  oat  *maxVal ue  ) ; 

qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

ki  nd 

The  type  of  constraints  to  be  returned  (see  below), 
mi nVal ue 

On  entry,  a  pointer  to  a  floating-point  value.  On  return,  the  current  minimum 
constraint  of  the  specified  type  is  copied  into  that  value. 
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maxVal ue 

On  entry,  a  pointer  to  a  floating-point  value.  On  return,  the  current  maximum 
constraint  of  the  specified  type  is  copied  into  that  value. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

kind  Constants 

kQTVRPan 

The  pan  angle.  The  associated  value  is  of  type  f  1  oat. 
kQTVRTilt 

The  tilt  angle.  The  associated  value  is  of  type  float. 
kQTVRFi  el  dOfVi  ew 

The  field  of  view.  The  associated  value  is  of  type  f  1  oat. 

Discussion 

This  function  returns,  in  the  floating-point  values  pointed  to  by  the  mi  nVal  ue  and 
maxVal  ue  parameters,  the  current  minimum  and  maximum  constraints  of  the  type 
specified  by  the  kind  parameter.  The  values  returned  by  this  function  are  unaffected 
by  the  current  control  settings. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Determining  Viewing  Limits  and  Constraints"  (V-2912) 

Related  Java  Methods 

qui cktime . vr . QTVRInstance . getConstrai nts_mi n( ) , 
qui cktime . vr . QTVRInstance . getConstrai nts_max( ) 


See  Also 

For  the  corresponding  set  function,  see  QTVRSetConstrai  nts  (11-1415),  used  to  set  a 
movie's  minimum  and  maximum  constraints. 


QTVRGetConstraintStatus 


Obtains  the  set  of  constraints  active  for  the  current  view. 

UInt32  QTVRGetConstraintStatus  ( 

QTVRInstance  qtvr  ); 
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qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

function  result  A  long  integer  (see  below)  whose  bits  encode  the  constraints 

currently  active  for  the  QuickTime  VR  movie  specified  by  the  qtvr 
parameter. 

Function  Result  Constants 

kQTVRUnconstrai ned 

The  view  has  no  constraints.  This  is  not  a  bit  selector  but  a  value  that  indicates 
that  none  of  the  other  bits  are  set. 

kQTVRCantPanLeft 

If  this  bit  is  set,  the  view  cannot  pan  left. 
kQTVRCantPanRi ght 

If  this  bit  is  set,  the  view  cannot  pan  right. 
kQTVRCantPanUp 

If  this  bit  is  set,  the  view  cannot  pan  up. 
kQTVRCantPanDown 

If  this  bit  is  set,  the  view  cannot  pan  down. 
kQTVRCantZoomln 

If  this  bit  is  set,  the  view  cannot  zoom  in. 
kQTVRCantZoomOut 

If  this  bit  is  set,  the  view  cannot  zoom  out. 
kQTVRCantT  ransl ate  Left 

If  this  bit  is  set,  the  view  cannot  translate  to  the  left.  This  constraint  is  valid  only 
for  object  nodes. 
kQTVRCantT  ransl ate Ri ght 

If  this  bit  is  set,  the  view  cannot  translate  to  the  right.  This  constraint  is  valid 
only  for  object  nodes. 
kQTVRCantT  ransl  ateLIp 

If  this  bit  is  set,  the  view  cannot  translate  up.  This  constraint  is  valid  only  for 
object  nodes. 
kQTVRCantT  ransl ateDown 

If  this  bit  is  set,  the  view  cannot  translate  down.  This  constraint  is  valid  only  for 
object  nodes. 
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Discussion 

The  values  returned  byQTVRGetConstraintStatus  are  unaffected  by  the  current 
control  settings. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Determining  Viewing  Limits  and  Constraints"  (V-2912) 


QTVRGetControlSetting 


Obtains  the  current  state  of  a  control  setting  for  an  object  node. 

OSErr  QTVRGetControlSetting  ( 

QTVRInstance  qtvr, 

QTVRControl Setti ng  setting. 

Boolean  *enable  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
setti ng 

A  control  setting  (see  below), 
enabl e 

On  entry,  a  pointer  to  a  Boolean  value.  On  return,  that  value  is  set  to  TRUE  if  the 
specified  control  setting  is  currently  enabled  for  the  specified  object  node  or  to 
FALSE  otherwise. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

setting  Constants 

kQTVRWrapPan 

Set  wrapping  during  panning.  When  this  control  setting  is  enabled,  the  user  can 
wrap  around  from  the  current  pan  constraint  maximum  value  to  the  pan 
constraint  minimum  value  (or  vice  versa)  using  the  mouse  or  arrow  keys.  In 
addition,  calling  QTVRSetPanAngl  e  (11-1431)  with  a  pan  angle  that  is  either  less 
than  or  greater  than  the  current  pan  constraints  results  in  a  pan  angle  within  the 
current  pan  constraints.  Similarly,  QTVRWrapAndConstrai  n  (11-1446)  returnsapan 
angle  within  the  current  pan  constraints,  and  QTVRNudge  (11-1402)  wraps  views 
after  it  reaches  the  maximum  or  minimum  constraint  value. 
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When  this  control  setting  is  disabled,  the  user  cannot  wrap  around  from  the 
current  pan  constraint  maximum  value  to  the  pan  constraint  minimum  value 
(or  vice  versa)  using  the  mouse  or  arrow  keys.  In  addition,  QTVRSetPanAngl  e 
returns  the  result  code  constrai  ntReachedErr  when  passed  a  pan  angle  that  is 
either  less  than  or  greater  than  the  current  pan  constraints.  Similarly, 
QTVRWrapAndConstrai  n  returns  a  pan  angle  that  is  one  of  the  current  pan 
constraints,  and  QTVRNudge  returns  the  result  code  constrai  ntReachedErr  when 
it  reaches  the  maximum  or  minimum  constraint  value. 

Note  that  a  view  animation  stops  when  a  constraint  is  reached  unless 
palindrome  view  animation  or  wrapping  during  panning  is  enabled. 

kQTVRWrapT i 1 t 

Set  wrapping  during  tilting.  When  this  control  setting  is  enabled,  the  user  can 
wrap  around  from  the  current  tilt  constraint  maximum  value  to  the  tilt 
constraint  minimum  value  (or  vice  versa)  using  the  mouse  or  arrow  keys.  In 
addition,  calling  QTVRSetT i  1  tAngl  e  (11-1434)  with  a  tilt  angle  that  is  either  less 
than  or  greater  than  the  current  tilt  constraints  results  in  a  tilt  angle  within  the 
current  tilt  constraints.  Similarly,  QTVRWrapAndConstrai  n  (11-1446)  returns  a  tilt 
angle  within  the  current  tilt  constraints,  and  QTVRNudge  (11-1402)  wraps  views 
after  it  reaches  the  maximum  or  minimum  constraint  value. 

When  this  control  setting  is  disabled,  the  user  cannot  wrap  around  from  the 
current  tilt  constraint  maximum  value  to  the  tilt  constraint  minimum  value  (or 
vice  versa)  using  the  mouse  or  arrow  keys.  In  addition,  the  QTVRSetT i  1  tAngl  e 
function  returns  the  result  code  constrai  ntReachedErr  when  passed  a  tilt  angle 
that  is  either  less  than  or  greater  than  the  current  tilt  constraints.  Similarly, 
QTVRWrapAndConstrai  n  returns  a  tilt  angle  that  is  one  of  the  current  tilt 
constraints,  and  QTVRNudge  returns  the  result  code  constrai  ntReachedErr  when 
it  reaches  the  maximum  or  minimum  constraint  value. 

kQTVRCanZoom 

Set  zooming  to  be  active.  When  this  control  setting  is  enabled,  the  user  can 
change  the  current  field  of  view  using  the  zoom-in  and  zoom-out  keys  on  the 
keyboard  (or  using  the  VR  controller  buttons).  In  addition,  you  can  use 
QTVRSetFi  el  dOfVi  ew  (11-1420)  to  alter  the  current  field  of  view.  Similarly, 
QTVRWrapAndConstrai  n  (11-1446)  returns  a  field  of  view  within  the  current  field 
of  view  constraints. 

When  this  control  is  disabled,  the  user  cannot  change  the  current  field  of  view 
using  the  zoom-in  and  zoom-out  keys  on  the  keyboard  (or  using  the  VR 
controller  buttons).  In  addition,  the  QTV  RSet  Fi  el  dOf  V  i  ew  function  returns  the 
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result  code  constraintReachedErr  and  doesn't  change  the  field  of  view. 
Similarly,  QTVRWrapAndConstrai  n  returns  the  current  field  of  view. 

kQTVRReverseHControl 

Reverse  the  direction  of  the  horizontal  control.  When  this  control  setting  is 
enabled,  the  user  can  change  an  object's  horizontal  view  using  the  mouse  or  the 
keyboard  arrows  with  reversed  values  for  mouse  horizontal  motion  and 
keyboard  left  and  right  arrows.  (In  other  words,  the  left  arrow  key  causes 
panning  to  the  right,  and  moving  the  mouse  right  causes  panning  to  the  left.) 
Similarly,  QTVRNudge  (11-1402)  nudges  left  when  you  pass  the  value  0  and  right 
when  you  pass  the  value  180.  This  control  setting  is  useful  when  an  object's 
frames  have  been  authored  in  reverse  order. 

kQTVRReverseVControl 

Reverse  the  direction  of  the  vertical  control.  When  this  control  setting  is 
enabled,  the  user  can  change  an  object's  vertical  view  using  the  mouse  or  the 
keyboard  arrows  with  reversed  values  for  mouse  vertical  motion  and  keyboard 
up  and  down  arrows.  (In  other  words,  the  up  arrow  key  causes  tilting  down, 
and  moving  the  mouse  down  causes  tilting  up.)  Similarly,  QTVRNudge  (11-1402) 
nudges  up  when  you  pass  the  value  270  and  down  when  you  pass  the  value  90. 
This  control  setting  is  useful  when  an  object's  frames  have  been  authored  in 
reverse  order. 
kQTVRSwapHVControl 

Exchange  the  horizontal  and  vertical  controls.  When  this  setting  is  enabled,  the 
user  can  pan  left  using  the  up  arrow  key  and  tilt  up  using  the  left  arrow  key. 
Similarly,  QTVRNudge  (11-1402)  nudges  up  when  you  pass  the  value  180  and 
down  when  you  pass  the  value  0.  This  control  setting  is  useful  if  an  object  is  a 
single-row  or  multirow  movie  containing  vertically  changing  images.  This  is 
especially  useful  when  enabling  view  animation  for  an  object  with  animating 
vertical  changes  in  view  (because  objects  will  animate  only  along  rows,  not 
along  columns). 

kQTVRT  ransl ati on 

Set  translation  to  be  active.  When  this  setting  is  enabled,  the  user  can  translate 
using  the  mouse  when  either  the  translation  key  is  held  down  or  the  controller 
translation  mode  button  is  toggled  on.  In  addition,  you  can  use  the 
QTVRSetVi  ewCenter  function  to  set  a  horizontal  and  vertical  position  in  the 
current  display  coordinate  system.  When  this  setting  is  disabled, 
QTVRWrapAndConstrai  n  (11-1446)  always  returns  the  current  view  center,  and 
QTVRSetVi  ewCenter  (11-1437)  returns  the  result  code  constrai  ntReachedErr  and 
doesn't  change  the  current  view  center. 
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Discussion 

This  function  returns,  through  the  enable  parameter,  the  current  state  of  the  control 
setting  specified  by  the  setti  ng  parameter  for  the  object  node  specified  by  the  qtvr 
parameter.  If  enable  is  TRUE,  the  specified  setting  is  currently  enabled;  otherwise,  the 
setting  is  disabled. 

Special  Considerations 

QTVRGetControl  Setti  ng  is  valid  only  for  object  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Object  Nodes"  (V-2909) 

See  Also 

Use  QTVRSet Control  Setti  ng  (11-1416)  to  set  the  state  of  a  control  setting  for  an  object 
node. 


QTVRGetCurrentMouseMode 


Obtains  the  current  mouse  control  modes. 

UInt32  QTVRGetCurrentMouseMode  ( 
QTVRInstance  qtvr  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

function  result  A  constant  (see  below)  that  describes  the  current  mouse  control 
modes. 

Function  Result  Constants 

kQTVRPanni ng 

If  this  bit  is  set,  the  mouse  controls  panning  of  standard  objects,  using 
objects-only  controllers. 

kQTVRT  ransl ati ng 

If  this  bit  is  set,  the  mouse  controls  translation  for  all  objects. 
kQTVRZoomi ng 

If  this  bit  is  set,  the  mouse  controls  zooming  for  all  objects. 
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kQTVRScrol 1 i ng 

If  this  bit  is  set,  the  mouse  controls  arrow  scrolling  for  standard  objects  and 
scrolling  for  joystick  objects. 
kQTVRSel ecti ng 

If  this  bit  is  set,  the  mouse  controls  selecting  of  objects  as  an  object  absolute 
controller. 

Discussion 

The  value  returned  by  this  function  is  an  unsigned  long  integer  that  encodes  the 
current  mouse  control  modes.  If  a  bit  in  the  integer  is  set,  the  corresponding  mode 
is  one  of  the  current  mouse  modes.  The  mode  bits  are  addressed  using  the  above 
constants.  Notice  that  several  modes  can  be  returned.  That  means  a  return  value 
could  have  both  zooming  and  translating  set,  for  example. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Object  Nodes"  (V-2909) 


QTVRGetCurrentNodelD 


Obtains  the  current  node  of  a  movie. 

UInt32  QTVRGetCurrentNodelD  ( 
QTVRInstance  qtvr  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

function  result  The  ID  of  the  current  node  of  the  specified  movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Getting  Scene  and  Node  Information"  (V-2906) 

Related  Java  Methods 

qui cktime . vr . QTVRInstance . getCurrentNodelDI ) 
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See  Also 

Use  QTVRGoToNodelD  (11-1386)  to  set  the  current  node  ID. 


QTVRGetCurrentViewDuration 


Obtains  the  duration  of  the  current  view  of  an  object  node. 

TimeValue  QTVRGetCurrentViewDuration  ( 

QTVRInstance  qtvr  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

function  result  The  duration  of  the  current  view  of  the  object  node  specified  by  the 
qtvr  parameter. 

Special  Considerations 

This  function  is  valid  only  for  object  nodes.  You  cannot  change  a  node's  view 
duration. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Object  Nodes"  (V-2909) 


QTVRGetFieldOfView 


Obtains  the  vertical  field  of  view  of  a  QuickTime  VR  movie. 

float  QTVRGetFieldOfView  ( 

QTVRInstance  qtvr  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

function  result  The  current  vertical  field  of  view  of  the  QuickTime  VR  movie 
specified  by  the  qtvr  parameter.  The  vertical  field  of  view  is  a 
floating-point  value  that  specifies  the  angle  created  by  the  two  lines 
that  connect  the  viewpoint  to  the  top  and  bottom  of  the  image. 
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Discussion 

The  following  code  fragment  illustrates  the  use  of  this  function: 

//  QTVRGetFi el dOfVi ew  coding  example 
#define  kDirln  4L 

#define  kDirOut  5L 

void  MyZoomlnOrOut  (QTVRInstance  thelnstance,  long  theDir) 

{ 

float  theFloat; 

theFloat  =  QTVRGetFiel dOfView(thelnstance) ; 
switch  (theDir)  { 
case  kDirln: 

theFloat  =  theFloat  /  2.0; 
break; 

case  kDirOut: 

theFloat  =  theFloat  *  2.0; 
break; 
def aul t : 
break; 

} 

QTVRSetFi el dOfVi ew( thelnstance ,  theFloat); 

QTVRUpdate( the  Instance,  kQTVRStati c) ; 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Manipulating  Viewing  Angles  and  Zooming"  (V-2905) 

Related  Java  Methods 

qui cktime . vr . QTVRInstance . get Fi el dOfVi ew( ) 

See  Also 

Use  QTVRSetFi  el  dOfVi  ew  (11-1420)  to  set  the  vertical  field  of  view  of  a  QuickTime  VR 
movie. 


QTVRGetFrameAnimation 

Obtains  the  current  state  of  frame  animation  for  an  object  node. 


Inside  QuickTime:  Function  l-Q 


11-1361 


QTVRGetFrameRate 


Boolean  QTVRGetFrameAnimation  ( 
QTVRInstance  qtvr  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

function  result  TRUE  if  frame  animation  is  currently  enabled,  FALSE  otherwise. 

Special  Considerations 

This  function  is  valid  only  for  object  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Object  Nodes"  (V-2909) 

See  Also 

Use  QTVREnabl  eFrameAni  mati  on  (11-1339)  to  set  the  state  of  frame  animation  for  an 
object  node. 


QTVRGetFrameRate 


Obtains  the  current  frame  rate  of  an  object  node. 

float  QTVRGetFrameRate  ( 

QTVRInstance  qtvr  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

function  result  The  current  frame  rate  of  the  object  node  specified  by  the  qtvr 

parameter.  A  frame  rate  is  a  floating-point  value  in  the  range  from 
-100.0  to  +100.0. 


Discussion 

An  object  node's  default  frame  rate  is  stored  in  the  movie  file. 

Special  Considerations 

QTVRGetFrameRate  is  valid  only  for  object  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


11-1362 


Inside  QuickTime:  Function  l-Q 


QTVRGetHotSpotRegion 


Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Object  Nodes"  (V-2909) 

See  Also 

Use  QTVRSetFrameRate  (11-1421)  to  set  the  frame  rate  of  an  object  node. 


QTVRGetHotSpotRegion 


Obtains  the  region  occupied  by  a  hot  spot. 

OSErr  QTVRGetHotSpotRegion  ( 
QTVRInstance  qtvr, 

UInt32  hotSpotID, 

RgnHandle  hotSpotRegi on  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

hotSpotID 

A  hot  spot  ID. 
hotSpotRegi on 

On  entry,  an  initialized  handle  to  a  region.  On  return,  this  region  is  rewritten 
with  the  region  occupied  by  the  hot  spot  having  the  specified  ID. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  returned  region  is  clipped  to  the  bounds  of  the  movie's  graphics  world.  You  can 
obtain  the  regions  of  all  visible  hot  spots  by  calling  QTVRGetVi  si  bl  eHotSpots 
(11-1384)  and  then  calling  this  function  for  each  hot  spot  ID  in  the  list. 

Special  Considerations 

The  first  time  you  call  this  function,  a  significant  amount  of  memory  might  need  to 
be  allocated.  Accordingly,  you  should  always  check  for  Memory  Manager  errors 
returned  by  this  function.  Your  application  is  responsible  for  disposing  of  the 
memory  occupied  by  the  returned  region. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Hot  Spots"  (V-2906) 


Inside  QuickTime:  Function  l-Q 


11-1363 


QTVRGetHotSpotType 


QTVRGetHotSpotType 

Obtains  the  type  of  a  QuickTime  VR  hot  spot. 

OSErr  QTVRGetHotSpotType  ( 

QTVRInstance  qtvr, 

UInt32  hotSpotID, 

OSType  *hotSpotType  ) ; 

qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
hotSpotID 

A  hot  spot  ID. 
hotSpotType 

On  entry,  a  pointer  to  a  long  integer.  On  return,  that  long  integer  contains  the 
type  of  the  hot  spot  specified  by  the  hot  spot  ID. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  gets  the  type  of  a  hot  spot  whose  ID  you  specify.  In  combination  with 
the  kQTVRGetHotSpotTypeSel  ector  intercept  selector  (see  QTVRInstal  1  InterceptProc 
(11-1387)),  this  allows  an  application  to  change  a  hot  spot's  type  dynamically.  For 
example,  an  application  can  take  an  existing  movie  and  cause  VR  to  display  the 
cursors  for  a  type  of  hotspot  different  from  the  one  the  movie  was  originally 
authored  with.  In  combination  with  intercepting  kQTVRTriggerHotSpotSelector,  this 
would  allow  an  Internet  plugin  to  override  undefined  or  link  hotspots  in  movies  to 
make  them  appear  and  act  as  though  they  are  URL  links  instead.  If 
kQTVRTri  ggerHotSpotSel  ector  is  not  intercepted,  VR  will  attempt  to  act  on  the 
hotspot  in  the  normal  way;  by  storing  both  link  and  URL  data  in  a  file,  the  exact 
behavior  can  be  determined  at  runtime  by  an  application  to  allow  linking  to  either 
another  node  locally  or  a  remote  URL  link,  depending  on  system  configuration  or 
other  arbitrary  considerations. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Hot  Spots"  (V-2906) 

Related  Java  Methods 

qui ckti me . vr . QTVRInstance .getHotSpotTypet ) 


11-1364 


Inside  QuickTime:  Function  l-Q 


QTVRGetlmagingProperty 


See  Also 

Use  kQTVRGetHotSpotTypeSel  ector  with  QTVRInstal  1  InterceptProc  (11-1387)  to  set 
the  selector  for  the  intercept  procedure. 


QTVRGetlmagingProperty 


Obtains  the  current  value  of  an  imaging  property  of  a  movie. 

OSErr  QTVRGetlmagingProperty  ( 

QTVRInstance  qtvr, 

QTVRImagi ngMode  imagingMode, 

UInt32  imagi ngProperty , 

SInt32  *propertyVal ue  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

i magi ngMode 

An  imaging  mode  (see  below), 
i magi ngProperty 

An  imaging  property  (see  below). 
propertyVal ue 

On  entry,  a  pointer  to  a  long  integer.  On  return,  that  long  integer  contains  the 
current  value  of  the  specified  imaging  property  for  the  specified  mode. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

imagingMode  Constants 

kQTVRStati c 

The  panorama  is  static 
kQTVRMoti on 

The  panorama  is  in  motion;  that  is,  an  action  such  as  panning  or  zooming  is 
occurring. 

kQTVRAll Modes 

All  currently  defined  imaging  modes.  You  can  specify  this  imaging  mode  when 
calling  QTVRSetlmagi  ngProperty  (11-1422)  to  assign  a  value  to  a  particular 
imaging  property  for  all  imaging  modes.  You  can  also  use  this  imaging  mode 
in  the  imagingMode  field  of  a  QTVRPano  Imagi  ngAtom  (IV-2398)  structure  to  indicate 
a  default  value  for  a  particular  imaging  property  for  all  imaging  modes. 


Inside  QuickTime:  Function  l-Q 


11-1365 


QTVRGetlmagingProperty 


imagingProperty  Constants 

kQTVRImagi ngCorrection 

The  correction  mode  property  (see  below).  This  property  determines  the  type 
of  image  correction  to  be  applied  when  imaging  a  panoramic  view. 

kQTVRImagi ngQual i ty 

The  imaging  quality  property  (see  below).  This  property  determines  the  quality 
of  the  output  image. 
kQTVRImagi ngDirectDraw 

The  direct-drawing  property.  This  property  determines  the  immediate 
destination  of  an  image.  The  value  of  this  property  (as  specified  by  the 
propertyVal  ue  parameter)  is  interpreted  as  a  Bool  ean  value.  If  the  value  is  TRUE, 
then  images  are  computed  and  drawn  directly  to  the  final  destination  without 
first  being  drawn  in  the  prescreen  buffer  maintained  by  QuickTime  VR.  This 
value  provides  the  fastest  overall  frame  rate  but  may  result  in  relatively  slower 
individual  frame  drawing  for  high-quality,  high-resolution  images  on  lower 
performance  systems.  If  the  value  of  this  property  is  FALSE,  then  images  are 
computed  and  drawn  first  into  the  prescreen  buffer  and  then  to  the  final 
destination.  This  value  provides  the  shortest  imaging  time  for  each  individual 
frame  but  results  in  a  reduced  overall  frame  rate. 

Note  that  the  kQTVRImagi  ngDi  rectDraw  property  cannot  always  be  supported. 
During  updates,  QuickTime  VR's  warping  engine  might  ignore  a  value  of  TRU  E 
and  draw  the  image  first  into  the  prescreen  buffer  and  then  into  the  final 
destination 

kQTVRImagi ngCurrentMode 

The  current  imaging  mode  property.  When  you  pass  this  property  selector  to 
this  function,  it  returns,  in  the  propertyVal  ue  parameter,  the  current  imaging 
mode  (that  is,  either  kQTVRStati  c  or  kQTVRMoti  on).  If  the 

kQTVRImagi  ngDef  aul  tVal  ue  bit  is  set,  the  default  imaging  mode  is  returned.  You 
can  get  but  not  set  the  value  of  this  property.  You  might  want  to  determine  the 
current  imaging  mode  in  an  imaging  callback  procedure  if  what  you  draw 
depends  on  the  current  imaging  mode. 

kQTVRImagi ngDefaultValue 

The  default  value  specifier.  You  can  OR  this  value  with  any  of  the  imaging 
property  types  to  get  or  set  the  default  value  of  that  property  type 

kQTVRImagingCorrection  Constants 

kQTVRNoCorrecti on 

Apply  no  warping.  The  source  panorama  is  reproduced  directly,  with  no  image 
correction. 


11-1366 


Inside  QuickTime:  Function  l-Q 


QTVRGetlmagingProperty 


kQTVRParti al Correcti  on 

Apply  one-dimensional  (horizontal)  warping.  This  kind  of  correction  is  often 
sufficient,  especially  for  outdoor  scenes. 
kQTVRFul 1 Correcti on 

Apply  two-dimensional  warping.  This  correction  mode  produces  images  in 
correct  perspective  from  the  source  panorama. 

kQTVRImagingQuality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 
codecNormal Quality 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 

codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field. 

Discussion 

This  function  returns,  in  the  long  integer  pointed  to  by  the  propertyVal  ue 
parameter,  the  current  value  of  the  property  specified  by  the  i  magi  ngProperty 
parameter  when  the  QuickTime  VR  movie  specified  by  the  qtv  r  parameter  is  in  the 
mode  specified  by  the  imagi  ngMode  parameter. 

Special  Considerations 

QTVRGetlmagi  ngProperty  is  valid  only  for  panoramic  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Imaging  Characteristics"  (V-2910) 

Related  Java  Methods 

qui cktime . vr . QTVRInstance . get  I magi ngProperty ( ) 


See  Also 

Use  QTVRSetlmagi  ngProperty  (11-1422)  to  set  an  imaging  property. 


Inside  QuickTime:  Function  l-Q 


11-1367 


QTVRGetlnteractionProperty 


QTVRGetlnteractionProperty 


Obtains  the  value  of  an  interaction  property. 

OSErr  QTVRGetlnteractionProperty  ( 
QTVRInstance  qtvr, 

UInt32  property, 

voi d  *val ue  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
property 

An  interaction  property  type  (see  below), 
val  ue 

On  entry,  a  pointer  to  a  block  of  memory.  On  return,  that  memory  contains  the 
current  value  of  the  specified  interaction  property. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

property  Constants 

kQTVRInteracti onMouseCl i ckHysteresi s 

The  value  parameter  is  interpreted  as  an  unsigned  short  integer  that  represents 
the  mouse-click  hysteresis,  the  distance,  in  pixels,  from  the  location  of  a 
mouse-down  event  to  the  limit  within  which  the  cursor  is  considered  not  to 
have  moved.  In  other  words,  the  cursor  can  move  that  many  pixels  during  a 
mouse  click  and  still  have  the  event  considered  a  click.  The  default  mouse-click 
hysteresis  value  is  2.  This  property  is  valid  for  panoramas  only. 
kQTVRInteracti onMouseCl i ckTimeout 

The  value  parameter  is  interpreted  as  an  unsigned  long  integer  that  represents 
the  mouse-click  timeout,  the  number  of  ticks  after  which  a  mouse  click  times 
out  and  is  automatically  switched  from  a  hot  spot  selection  into  a  pan.  The 
default  mouse-click  timeout  value  is  30  ticks  (one-half  second).  This  property  is 
valid  for  panoramas  only. 
kQTVRInteracti onPanTiltSpeed 

The  panning  and  tilting  speed.  The  value  parameter  is  interpreted  as  an 
unsigned  long  integer  that  represents  the  relative  speed  of  panning  and  tilting. 
This  integer  should  be  from  1  (the  slowest  speed)  through  10  (the  fastest  speed); 
the  default  panning  and  tilting  speed  is  5.  This  property  is  valid  only  for 
panoramas. 
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QTVRGetlnteractionProperty 


kQTVRInteracti onZoomSpeed 

The  value  parameter  is  interpreted  as  an  unsigned  long  integer  that  represents 
the  zooming  speed,  the  relative  speed  of  zooming  in  and  out.  This  integer 
should  be  from  1  (the  slowest  speed)  through  10  (the  fastest  speed);  the  default 
zooming  speed  is  5.  This  property  is  valid  for  both  objects  and  panoramas. 
kQTVRInteracti onTransl ateOnMouseDown 

The  translate  flag.  The  value  parameter  is  interpreted  as  a  Bool  ean  value  that 
indicates  whether  translate  mode  is  enabled  (true)  or  disabled  (false).  When 
translate  mode  is  enabled,  the  user  can  no  longer  pan  or  tilt  using  the  mouse; 
instead,  dragging  the  cursor  causes  the  object  to  translate.  The  default  translate 
flag  value  is  false.  This  property  is  valid  for  objects  only. 

kQTVRInteracti onMouseMoti onScal e 

The  value  parameter  is  interpreted  as  a  pointer  to  a  floating-point  number  that 
represents  the  mouse-motion  scale,  the  number  of  degrees  or  radians  that  an 
object  or  panorama  is  panned  or  tilted  when  the  cursor  is  dragged  the  entire 
width  of  the  object  bounding  box.  The  default  value  is  180.0.  This  property  is 
valid  for  objects  only. 
kQTVRInteracti onNudgeMode 

This  parameter  lets  you  set  the  QuickTime  VR  nudge  mode  (see  below)  to  either 
rotate,  translate,  or  be  the  same  as  the  current  mouse  mode. 

Nudge  Mode  Constants 

kQTVRNudgeRotate 

Set  the  nudge  mode  to  rotate  the  object. 
kQTVRNudgeT ransl  ate 

Set  the  nudge  mode  to  translate  the  image. 
kQTVRNudgeSameAs Mouse 

Set  the  nudge  mode  to  the  same  as  the  current  mouse  mode,  which  you  can 
determine  by  calling  QTVRGetCurrentMouseMode  (11-1358). 

Discussion 

This  function  returns,  in  the  block  of  memory  pointed  to  by  the  value  parameter,  the 
current  value  of  the  property  specified  by  the  property  parameter  for  the 
QuickTime  VR  movie  specified  by  the  qtvr  parameter.  That  block  of  memory  must 
be  large  enough  to  hold  the  returned  value. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  QuickTime  VR  Movie  Interactions"  (V-2912) 


Inside  QuickTime:  Function  l-Q 


11-1369 


QT  VRG  etMous  eD  o  wnTracking 


See  Also 

Use  QTVRSetlnteracti  onProperty  (11-1425)  to  set  an  interaction  property. 


QTVRGetMouseDownT  racking 


Obtains  the  current  state  of  mouse-down  tracking. 

Boolean  QTVRGetMouseDownTracki ng  ( 

QTVRInstance  qtvr  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

function  result  A  Bool  ean  value  that  indicates  whether  QuickTime  VR  is  currently 
handling  mouse-down  tracking  for  the  QuickTime  VR  movie 
specified  by  the  qtvr  parameter  (TRUE)  or  not  (FALSE). 

Discussion 

By  default,  QuickTime  VR  tracks  mouse  clicks  in  a  QuickTime  VR  movie  and 
triggers  hot  spots  as  necessary. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Handling  Events"  (V-2907) 

See  Also 

Use  QTVRSetMouseDownT racki  ng  (11-1429)  to  change  the  mouse-down  tracking  state 
of  a  QuickTime  VR  movie. 


QT  VRGetMouseO  verT  racking 


Obtains  the  current  state  of  mouse-over  tracking. 

Boolean  QTVRGetMouseOverTracki ng  ( 
QTVRInstance  qtvr  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
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QTVRGetNodelnfo 


function  result  A  Bool  ean  value  that  indicates  whether  QuickTime  VR  is  currently 
handling  mouse-over  tracking  for  the  QuickTime  VR  movie 
specified  by  the  qtvr  parameter  (TRUE)  or  not  (FALSE). 

Discussion 

By  default,  QuickTime  VR  tracks  mouse  movements  in  a  QuickTime  VR  movie  and 
changes  the  shape  of  the  cursor  as  appropriate. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Handling  Events"  (V-2907) 

See  Also 

Use  QTVRSetMouseOverT racki  ng  (11-1431)  to  change  the  mouse-over  tracking  state  of 
a  QuickTime  VR  movie. 


QTVRGetNodelnfo 


Obtains  the  node  information  atom  container  that  describes  a  node  and  all  the  hot 
spots  in  the  node. 

OSErr  QTVRGetNodelnfo  ( 

QTVRInstance  qtvr, 

UInt32  nodelD, 

QTAtomContai ner  *node!nfo  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

nodelD 

A  node  ID.  Set  this  parameter  to  kQTVRCurrentNode  to  receive  information  about 
the  current  node. 

nodeinfo 

On  return,  a  pointer  to  an  atom  container  that  contains  information  about  the 
specified  node. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns,  in  the  n  o  d  e  I  n  f  o  parameter,  a  pointer  to  an  atom  container  that 
contains  information  about  the  node  specified  by  the  nodelD  parameter  in  the  movie 


Inside  QuickTime:  Function  l-Q 
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QTVRGetNodeType 


specified  by  the  qtvr  parameter.  The  atom  container  includes  information  about  all 
the  hot  spots  contained  in  that  node.  You  can  use  the  QuickTime  atom  functions  to 
extract  atoms  from  that  container.  You  can  also  use  those  functions  to  access  the  hot 
spot  atom  list.  All  hot  spot  atoms  are  contained  in  the  hot  spot  parent  atom. 

Special  Considerations 

The  node  information  atom  container  returned  by  this  function  is  a  copy  of  the  atom 
container  maintained  internally  by  the  QuickTime  VR  Manager.  You  should 
dispose  of  the  node  information  atom  container,  by  calling  QTDi  sposeAtomContai  ner 
(11-1164),  when  you're  finished  using  it. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Getting  Scene  and  Node  Information"  (V-2906) 

Related  Java  Methods 

qui ckti me . std .movi es . AtomContai ner . f romQTVRInstanceNode( ) , 
qui ckti me . vr . QTVRInstance .getNodelnfot ) 


See  Also 


QTVRGetNodeType 


Obtains  the  type  of  a  movie  node. 

OSType  QTVRGetNodeType  ( 
QTVRInstance  qtvr, 

UInt32  nodelD  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

nodelD 

A  node  ID.  Pass  kQTVRCurrentNode  for  the  current  node. 


function  result  The  type  of  the  node  specified  by  the  nodelD  parameter  in  the 
QuickTime  VR  movie  specified  by  the  qtvr  parameter. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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QTVRG  etPanAngle 


Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Getting  Scene  and  Node  Information"  (V-2906) 

Related  Java  Methods 

qui cktime . vr . QTVRInstance .  getNodeTypel ) 


QTVRGetPanAngle 


Obtains  the  pan  angle  of  a  QuickTime  VR  movie. 

float  QTVRGetPanAngle  ( 

QTVRInstance  qtvr  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 


function  result  A  floating-point  value  that  represents  the  current  pan  angle  of  the 
QuickTime  VR  movie  specified  by  the  qtvr  parameter. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Manipulating  Viewing  Angles  and  Zooming"  (V-2905) 

Related  Java  Methods 

qui cktime . vr . QTVRInstance . getPanAngl e( ) 


See  Also 

Use  QTVRSetPanAngl  e  (11-1431)  to  set  the  pan  angle  of  a  movie. 


QTVRGetQTVRInstance 


Obtains  an  instance  of  a  QuickTime  VR  movie. 


OSErr  QTVRGetQTVRInstance  ( 
QTVRInstance  *qtvr. 

Track  qtvrTrac 

Movi eControl 1 er  me  ); 


k. 


Inside  QuickTime:  Function  l-Q 


11-1373 


QTVRGetQTVRInstance 


qtvr 

On  return,  an  instance  of  the  specified  QuickTime  VR  movie. 
qtvrT  rack 

A  QTVR  track  contained  in  a  QuickTime  movie.  You  can  obtain  a  reference  to 
this  track  by  calling  QTVRGetQTVRTrack  (11-1375). 

me 

An  identifier  for  the  movie  controller  to  be  associated  with  the  new  QuickTime 
VR  movie  instance.  You  obtain  this  identifier  from  OpenComponent  (11-1130)  or 
OpenDef  aul  tComponent  (11-1131),  or  from  NewMovi  eControl  1  er  (11-1071). 

function  result  If  qtvrT  rack  does  not  specify  a  QTVR  track,  this  function  returns  NIL 
in  the  qtvr  parameter  and  an  error  code  as  its  function  result.  See 
"Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  need  a  QuickTime  VR  movie  instance  to  call  most  other  QuickTime  VR 
functions.  This  function  returns,  in  the  qtvr  parameter,  an  instance  of  the 
QuickTime  VR  movie  specified  by  the  qtvrT  rack  parameter.  Here's  an  example  of 
code  that  gets  a  QTVR  instance: 

//  QTVRGetQTVRInstance  coding  example 

//  See  “Discovering  QuickTime,”  page  390 

QTVRInstance  MyGetQTVRInstanceFromMC  ( Movi eControl 1 er  me) 

{ 

Track  track  =  NIL; 

QTVRInstance  qtvrinstance  =  NIL; 

Movie  movie  =  NIL; 

//Get  the  movie  from  the  movie  controller, 
movie  =  MCGetMovi e(mc) ; 

if  (movie  !=  NIL)  { 

//Get  the  first  QTVR  track  in  the  movie, 
track  =  QTVRGetQTVRTrack(movi e ,  1); 

//Get  a  QTVR  instance  for  that  QTVR  track, 
if  (track  !=  NIL)  { 

QTVRGetQTVRInstance(qtvrinstance,  track,  me); 

//Set  our  units  to  be  degrees, 
if  (qtvrinstance  !=  NIL) 

QTVRSetAngul  arllnitstqtvr  instance,  kQTVRDegrees ) ; 

} 


11-1374 


Inside  QuickTime:  Function  l-Q 


QTVRGetQTVRTrack 


} 

return  qtvri nstance ; 

} 

Special  Considerations 

It's  not  necessary  to  dispose  of  a  QuickTime  VR  movie  instance. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  QuickTime  VR  Movie  Instances"  (V-2904) 

Related  Java  Methods 

qui cktime . vr . QTVRI nstance . QTVRI nstance! ) 


QTVRGetQTVRTrack 


Obtains  a  QTVR  track  contained  in  a  QuickTime  movie  to  use  in  the 
QTVRGetQTVRI nstance  (11-1373)  call. 

Track  QTVRGetQTVRTrack  ( 

Movie  theMovie, 

SInt32  index  ); 

theMovi e 

A  QuickTime  movie, 
i  ndex 

The  index  of  the  desired  QTVR  track. 

function  result  A  track  identifier  for  the  QTVR  track  that  has  the  index  specified  by 
the  index  parameter  in  the  QuickTime  movie  specified  by  the 
theMovie  parameter.  If  there  is  no  such  track,  or  the  movie  is  not  a 
QTVR  movie,  this  function  returns  the  value  N I L. 

Discussion 

Here's  an  example  of  using  this  function  to  help  get  an  instance  of  a  QTVR  movie 
running  in  a  movie  controller: 

//  QTVRGetQTVRTrack  coding  example 

//  See  “Discovering  QuickTime,”  page  390 

QTVRInstance  MyGetQTVRInstanceFromMC  (MovieControl 1 er  me) 


Inside  QuickTime:  Function  l-Q 


11-1375 


QTVRGetQTVRTrack 


T  rack 

QTVRInstance 
Movi  e 


track  =  NIL; 
qtvrinstance  =  NIL; 
movi e  =  NIL; 


//Get  the  movie  from  the  movie  controller, 
movie  =  MCGetMovie(mc) ; 


if  (movie  !=  NIL)  { 

//Get  the  first  QTVR  track  in  the  movie, 
track  =  QTVRGetQTVRTracktmovi e  ,  1); 


} 


//Get  a  QTVR  instance  for  that  QTVR  track, 
if  (track  !=  NIL)  { 

QTVRGetQTVRInstance(qtvrinstance,  track,  me); 

//Set  our  units  to  be  degrees, 
if  (qtvrinstance  !=  NIL) 

QTVRSetAngul arUnitstqtvr instance,  kQTVRDegrees ) ; 

} 


return  qtvrinstance; 

} 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier.  QuickTime  VR  2.1  supports  files  with  at  most 
one  QTVR  track;  hence  the  value  for  the  index  parameter  of  a  movie  made  with 
QuickTime  VR  2.1  is  always  1.  Panorama  and  object  movies  made  with  QuickTime 
VR  version  1.0  have  no  QTVR  track.  This  function  returns  the  track  ID  of  the 
panorama  track  for  version  1.0  panorama  movies  and  the  track  ID  of  the  image 
video  track  for  version  1.0  object  movies. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  QuickTime  VR  Movie  Instances"  (V-2904) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . getQTVRT  rack( ) 


See  Also 

Use  QTVRGetQTVRInstance  (11-1373)  to  get  a  QuickTime  VR  movie  instance  from  the 
track  identifier  returned  by  this  function. 


11-1376 


Inside  QuickTime:  Function  l-Q 


QTVRGetTilt  Angle 


QT  VRGetT  ilt  Angle 


Obtains  the  tilt  angle  of  a  QuickTime  VR  movie. 

float  QTVRGetTi  1  tAngl  e  ( 

QTVRInstance  qtvr  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRI instance  (11-1373). 


function  result  A  floating-point  value  that  represents  the  current  tilt  angle  of  the 
QuickTime  VR  movie  specified  by  the  qtvr  parameter. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Manipulating  Viewing  Angles  and  Zooming"  (V-2905) 

Related  Java  Methods 

qui cktime . vr . QTVRInstance . getT i 1 tAngl e( ) 


See  Also 

Use  QTVRSetT i  1  tAngl  e  (11-1434)  to  set  the  tilt  angle  of  a  movie. 


QTVRGetViewAnimation 


Obtains  the  current  state  of  view  animation  for  an  object  node. 

Boolean  QTVRGetViewAnimation  ( 

QTVRInstance  qtvr  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRI nstance  (11-1373). 

function  result  A  B  o  o  1  e  a  n  value  that  indicates  the  current  state  of  view  animation  for 
the  object  node  specified  by  the  qtvr  parameter.  It  is  TRUE  if  view 
animation  is  enabled,  FALSE  otherwise. 

Special  Considerations 

This  function  is  valid  only  for  object  nodes. 


Inside  QuickTime:  Function  l-Q 


11-1377 


QTVRGetViewCenter 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Object  Nodes"  (V-2909) 

See  Also 

Use  QTVREnabl  eVi  ewAni  mati  on  (11-1342)  to  set  the  state  of  view  animation  for  an 
object  node. 


QT  VRGetV  iewCenter 


Obtains  the  view  center  of  a  QuickTime  VR  movie. 

OSErr  QTVRGetViewCenter  ( 

QTVRInstance  qtvr, 

QTVRF1 oatPoi nt  *viewCenter  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

vi ewCenter 

On  entry,  a  pointer  to  a  QTVRF1  oatPoi  nt  (IV-2396)  structure.  On  return,  that 
structure  contains  the  current  view  center  of  the  specified  movie. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

This  function  is  valid  only  for  object  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Manipulating  Viewing  Angles  and  Zooming"  (V-2905) 

Related  Java  Methods 

qui ckti me . vr . QTVRInstance . getVi ewCenter ( ) 


See  Also 

Use  QTVRSetVi  ewCenter  (11-1437)  to  set  the  view  center  of  a  movie. 


11-1378 


Inside  QuickTime:  Function  l-Q 


QTVRG  et  Vie  wCurrentTime 


QTVRGetViewCurrentTime 


Obtains  the  current  time  in  the  current  view. 

TimeValue  QTVRGetViewCurrentTime  ( 
QTVRInstance  qtvr  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

function  result  The  current  time  in  the  current  view  of  the  object  node  specified  by 
the  qtvr  parameter.  The  returned  value  is  always  greater  than  or 
equal  to  0  and  less  than  or  equal  to  the  value  returned  by 
QTVRGetCurrentVi  ewDurati  on  (11-1360). 

Special  Considerations 

QTVRGetVi  ewCurrentT i  me  is  valid  only  for  object  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Object  Nodes"  (V-2909) 

See  Also 

Use  QTVRSetVi  ewCurrentT i  me  (11-1438)  to  set  the  current  time  of  an  object  node. 


QTVRGetViewingLimits 


Obtains  the  current  viewing  limits  of  a  QuickTime  VR  movie. 

OSErr  QTVRGetViewingLimits  ( 

QTVRInstance  qtvr, 

UIntl6  kind, 

float  *minValue, 

float  *maxValue  ); 

qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

ki  nd 

The  type  of  viewing  limits  to  be  returned  (see  below). 


Inside  QuickTime:  Function  l-Q 


11-1379 


QTVRGetViewParameter 


mi nVal ue 

On  entry,  a  pointer  to  a  floating-point  value.  On  return,  the  minimum  viewing 
limit  of  the  specified  type  is  copied  into  that  value. 
maxVal ue 

On  entry,  a  pointer  to  a  floating-point  value.  On  return,  the  maximum  viewing 
limit  of  the  specified  type  is  copied  into  that  value. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

kind  Constants 

kQTVRPan 

The  pan  angle.  The  associated  value  is  of  type  f  1  oat. 
kQTVRT i 1 t 

The  tilt  angle.  The  associated  value  is  of  type  f  1  oat. 
kQTVRFi el dOfVi ew 

The  field  of  view.  The  associated  value  is  of  type  f  1  oat. 

Discussion 

This  function  returns,  in  the  floating-point  values  pointed  to  by  the  mi  nVal  ue  and 
maxVal  ue  parameters,  the  current  minimum  and  maximum  values  for  angles  whose 
type  is  specified  by  the  kind  parameter.  The  maximum  field  of  view  of  a  panoramic 
node  can  be  limited  by  the  size  of  the  back  buffer  and  the  current  aspect  ratio  of  the 
movie's  graphics  world.  The  values  returned  by  this  function  are  unaffected  by  the 
current  control  settings. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Determining  Viewing  Limits  and  Constraints"  (V-2912) 

See  Also 

This  function  returns  information  about  the  physical  viewing  limits  of  a  panorama 
or  object.  To  get  information  about  the  current  viewing  constraints,  use 
QTVRGetConstrai nts  (11-1352). 


QT  VRGetV  iewParameter 


Undocumented 

OSErr  QTVRGetViewParameter  ( 
QTVRInstance  qtvr. 


11-1380 


Inside  QuickTime:  Function  l-Q 


QTVRGetViewRate 


UInt32 
voi  d 
UInt32 
UInt32 


viewParameter, 
*val ue , 
f 1 ags In  , 
*flagsOut  ); 


qtvr 

Undocumented 
vi ewParameter 

Undocumented 
val  ue 

Undocumented 
fl agsln 

Undocumented 
f 1 agsOut 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 


QTVRGetViewRate 


Obtains  the  current  view  rate  of  an  object  node. 

float  QTVRGetViewRate  ( 

QTVRInstance  qtvr  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

function  result  The  current  view  rate  of  the  object  node  specified  by  the  qtvr 

parameter.  A  view  rate  is  a  floating-point  value  in  the  range  from 
-100.0  to  +100.0.  An  object  node's  default  view  rate  is  stored  in  the 
movie  file. 


Special  Considerations 

This  function  is  valid  only  for  object  nodes. 


Inside  QuickTime:  Function  l-Q 


11-1381 


QTVRGetViewState 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Object  Nodes"  (V-2909) 

See  Also 

Use  QTVRSetVi  ewRate  (11-1439)  to  set  the  view  rate  of  an  object  node. 


QT  VRGetV  iewState 


Obtains  the  value  of  a  view  state. 

OSErr  QTVRGetViewState  ( 

QTVRInstance  qtvr, 

QTVRVi ewStateType  vi ewStateType , 

UIntl6  *state  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
vi ewStateType 

A  view  state  type  (see  below), 
state 

On  entry,  a  pointer  to  a  short  integer.  On  return,  that  integer  is  set  to  the  current 
value  of  the  specified  type  of  view  state. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

viewStateType  Constants 

kQTVRDefaul t 

The  default  view  state  of  the  current  view.  The  default  view  state  is  a  set  of 
object  images  defined  by  view  duration,  row,  and  column.  The  default  view 
state  image  for  a  given  view  is  displayed  when  the  mouse  button  is  not  down. 
kQTVRCurrent 

The  current  view  state  of  the  current  view.  The  current  view  state  can  be  any  of 
the  view  states  authored  in  an  object  movie.  Setting  the  current  view  state  does 
not  change  the  view  state  designated  as  the  kQTVRDefaul  t  or  kQTVRMouseDown 
view  state.  The  effect  of  changing  the  current  view  state  lasts  until  a  transition 
to  the  mouse-down  or  default  view  state  occurs. 


11-1382 


Inside  QuickTime:  Function  l-Q 


QTVRGetViewStateCount 


kQTVRMouseDown 

The  mouse-down  state  of  the  current  view.  The  mouse-down  view  state  is  a  set 
of  object  images  defined  by  view  duration,  row,  and  column.  The  mouse-down 
view  state  image  for  a  given  view  is  displayed  when  the  user  holds  the  mouse 
button  down  while  the  cursor  is  over  an  object  movie. 

Special  Considerations 

This  function  is  valid  only  for  object  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Object  Nodes"  (V-2909) 

See  Also 

Use  QTVRSetVi  ewState  (11-1440)  to  set  the  value  of  a  view  state. 


QTVRGetViewStateCount 


Obtains  the  number  of  view  states  of  an  object  node. 

UIntl6  QTVRGetViewStateCount  ( 

QTVRInstance  qtvr  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

function  result  The  number  of  view  states  associated  with  the  object  node  specified 
by  the  qtvr  parameter.  The  number  of  view  states  in  an  object  movie 
is  defined  by  the  movie  file. 

Special  Considerations 

This  function  is  valid  only  for  object  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Object  Nodes"  (V-2909) 


Inside  QuickTime:  Function  l-Q 


11-1383 


QTVRGetVisible 


QT  VRGetV  isible 


Obtains  a  movie's  visibility  state. 

Boolean  QTVRGetVisible  ( 
QTVRInstance  qtvr  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

function  result  A  Bool  ean  value  that  indicates  whether  the  QuickTime  VR  movie 
specified  by  the  qtvr  parameter  is  visible  (TRUE)  or  not  (FALSE). 

Special  Considerations 

This  function  is  valid  only  for  panoramic  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Imaging  Characteristics"  (V-2910) 

See  Also 

Use  QTVRSetVi  sibl  e  (11-1441)  to  set  the  visibility  state  of  a  movie. 


QTVRGetVisibleHotSpots 


Obtains  a  list  of  the  currently  visible  hot  spots  in  a  QuickTime  VR  movie. 

UInt32  QTVRGetVisibleHotSpots  ( 

QTVRInstance  qtvr, 

Handl e  hotSpots  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

hotSpots 

On  entry,  a  valid  handle  to  a  block  of  memory.  On  return,  that  block  of  memory 
is  filled  with  a  list  of  the  IDs  of  the  visible  hot  spots  in  the  specified  QuickTime 
VR  movie.  If  necessary,  the  handle  is  resized  to  hold  all  the  hot  spot  IDs. 
Accordingly,  the  handle  must  be  unlocked  at  the  time  you  call  this  function. 


11-1384 


Inside  QuickTime:  Function  l-Q 


QTVRGetVRWorld 


function  result  The  number  of  hot  spot  IDs  returned  though  the  hotSpots  parameter. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Hot  Spots"  (V-2906) 


QTVRGetVRWorld 


Obtains  the  VR  world  atom  container  for  a  movie. 

OSErr  QTVRGetVRWorld  ( 

QTVRInstance  qtvr, 

QTAtomContai ner  *VRWorld  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRI instance  (11-1373). 

VRWorl  d 

On  return,  a  pointer  to  an  atom  container  that  contains  information  about  the 
specified  movie. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns,  in  the  VRWorl  d  parameter,  a  pointer  to  an  atom  container  that 
contains  general  scene  information  about  the  QuickTime  VR  movie  specified  by  the 
qtvr  parameter,  as  well  as  a  list  of  all  the  nodes  in  that  movie.  You  can  use  the 
QuickTime  atom  functions  to  extract  atoms  from  that  container. 

Special  Considerations 

The  VR  world  atom  container  returned  by  this  function  is  a  copy  of  the  atom 
container  maintained  internally  by  the  QuickTime  VR  Manager.  You  should 
dispose  of  the  VR  world  atom  container  by  calling  QTDi  sposeAtomContai  ner  (11-1164) 
when  you're  finished  using  it. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Getting  Scene  and  Node  Information"  (V-2906) 


Inside  QuickTime:  Function  l-Q 
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QTVRGoToNodelD 


Related  Java  Methods 

qui ckti me . std .movi es . AtomContai ner . f romQTVRInstanceWorl d( ) , 
qui ckti me . vr . QTVRI instance .getVRWorld( ) 


QTVRGoToNodelD 


Sets  the  current  node  of  a  movie. 

OSErr  QTVRGoToNodelD  ( 
QTVRInstance  qtvr, 

UInt32  nodelD  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
nodelD 

The  ID  of  the  node  you  want  to  be  the  current  node.  The  QuickTime  VR 
Manager  defines  several  constants  (see  below)  for  specific  nodes. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

nodelD  Constants 

kQTVRCurrentNode 

The  current  node.  Moving  to  the  current  node  has  the  effect  of  restoring  the 
default  view  in  that  node. 

kQTVRPrevi ousNode 

The  previous  node.  The  QuickTime  VR  Manager  maintains  a  list  (which  is 
limited  only  by  the  available  memory)  of  the  nodes  visited. 
kQTVRDefaul tNode 

The  default  node  in  the  scene. 

Special  Considerations 

Setting  the  current  node  also  sets  the  pan,  tilt,  and  field  of  view  of  the  new  current 
node  to  their  default  values.  As  a  result,  if  you  wish  to  set  non-default  angles,  you 
should  call  this  function  before  you  call  QTVRSetPanAngl  e  (11-1431), 

QTVRSetT i  1  tAngl  e  (11-1434),  or  QTVRSetFi  el  dOfVi  ew  (11-1420). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Getting  Scene  and  Node  Information"  (V-2906) 
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QTVRInstalllnterceptProc 


Related  Java  Methods 

qui cktime . vr . QTVRInstance .  goToNodelDl ) 


See  Also 

Use  QTVRGetCurrentNodelD  (11-1359)  to  get  the  current  node  ID. 


QTVRInstalllnterceptProc 


Installs  or  removes  an  intercept  procedure  for  a  QuickTime  VR  Manager  function. 


OSErr  QTVRInstalllnterceptProc  ( 


QTVRInstance 

QTVRProcSel  ector 

QTVRInterceptUPP 

SInt32 

UInt32 


qtvr , 
sel ector , 
i nterceptProc , 
refCon , 
flags  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

sel ector 

A  selector  (see  below)  that  indicates  which  QuickTime  VR  function  to  intercept, 
i nterceptProc 

A  Universal  Procedure  Pointer  for  a  QTVRInterceptProc  (III— 2130)  callback.  Set 
this  parameter  to  N I L  to  remove  a  previously  installed  intercept  procedure. 
refCon 

A  reference  constant  to  be  passed  to  your  intercept  callback.  Use  this  parameter 
to  point  to  a  data  structure  containing  any  information  your  callback  needs. 

fl  ags 

Unused.  Set  this  parameter  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

selector  Constants 

kQTVRSetPanAngl  eSel  ector 

Intercept  the  QTVRSetPanAngl  e  (11-1431)  function. 
kQTVRSetT i 1 tAngl  eSel  ector 

Intercept  the  QTVRSetT i  1  tAngl  e  (11-1434)  function. 
kQTVRSetFi el dOfVi ewSel  ector 

Intercept  the  QTVRSetFi  el  dOfVi  ew  (11-1420)  function. 
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QTVRInstalllnterceptProc 


kQTVRSetVi ewCenterSel ector 

Intercept  the  QTVRSetVi  ewCenter  (11-1437)  function. 
kQTVRMouseEnterSel ector 

Intercept  the  QTVRMouseEnter  (11-1392)  function. 
kQTVRMo us eWi thinSel ector 

Intercept  the  QTVRMouseWi  thi  n  (11-1401)  function. 
kQTVRMo use  Lea veSel ector 

Intercept  the  QTVRMouseLeave  (11-1394)  function. 
kQTVRMo use Down Sel ector 

Intercept  the  QTVRMouseDown  (11-1391)  function. 
kQTVRMo us eSti 1 1  Down Sel  ector 

Intercept  the  QTVRMouseSti  1 1  Down  (11-1395)  function. 
kQTVRMo  us  eLlpSel  ector 

Intercept  the  QTVRMouseUp  (11-1398)  function. 
kQTVRT  riggerHotSpotSel ector 

Intercept  the  QTVRT ri  ggerHotSpot  (11-1443)  function. 
kQTVRGetHotSpotTypeSel ector 

Intercept  the  QTVRGetHotSpotType  (11-1364)  function. 

Discussion 

This  function  installs  the  procedure  specified  by  the  interceptProc  parameter  as  an 
intercept  procedure  for  the  QuickTime  VR  function  specified  by  the  sel  ector 
parameter  for  the  QuickTime  VR  movie  specified  by  the  qtvr  parameter.  Your 
intercept  procedure  is  called  whenever  QuickTime  VR  is  about  to  execute  the 
function  you  are  intercepting. 

Your  procedure  can  simply  replace  the  intercepted  function,  by  returning  TRUE  in 
the  cancel  parameter;  or  it  can  call  through  to  the  intercepted  function,  by  calling 
QTVRCal  1  InterceptedProc  (11-1336);  or  it  can  allow  the  intercepted  function  to 
execute  when  the  intercept  procedure  returns,  by  returning  FALSE  in  the  cancel 
parameter. 

Here's  an  example  of  using  this  function: 

//  QTVRInstalllnterceptProc  coding  example 
//  See  “Discovering  QuickTime,”  page  398 

QTVRInterceptUPP  My Instal 1 InterceptProcedure  (QTVRInstance  qtvri nstance ) 

{ 

QTVRInterceptUPP  1 pfnlntercept ; 
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QT  VRInteractionN  udge 


} 


I pfnlntercept  =  NewQTVRInterceptProc(MylnterceptProc) ; 

QTVRInstal 1 1 nterceptProcIqtvr instance,  kQTVRSetPanAngl eSel ector , 

1 pfnlntercept,  0,  0); 


return  1 pfnlntercept 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Q  u  i  c  kT i me  V  R . h 

Programming  summary:  "Intercepting  QuickTime  VR  Manager  Routines"  (V-2908) 

Related  Java  Methods 

qui cktime . vr . QTVRInstance . i nstal 1 InterceptProc( ) 


QTVRInteractionNudge 


Translates  the  image  and  displays  the  new  view  or  rotates  the  object  in  a  particular 
direction  and  displays  its  new  appearance. 

OSErr  QTVRInteractionNudge  ( 

QTVRInstance  qtvr, 

QTVRNudgeControl  direction  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

di recti  on 

The  direction  of  the  nudge  (see  below).  The  type  of  adjustment  depends  on  the 
nudge  interaction  mode,  which  you  can  set  with  QTVRSetlnteracti  onProperty 
(11-1425).  If  the  nudge  interaction  mode  is  kQTVRNudgeRotate,  the  action  of 
QTVRInteractionNudge  is  to  rotate  the  object  in  the  specified  direction.  If  the 
nudge  interaction  mode  is  kQTVRNudgeT ransl  ate,  the  action  of 
QTVRInteracti  onNudge  is  to  translate  the  image  in  the  specified  direction.  If  the 
nudge  interaction  mode  is  kQTVRNudgeSameAsMouse,  the  action  of 
QTVRInteracti  onNudge  is  determined  by  the  current  mouse  mode,  which  you 
can  determine  by  calling  QTVRGetCurrentMouseMode  (11-1358). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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QTVRInteractionNudge 


direction  Constants 

kQTVRRi ght 

Nudge  the  current  view  to  the  right. 
kQTVRUpRi ght 

Nudge  the  current  view  up  and  to  the  right. 
kQTVRUp 

Nudge  the  current  view  up. 
kQTVRUpLeft 

Nudge  the  current  view  up  and  to  the  left. 
kQTVRLeft 

Nudge  the  current  view  to  the  left. 
kkQTVRDownLeft 

Nudge  the  current  view  down  and  to  the  left. 
kQTVRDown 

Nudge  the  current  view  down. 
kQTVRDownRi ght 

Nudge  the  current  view  down  and  to  the  right. 

Discussion 

This  function  adjusts  the  current  view  of  the  movie  specified  by  the  qtv  r  parameter 
as  indicated  by  the  di  recti  on  parameter.  The  type  of  adjustment  depends  on  the 
property  setting  for  nudge  interaction  mode,  which  you  can  set  with 
QTVRSetlnteracti  onProperty  (11-1425). 

Special  Considerations 

This  function  is  valid  only  for  object  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Manipulating  Viewing  Angles  and  Zooming"  (V-2905) 

See  Also 

Use  QTVRGetlnteracti  onProperty  (11-1368)  and  QTVRSetlnteracti  onProperty 
(11-1425)  to  get  and  set  the  nudge  mode  and  direction  properties. 
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QTVRMouseDown 


QTVRMouseDown 


Handles  the  user's  clicking  the  mouse  button  when  the  cursor  is  in  a  QuickTime  VR 
movie  for  which  mouse-down  tracking  is  disabled. 


OSErr  QTVRMouseDown 
QTVRInstance 
Poi  nt 
UInt32 
UIntl6 
UInt32 
Wi ndowPtr 


( 

qtvr , 
pt. 
when , 

modi fi ers , 
*hotSpotID, 
w  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
pt 

The  current  location  of  the  cursor,  in  the  local  coordinates  of  the  graphics  world 
specified  by  the  w  parameter. 

when 

The  time,  in  the  number  of  ticks  (sixtieths  of  a  second)  since  system  startup, 
when  the  mouse-down  event  was  posted. 

modi f i ers 

A  short  integer,  each  bit  of  which  is  represented  by  a  constant  (see  below)  that 
provides  information  about  the  state  of  the  modifier  keys  and  the  mouse 
button  at  the  time  the  event  was  posted.  More  than  one  bit  may  be  set. 
hotSpotID 

On  entry,  a  pointer  to  a  long  integer.  On  return,  that  long  integer  contains  the 
ID  of  the  hot  spot  that  lies  beneath  the  specified  point,  or  the  value  0  if  no  hot 
spot  lies  beneath  that  point, 
w 

A  pointer  to  a  graphics  world. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

modifiers  Constants 

acti  veFl  ag 

A  window  is  being  activated  or  a  mouse-down  event  has  caused  a  foreground 
switch. 
btnState 

The  mouse  button  has  been  released. 
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QTVRMouseEnter 


cmdKey 

The  Command  key  is  being  pressed, 
shi ft  Key 

The  Shift  key  is  being  pressed, 
al phaLock 

The  Caps  Lock  key  is  being  pressed 
opti onKey 

The  Option  key  is  being  pressed, 
control  Key 

The  Control  key  is  being  pressed. 

Discussion 

This  function  returns,  in  the  long  integer  pointed  to  by  the  hotSpotID  parameter,  the 
ID  of  the  hot  spot  in  the  QuickTime  VR  movie  specified  by  the  qtvr  parameter  that 
lies  directly  under  the  point  specified  by  the  pt  parameter.  If  no  hot  spot  lies  under 
that  point,  the  long  integer  is  set  to  0.  QTVRMouseDown  also  performs  any  other  tasks 
that  are  typically  performed  when  the  user  clicks  the  mouse  button  when  the  cursor 
is  in  a  QuickTime  VR  movie. 

Special  Considerations 

You  need  to  call  QTVRMouseDown  only  if  you  have  disabled  mouse-down  tracking  for 
the  specified  QuickTime  VR  movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Handling  Events"  (V-2907) 

See  Also 

Use  QTVRSetMouseDownT racki  ng  (11-1429)  to  change  the  mouse-down  tracking  state 
of  a  QuickTime  VR  movie.  Use  QTVRMousellp  (11-1398)  and  QTVRMouseSti  1 1  Down 
(11-1395)  to  handle  the  mouse  button's  being  held  down  and  released. 


QTVRMouseEnter 


Handles  the  user's  moving  the  cursor  into  a  QuickTime  VR  movie  for  which 
mouse-over  tracking  is  disabled. 

OSErr  QTVRMouseEnter  ( 

QTVRInstance  qtvr, 

Point  pt, 
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QTVRMouseEnter 


UInt32  *hotSpotID, 

WindowPtr  w  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRI instance  (11-1373). 
pt 

The  current  location  of  the  cursor,  in  the  local  coordinates  of  the  graphics  world 
specified  by  the  w  parameter. 
hotSpotID 

On  entry,  a  pointer  to  a  long  integer.  On  return,  that  long  integer  contains  the 
ID  of  the  hot  spot  that  lies  beneath  the  specified  point,  or  the  value  0  if  no  hot 
spot  lies  beneath  that  point. 

w 

A  pointer  to  a  graphics  world. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns,  in  the  long  integer  pointed  to  by  the  hotSpotID  parameter,  the 
ID  of  the  hot  spot  in  the  QuickTime  VR  movie  specified  by  the  qtvr  parameter  that 
lies  directly  under  the  point  specified  by  the  pt  parameter.  If  no  hot  spot  lies  under 
that  point,  the  long  integer  is  set  to  0.  QTVRMouseEnter  also  performs  any  other  tasks 
that  are  typically  performed  when  the  user  first  moves  the  cursor  into  a  QuickTime 
VR  movie. 

Special  Considerations 

You  need  to  call  QTVRMouseEnter  only  if  you  have  disabled  mouse-over  tracking  for 
the  specified  QuickTime  VR  movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Handling  Events"  (V-2907) 

See  Also 

Use  QTVRSetMouseOverT racki  ng  (11-1431)  to  change  the  mouse-over  tracking  state  of 
a  QuickTime  VR  movie.  Use  QTVRMouseWi  thi  n  (11-1401)  and  QTVRMouseLeave 
(11-1394)  to  handle  the  cursor's  remaining  in  and  leaving  a  QuickTime  VR  movie. 
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QTVRMouseLeave 


QTVRMouseLeave 


Handles  the  user's  moving  the  cursor  out  of  a  QuickTime  VR  movie  for  which 
mouse-over  tracking  is  disabled. 

OSErr  QTVRMouseLeave  ( 

QTVRInstance  qtvr, 

Point  pt, 

Wi ndowPtr  w  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

pt 

The  current  location  of  the  cursor,  in  the  local  coordinates  of  the  graphics  world 
specified  by  the  w  parameter, 
w 

A  pointer  to  a  graphics  world. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  performs  any  tasks  that  are  typically  performed  when  the  user  moves 
the  cursor  out  of  a  QuickTime  VR  movie. 

Special  Considerations 

You  need  to  call  QTVRMouseLeave  only  if  you  have  disabled  mouse-over  tracking  for 
the  specified  QuickTime  VR  movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Handling  Events"  (V-2907) 

See  Also 

Use  QTVRSetMouseOverT racki  ng  (11-1431)  to  change  the  mouse-over  tracking  state  of 
a  QuickTime  VR  movie.  Use  QTVRMouseEnter  (11-1392)  and  QTVRMouseWi  thi  n 
(11-1401)  to  handle  the  cursor's  entering  and  remaining  in  a  QuickTime  VR  movie. 
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QTVRMouseStillDown 


Handles  the  user's  holding  down  the  mouse  button  while  the  cursor  is  in  a 
QuickTime  VR  movie  for  which  mouse-down  tracking  is  disabled. 

OSErr  QTVRMouseStillDown  ( 

QTVRInstance  qtvr. 

Point  pt, 

UInt32  *hotSpotID, 

WindowPtr  w  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
pt 

The  current  location  of  the  cursor,  in  the  local  coordinates  of  the  graphics  world 
specified  by  the  w  parameter. 

hotSpotID 

On  entry,  a  pointer  to  a  long  integer.  On  return,  that  long  integer  contains  the 
ID  of  the  hot  spot  that  lies  beneath  the  specified  point,  or  the  value  0  if  no  hot 
spot  lies  beneath  that  point, 
w 

A  pointer  to  a  graphics  world. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns,  in  the  long  integer  pointed  to  by  the  hotSpotID  parameter,  the 
ID  of  the  hot  spot  in  the  QuickTime  VR  movie  specified  by  the  qtvr  parameter  that 
lies  directly  under  the  point  specified  by  the  pt  parameter.  If  no  hot  spot  lies  under 
that  point,  the  long  integer  is  set  to  0.  This  function  also  performs  any  other  tasks 
that  are  typically  performed  when  the  user  holds  down  the  mouse  button  when  the 
cursor  is  in  a  QuickTime  VR  movie.  You  should  call  this  function  repeatedly  for  as 
long  as  the  user  holds  down  the  mouse  button  while  the  cursor  is  in  the  specified 
QuickTime  VR  movie. 

Special  Considerations 

You  need  to  call  this  function  only  if  you  have  disabled  mouse-down  tracking  for 
the  specified  QuickTime  VR  movie.  Applications  running  on  operating  systems 
other  than  Mac  OS  should  use  the  extended  form  of  this  function, 

QTVRMouseSti  1 1  DownExtended  (11-1396). 
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QTVRMouseStillDownExtended 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Handling  Events"  (V-2907) 

See  Also 

Use  QTVRSetMouseDownT racki  ng  (11-1429)  to  change  the  mouse-down  tracking  state 
of  a  QuickTime  VR  movie.  Use  QTVRMouseDown  (11-1391)  and  QTVRMouseUp  (11-1398)  to 
handle  the  mouse  button's  being  clicked  and  released. 


QTVRMouseStillDownExtended 


Handles  the  user's  holding  down  the  mouse  button  while  the  cursor  is  in  a 
QuickTime  VR  movie  for  which  mouse-down  tracking  is  disabled. 


OSErr  QTVRMouseSti 
QTVRInstance 
Poi  nt 
UInt32 
Wi ndowPtr 
UInt32 
UIntl6 


DownExtended  ( 

qtvr , 

pt. 

*hotSpotID, 
w , 

when , 

modifiers  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

pt 

The  current  location  of  the  cursor,  in  the  local  coordinates  of  the  graphics  world 
specified  by  the  w  parameter. 

hotSpotID 

On  entry,  a  pointer  to  a  long  integer.  On  return,  that  long  integer  contains  the 
ID  of  the  hot  spot  that  lies  beneath  the  specified  point,  or  the  value  0  if  no  hot 
spot  lies  beneath  that  point. 

w 

A  pointer  to  a  graphics  world. 

when 

The  current  time  as  the  number  of  ticks  (sixtieths  of  a  second)  since  system 
startup. 
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QTVRMouseStillDownExtended 


modi f i ers 

A  short  integer,  each  bit  of  which  is  represented  by  a  constant  (see  below)  that 
provides  information  about  the  state  of  the  modifier  keys  and  the  mouse 
button  at  the  time  the  event  was  posted.  More  than  one  bit  may  be  set. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

modifiers  Constants 

acti  veFl  ag 

A  window  is  being  activated  or  a  mouse-down  event  has  caused  a  foreground 
switch. 

btnState 

The  mouse  button  has  been  released. 
cmdKey 

The  Command  key  is  being  pressed, 
shi ft  Key 

The  Shift  key  is  being  pressed, 
al phaLock 

The  Caps  Lock  key  is  being  pressed 
opti onKey 

The  Option  key  is  being  pressed, 
control  Key 

The  Control  key  is  being  pressed. 

Discussion 

This  function  uses  the  same  intercept  as  QTVRMouseSti  1 1  Down  (11-1395)  but  has  two 
additional  parameters.  Applications  that  intercept  this  function  should  always 
check  the  paramCount  field  to  make  sure  it  is  5  before  using  the  last  two  fields.  You 
should  call  this  function  repeatedly  for  as  long  as  the  user  holds  down  the  mouse 
button  while  the  cursor  is  in  the  specified  QuickTime  VR  movie. 

Special  Considerations 

You  need  to  call  this  function  only  if  you  have  disabled  mouse-down  tracking  for 
the  specified  QuickTime  VR  movie.  Internally,  QuickTime  VR  always  uses  this 
function  instead  of  QTVRMouseSti  1 1  Down.  Developers  implementing  their  own  mouse 
down  tracking  don't  need  to  use  the  extended  version  unless  they  also  intercept  the 
procedure  and  need  the  added  parameters. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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QTVRMouseUp 


Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Handling  Events"  (V-2907) 

See  Also 

Use  QTVRSetMouseDownT racki  ng  (11-1429)  to  change  the  mouse-down  tracking  state 
of  a  QuickTime  VR  movie.  Use  QTVRMouseDown  (11-1391)  and  QTVRMouseUpExtended 
(11-1399)  to  handle  the  mouse  button's  being  clicked  and  released. 


QTVRMouseUp 


Handles  the  user's  releasing  the  mouse  button  while  the  cursor  is  in  a  QuickTime 
VR  movie  for  which  mouse-down  tracking  is  disabled. 


OSErr  QTVRMouseUp 
QTVRInstance 
Poi  nt 
UInt32 
Wi ndowPtr 


qtvr , 
pt. 

*hotSpotID, 
w  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

pt 

The  current  location  of  the  cursor,  in  the  local  coordinates  of  the  graphics  world 
specified  by  the  w  parameter. 

hotSpotID 

On  entry,  a  pointer  to  a  long  integer.  On  return,  that  long  integer  contains  the 
ID  of  the  hot  spot  that  lies  beneath  the  specified  point,  or  the  value  0  if  no  hot 
spot  lies  beneath  that  point. 

w 

A  pointer  to  a  graphics  world. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns,  in  the  long  integer  pointed  to  by  the  hotSpotID  parameter,  the 
ID  of  the  hot  spot  in  the  QuickTime  VR  movie  specified  by  the  qtvr  parameter  that 
lies  directly  under  the  point  specified  by  the  pt  parameter.  If  no  hot  spot  lies  under 
that  point,  the  long  integer  is  set  to  0.  this  function  also  performs  any  other  tasks  that 
are  typically  performed  when  the  user  releases  the  mouse  button  after  clicking  it 
when  the  cursor  is  in  a  QuickTime  VR  movie. 
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QTVRMouseUpExtended 


Special  Considerations 

You  need  to  call  this  function  only  if  you  have  disabled  mouse-down  tracking  for 
the  specified  QuickTime  VR  movie.  Applications  running  on  operating  systems 
other  than  Mac  OS  should  use  the  extended  form  of  this  function, 
QTVRMouseUpExtended  (11-1399). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Handling  Events"  (V-2907) 

See  Also 

Use  QTVRSetMouseDownT racki  ng  (11-1429)  to  change  the  mouse-down  tracking  state 
of  a  QuickTime  VR  movie.  Use  QTVRMouseDown  (11-1391)  and  QTVRMouseSti  1 1  Down 
(11-1395)  to  handle  the  mouse  button's  being  clicked  and  held  down. 


QTVRMouseUpExtended 


Handles  the  user's  releasing  the  mouse  button  while  the  cursor  is  in  a  QuickTime 
VR  movie  for  which  mouse-down  tracking  is  disabled. 


OSErr  QTVRMouseUpExtended  ( 
QTVRInstance  qtvr. 

Point  pt. 


UInt32 
Wi ndowPtr 
UInt32 
UIntl6 


*hotSpotID, 

w, 

when , 

modifiers  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

pt 

The  current  location  of  the  cursor,  in  the  local  coordinates  of  the  graphics  world 
specified  by  the  w  parameter. 

hotSpotID 

On  entry,  a  pointer  to  a  long  integer.  On  return,  that  long  integer  contains  the 
ID  of  the  hot  spot  that  lies  beneath  the  specified  point,  or  the  value  0  if  no  hot 
spot  lies  beneath  that  point. 
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QTVRMouseUpExtended 


w 

A  pointer  to  a  graphics  world. 

when 

The  time,  in  the  number  of  ticks  (sixtieths  of  a  second)  since  system  startup, 
when  the  mouse-up  event  was  posted. 

modi f i ers 

A  short  integer,  each  bit  of  which  is  represented  by  a  constant  (see  below)  that 
provides  information  about  the  state  of  the  modifier  keys  and  the  mouse 
button  at  the  time  the  event  was  posted.  More  than  one  bit  may  be  set. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

modifiers  Constants 

acti  veFl  ag 

A  window  is  being  activated  or  a  mouse-down  event  has  caused  a  foreground 
switch. 
btnState 

The  mouse  button  has  been  released. 
cmdKey 

The  Command  key  is  being  pressed, 
shi ft  Key 

The  Shift  key  is  being  pressed, 
al phaLock 

The  Caps  Lock  key  is  being  pressed 
opti onKey 

The  Option  key  is  being  pressed, 
control  Key 

The  Control  key  is  being  pressed. 

Discussion 

This  function  uses  the  same  intercept  as  the  QTVRMouseUp  function  but  has  two 
additional  parameters.  Applications  that  intercept  this  function  should  always 
check  the  paramCount  field  to  make  sure  it  is  5  before  using  the  last  two  fields. 

Special  Considerations 

You  need  to  call  QTVRMouseUp  (11-1398)  or  this  function  only  if  you  have  disabled 
mouse-down  tracking  for  the  specified  QuickTime  VR  movie.  Internally, 
QuickTime  VR  always  uses  the  this  function  function  instead  of  QTVRMouseUp. 
Developers  implementing  their  own  mouse  down  tracking  don't  need  to  use  the 
extended  version  unless  they  also  intercept  the  procedure  and  need  the  added 
parameters. 
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QTVRMouseWithin 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Handling  Events"  (V-2907) 


QT  VRMouseW  ithin 


Handles  the  user's  leaving  the  cursor  in  a  QuickTime  VR  movie  for  which 
mouse-over  tracking  is  disabled. 


OSErr  QTVRMouseWithin  ( 
QTVRInstance  qtvr. 

Point  pt. 


UInt32  *hotSpotID, 

WindowPtr  w  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
pt 

The  current  location  of  the  cursor,  in  the  local  coordinates  of  the  graphics  world 
specified  by  the  w  parameter. 

hotSpotID 

On  entry,  a  pointer  to  a  long  integer.  On  return,  that  long  integer  contains  the 
ID  of  the  hot  spot  that  lies  beneath  the  specified  point,  or  the  value  0  if  no  hot 
spot  lies  beneath  that  point. 

w 

A  pointer  to  a  graphics  world. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  should  call  this  function  repeatedly  for  as  long  as  the  cursor  remains  in  the 
specified  QuickTime  VR  movie. 

Special  Considerations 

You  need  to  call  QTVRMouseWithin  only  if  you  have  disabled  mouse-over  tracking  for 
the  specified  QuickTime  VR  movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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QTVRNudge 


Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Handling  Events"  (V-2907) 

See  Also 

Use  QTVRSetMouseOverT racki  ng  (11-1431)  to  change  the  mouse-over  tracking  state  of 
a  QuickTime  VR  movie.  Use  QTVRMouseEnter  (11-1392)  and  QTVRMouseLeave  (11-1394) 
to  handle  the  cursor's  entering  and  leaving  a  QuickTime  VR  movie. 


QTVRNudge 


Turns  one  step  in  a  particular  direction  and  displays  the  new  view. 

OSErr  QTVRNudge  ( 

QTVRInstance  qtvr, 

QTVRNudgeControl  direction  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

di recti  on 

The  direction  of  the  nudge  (see  below).  Any  value  of  the  direction  parameter 
that  is  not  predefined  is  mapped  to  the  closest  defined  value. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

direction  Constants 

kQTVRRi ght 

Nudge  the  current  view  to  the  right. 
kQTVRUpRi ght 

Nudge  the  current  view  up  and  to  the  right. 
kQTVRUp 

Nudge  the  current  view  up. 
kQTVRUpLeft 

Nudge  the  current  view  up  and  to  the  left. 
kQTVRLeft 

Nudge  the  current  view  to  the  left. 
kkQTVRDownLeft 

Nudge  the  current  view  down  and  to  the  left. 
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QTVRPanToColumn 


kQTVRDown 

Nudge  the  current  view  down. 
kQTVRDownRi  ght 

Nudge  the  current  view  down  and  to  the  right. 

Discussion 

This  function  adjusts  the  current  view  of  the  movie  specified  by  the  qtvr  parameter 
as  indicated  by  the  direction  parameter.  In  particular,  it  turns  one  step  in  the 
indicated  direction  and  displays  the  new  view.  For  example,  to  move  to  the  next 
view  that  is  right  and  up  from  the  current  view,  set  the  direction  parameter  to 
kQTVRUpRi  ght  (that  is,  pi/4  radians,  or  45  degrees).  For  objects,  if  no  view  is  located 
at  the  adjacent  object  view  defined  by  the  nudge  direction  and  wrapping  is  off  in  the 
desired  direction,  then  this  function  remains  at  the  current  view  and  returns  the 
result  code  constraintReachedErr.  For  objects,  this  function  is  useful  for  changing  to 
an  adjacent  view  without  having  to  know  the  new  pan  and  tilt  angles.  The  direction 
of  the  nudge  is  affected  by  the  current  control  settings. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Q  u  i  c  kTi me V  R . h 

Programming  summary:  "Manipulating  Viewing  Angles  and  Zooming"  (V-2905) 

Related  Java  Methods 

qui cktime . vr . QTVRInstance . nudge ( ) 


See  Also 

Use  QTVRSetPanAngl  e  (11-1431)  and  QTVRSetT i  1  tAngl  e  (11-1434)  to  move  to  a  new 
view  specified  using  pan  and  tilt  angles. 


QTVRPanToColumn 


Obtains  the  column  number  in  the  object  image  array  that  corresponds  to  a  pan 
angle. 

short  QTVRPanToColumn  ( 

QTVRInstance  qtvr, 

float  panAngle  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
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QTVRPtToAngles 


panAngl e 

A  pan  angle. 

function  result  The  zero-based  column  number  in  the  current  object  image  array 
that  corresponds  to  the  pan  angle  specified  by  the  panAngl  e 
parameter 

Special  Considerations 

This  function  is  valid  only  for  object  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Converting  Angles  and  Points"  (V-2911) 

Related  Java  Methods 

qui ckti me . vr . QTVRInstance . panToCol umn ( ) 


QT  VRPtT  o  Angles 

Obtains  the  pan  and  tilt  angles  of  a  point. 

OSErr  QTVRPtToAngles  ( 

QTVRInstance  qtvr. 

Point  pt, 

float  *panAngle, 

f 1  oat  *ti 1 tAngl e  ) ; 

qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

pt 

A  point,  in  the  local  coordinates  of  the  graphics  world  of  the  specified  movie. 
panAngl e 

On  entry,  a  pointer  to  a  floating-point  value.  On  return,  that  value  contains  the 
pan  angle  of  the  specified  point, 
ti 1 tAngl e 

On  entry,  a  pointer  to  a  floating-point  value.  On  return,  that  value  contains  the 
tilt  angle  of  the  specified  point. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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QTVRPtToHotSpotID 


Discussion 

For  a  panorama,  each  point  in  the  current  view  corresponds  to  a  particular  pan  and 
tilt  angle,  with  the  point  at  the  center  of  the  view  corresponding  to  the  panorama's 
current  pan  and  tilt  angle.  This  function  returns,  in  the  floating-point  values  pointed 
to  by  the  panAngl  e  and  ti  1  tAngl  e  parameters,  the  pan  and  tilt  angles  of  the  point 
specified  by  the  pt  parameter. 

Special  Considerations 

This  function  is  valid  only  for  panoramic  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Converting  Angles  and  Points"  (V-2911) 

Related  Java  Methods 

qui cktime . vr . QTVRInstance . pt To PanAngl  e( ) , 
qui cktime . vr . QTVRInstance . ptToTi 1 tAngl e( ) 


QTVRPtToHotSpotID 


Obtains  the  ID  of  the  hot  spot,  if  any,  that  lies  beneath  a  point. 

OSErr  QTVRPtToHotSpotID  ( 

QTVRInstance  qtvr. 

Point  pt, 

UInt32  *hotSpotID  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

pt 

A  point,  in  the  local  coordinates  of  the  graphics  world  of  the  specified  movie. 
hotSpotID 

On  entry,  a  pointer  to  a  long  integer.  On  return,  that  long  integer  contains  the 
ID  of  the  hot  spot  that  lies  beneath  the  specified  point,  or  the  value  0  if  no  hot 
spot  lies  beneath  that  point. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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QTVRRefreshBackBuffer 


Programming  Info 

C  interface  file:  Qui  ckTimeVR.  h 

Programming  summary:  "Managing  Hot  Spots"  (V-2906) 


QTVRRefreshBackBuffer 


Refreshes  the  QTVR  back  buffer. 

OSErr  QTVRRefreshBackBuffer  ( 
QTVRInstance  qtvr, 

UInt32  f 1 ags  )  ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
fl  ags 

Unused.  Set  this  parameter  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  refreshes  some  or  all  of  the  back  buffer  associated  with  the  QuickTime 
VR  movie  specified  by  the  qtvr  parameter  by  reloading  the  appropriate  data  from 
the  diced  frames  in  the  panorama  image  track.  You  can  call  this  function  either  in  a 
back  buffer  imaging  procedure  or  elsewhere  in  your  application.  If  you  call  this 
function  in  a  back  buffer  imaging  procedure,  only  the  current  rectangle  (that  is,  the 
rectangle  specified  by  the  procedure's  drawRect  parameter)  is  refreshed.  If  you  call 
this  function  outside  of  a  back  buffer  imaging  procedure,  all  areas  of  interest 
specified  in  the  most  recent  call  to  QTVRSetBackBufferlmagi  ngProc  (11-1411)  are 
refreshed. 

Special  Considerations 

This  function  is  valid  only  for  panoramic  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTimeVR.  h 

Programming  summary:  "Accessing  Image  Buffers"  (V-2914) 

See  Also 

See  QTVRBackBufferlmagingProc  (III— 2127)  for  information  about  back  buffer 
imaging  procedures. 
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QTVRReplaceCursor 


QTVRReplaceCursor 


Replaces  any  of  the  standard  QuickTime  VR  cursors  with  your  own  custom  cursor. 

OSErr  QTVRReplaceCursor  ( 

QTVRInstance  qtvr, 

QTVRCursorRecord  *cursRecord  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRI instance  (11-1373). 

cursRecord 

A  pointer  to  a  QTVRCursorRecord  (IV-2395)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  replaces  one  or  more  of  the  standard  QuickTime  VR  cursors 
associated  with  the  instance  specified  by  the  qtvr  parameter  with  the  cursors 
specified  in  the  cursor  record  pointed  to  by  the  cursRecord  parameter.  If  the  type 
field  of  the  specified  cursor  record  is  kQTVRUseDef  aul  tCursor,  the  default  cursor  for 
the  given  resource  ID  is  reloaded;  in  this  case,  the  handle  field  of  that  record  should 
be  set  to  NIL. 

Special  Considerations 

This  function  replaces  the  standard  cursors  only  for  the  specified  QuickTime  VR 
movie  instance.  To  replace  the  standard  cursors  for  all  QuickTime  VR  movie 
instances  you  create,  you  need  to  call  this  function  for  each  such  instance. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier.  Note  that  QuickTime  VR  2.1  makes  a  copy  of 
the  cursor  handle  specified  in  the  cursor  record.  The  application  is  responsible  for 
disposing  of  its  own  cursor  handle. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  QuickTime  VR  Movie  Interactions"  (V-2912) 


QTVRRowToTilt 


Obtains  the  tilt  angle  that  corresponds  to  a  row  number  in  a  QTVR  object  image 
array. 

float  QTVRRowToTilt  ( 
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QTVRSetAngularUnits 


QTVRInstance  qtvr, 

short  row  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
row 

A  row  number. 

function  result  The  tilt  angle  that  corresponds  to  the  zero-based  row  number  in  the 
object  image  array  specified  by  the  row  parameter. 

Special  Considerations 

This  function  is  valid  only  for  object  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Converting  Angles  and  Points"  (V-2911) 

Related  Java  Methods 

qui ckti me . vr . QTVRInstance . rowToT i 1 t ( ) 


QTVRSetAngularUnits 


Sets  the  type  of  unit  used  when  specifying  QTVR  angles. 

OSErr  QTVRSetAngui arUni ts  ( 

QTVRInstance  qtvr, 

QTVRAngui arUni ts  units  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

uni  ts 

A  constant  (see  below)  that  indicates  the  type  of  angular  units  to  use. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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QTVRSetAnimationSetting 


units  Constants 

kQTVRDegrees 

Angles  are  specified  using  degrees.  This  is  the  default  type  of  angle 
specification. 

kQTVRRadi ans 

Angles  are  specified  using  radians 

Discussion 

This  function  sets  the  type  of  angular  units  to  be  used  in  all  subsequent  QuickTime 
VR  Manager  calls  for  the  QuickTime  VR  movie  specified  by  the  qtvr  parameter  to 
the  unit  type  specified  by  the  units  parameter. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Converting  Angles  and  Points"  (V-2911) 

Related  Java  Methods 

qui  cktime .  vr .  QTVRInstance .  setAngul  arllni  ts  ( ) 


See  Also 

Use  QTVRGetAngui  arllni  ts  (11-1344)  to  get  the  type  of  angular  unit  used  by  a 
QuickTime  VR  movie. 


QTVRSetAnimationSetting 


Sets  the  state  of  an  animation  setting  for  an  object  node. 

OSErr  QTVRSetAnimationSetting  ( 

QTVRInstance  qtvr, 

QTVRObjectAni mati on Sett i ng  setti ng  , 

Boolean  enable  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
setti ng 

An  animation  setting  (see  below), 
enabl e 

A  Bool  ean  value  that  indicates  whether  the  specified  animation  setting  is  to  be 
enabled  for  the  specified  object  node  (TRUE)  or  disabled  (FALSE). 
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QT  VR  S  et  Animations  etting 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

setting  Constants 

kQTVRPal i ndromeVi ew Frames 

Play  a  back-and-forth  animation  of  the  frames  of  the  current  view.  The  frames 
of  the  current  view  play  with  a  positive  or  negative  frame  rate;  the  frame  rate 
sign  is  switched  each  time  the  view  end  time  (equal  to  the  view  duration)  or  the 
view  start  time  (always  0)  is  reached. 
kQTVRStartFi rstView Frames 

Play  the  frame  animation  starting  with  the  first  frame  in  the  view  (that  is,  at  the 
view  start  time).  This  setting  is  useful  if  a  sound  track  is  associated  by  time  with 
object  views.  Even  if  the  object  view  contains  no  animation,  setting  this  flag 
allows  any  sound  authored  to  play  with  the  view  to  play  from  the  beginning. 
When  this  flag  is  clear,  each  new  object  view  begins  playing  using  the  current 
view  time  of  the  previous  view. 
kQTVRDontLoopVi ew Frames 

Don't  loop  the  frame  animation.  Animation  frames  and  sound  stop  playing 
when  the  view  duration  is  reached. 

kQTVRPl ay E ve ry V i ew Frame 

Play  every  view  frame.  Animation  plays  all  frames  regardless  of  play  rate.  The 
play  rate  is  used  to  adjust  the  duration  in  which  a  frame  appears  but  no  frames 
are  skipped  so  the  rate  is  not  exact.  When  this  property  is  set,  sound  tracks  are 
not  played. 

kQTVRSyncVi ewTo Frame Rate 

Synchronize  the  view  animation  to  the  frame  animation.  When  view  animation 
is  enabled,  the  object  views  play  at  the  same  rate  and  animation  settings  as  the 
frame  animation  rate  and  settings.  This  is  useful  if  animation  must  be 
synchronized  precisely  across  multiple  views  or  a  sound  track  is  to  be  played 
during  view  animation  instead  of  during  frame  animation. 
kQTVRPal i ndromeVi  ews 

Play  a  back-and-forth  animation  of  the  views  of  the  current  node.  When  view 
animation  is  enabled,  the  object  views  play  with  a  positive  or  negative  view 
rate;  the  view  rate  sign  is  switched  each  time  an  object's  pan  equals  the  object's 
minimum  pan  limit  or  the  object's  maximum  pan  limit  (the  first  column  in  a 
row  or  the  last  column  in  a  row,  respectively). 

kQTVRPl ayStreamingVi ews 

When  an  object  movie  is  streaming  in  from  a  network,  this  flag  indicates 
whether  the  frames  corresponding  to  the  row  in  which  the  default  view 
appears  are  to  be  played  as  they  are  loaded. 
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Special  Considerations 

This  function  is  valid  only  for  object  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Object  Nodes"  (V-2909) 

See  Also 

Use  QTVRGetAni mati  onSetti  ng  (11-1344)  to  get  the  current  state  of  an  animation 
setting  for  an  object  node. 


QTVRSetBackBufferlmagingProc 


Installs  or  removes  a  QTVR  back  buffer  imaging  procedure. 


OSErr  QTVRSetBackBufferlmagingProc  ( 


QTVRInstance 

QTVRBackBuf  f  erlmagi  ngllPP 
UIntl6 

QTVRArea Of  Interest 
SInt32 


qtvr , 

backBufferlmagingProc, 
numAreas , 

areasOf Interest[] , 
refCon  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
backBufferlmagingProc 

A  Universal  Procedure  Pointer  for  a  QTVRBackBuf  f  erlmagi  ngProc  (III— 2127) 
callback.  To  remove  a  previously  installed  back  buffer  imaging  procedure,  pass 
NIL. 

numAreas 

The  number  of  area  of  interest  structures  in  the  array  pointed  to  by  the 
areasOf  Interest  parameter. 

areasOf Interest[] 

A  pointer  to  an  array  of  QTVRAreaOf  Interest  (IV-2392)  structures.  Each 
structure  defines  a  rectangular  areas  about  which  you  want  your  back  buffer 
imaging  procedure  to  be  notified.  Your  procedure  is  called  for  each  area  of 
interest  as  it  becomes  visible  or  not  visible.  You  indicate  when  you  want  your 
procedure  to  be  called  for  a  particular  area  of  interest  by  setting  flags  in  the 
flags  field  in  the  corresponding  area  of  interest  structure.  The  width  of  the  area 
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of  interest  is  limited  by  the  size  of  the  back  buffer.  If  the  back  buffer  is  less  than 
the  full  cache  size,  then  the  area  of  interest  can  be  no  wider  than  half  the  size  of 
the  back  buffer.  (For  vertical  cylinder  geometries,  limiting  factor  would  be  the 
height  of  the  buffer.)  For  a  full  cache  back  buffer,  the  width  of  the  area  of 
interest  can  be  the  full  size  of  the  buffer.  If  the  width  limit  is  exceeded,  this 
function  returns  constrai  ntReachedErr. 

refCon 

A  reference  constant.  This  value  is  passed  to  the  specified  back  buffer  imaging 
callback.  Use  this  parameter  to  point  to  a  data  structure  containing  any 
information  your  callback  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  installs  the  procedure  specified  by  the  backBufferlmagingProc 
parameter  as  a  back  buffer  imaging  procedure  for  the  panoramic  node  specified  by 
the  qtvr  parameter.  You  can  use  that  procedure  to  draw  directly  into  the  back 
buffer.  Coordinates  in  the  back  buffer  are  dependent  on  the  current  correction 
mode;  as  a  result,  you  need  to  indicate  the  area  you're  interested  in  drawing  into  by 
specifying  a  pan  angle  and  tilt  angle  to  determine  the  upper-left  comer  of  the  area 
and  a  height  and  width  relative  to  that  comer.  Specifying  a  height  and  width 
instead  of  a  second  pair  of  pan  and  tilt  angles  for  the  bottom-right  coordinate  allows 
the  rectangle  to  wrap  around  the  edge  of  the  panorama. 

Special  Considerations 

This  function  is  valid  only  for  panoramic  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Accessing  Image  Buffers"  (V-2914) 

See  Also 

Use  QTVRSet Prescreen  I magi  ngCompl  eteProc  (11-1432)  to  install  or  remove  a  prescreen 
buffer  imaging  completion  procedure. 


QTVRSetBackBufferPrefs 

Sets  the  resolution,  pixel  format,  and  size  of  the  back  buffer  maintained  internally 
by  QuickTime  VR  for  caching  a  panoramic  image  in  a  particular  pixel  format. 

OSErr  QTVRSetBackBufferPrefs  ( 
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QTVRInstance  qtvr, 

UInt32  geometry, 

UIntl6  resolution, 

UInt32  cachePixel Format , 

SIntl6  cacheSize  ); 

qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
geometry 

The  type  and  orientation  of  the  panorama  data  (see  below), 
resol uti on 

The  desired  image  resolution  (see  below). 
cachePi xel Format 

The  desired  pixel  format  for  the  back  buffer  (see  below). 
cacheSi ze 

The  desired  size  for  the  panorama  back  buffer  (see  below). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

geometry  Constants 

kQTVRUseMovi eGeometry 
Value  is  0. 

kQTVRVerti cal Cyl i nder 

Vertical  cylinder  geometry.  Value  is  '  vcyl  ' . 

resolution  Constants 

kQTVRDef aul tRes 

The  default  resolution  of  the  image. 
kQTVRFul 1  Res 

The  full  resolution  of  the  image. 
kQTV  RH  a  1  f Res 

One-half  the  full  resolution  of  the  image. 
kQTVRQuarterRes 

One-quarter  the  full  resolution  of  the  image. 

cachePixelFormat  Constants 

kl6LE555Pixel Format 

16-bit  LE  RGB  555  (Windows) 
kl6BE565Pixel Format 
16-bit  BE  RGB  565 
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kl6LE565Pi xel Format 
16-bit  LE  RGB  565 
k24BGRPi xel Format 

24-bit  BGR 

k32ARGBPixel Format 
32-bit  ARGB 
k32BGRAPixel Format 

32-bit  BGRA  (Matrox) 
k32ABGRPixel Format 
32-bit  ABGR 
k32RGBAPixel Format 
32-bit  RGBA 

cacheSize  Constants 

kQTVRMi nimumCache 

The  minimum  cache  size  required  to  display  the  specified  VR  movie. 
kQTVRSuggestedCache 

The  suggested  cache  size,  a  cache  large  enough  to  allow  full  zooming  out  of  the 
panorama. 

kQTVRFull Cache 

The  full  cache  size  (that  is,  a  cache  that  is  large  enough  to  fit  the  entire  panorama 
in  memory).  This  is  the  default  cache  size. 

Discussion 

This  function  sets  the  resolution,  pixel  format,  and  size  of  the  panorama  back  buffer 
for  the  movie  specified  by  the  qtvr  parameter  to  the  values  specified  by  the 
resol  uti  on  parameter  an  the  cachePi  xel  Format  and  cacheSi  ze  parameters.  You  can 
specify  a  resolution  that  isn't  contained  in  the  movie  file;  if  you  do  so,  QuickTime 
VR  takes  the  highest  resolution  image  in  the  file  and  reduces  it  to  fit  into  the 
specified  buffer  size.  If  you  specify  an  unsupported  pixel  format,  this  function  may 
return  an  error. 

Special  Considerations 

This  function  is  valid  only  for  panoramic  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  VR  Memory"  (V-2913) 
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See  Also 

Use  QTVRGetAvai  1  abl  eResol  uti  ons  (11-1346)  to  determine  which  resolutions  are 
supported  by  a  node.  Use  QTVRGetBackBufferMemlnfo  (11-1347)  to  determine  the 
memory  requirements  for  the  preferred  settings. 


QTVRSetConstraints 


Sets  the  constraints  of  a  VR  movie. 


OSErr  QTVRSetConstraints  ( 
QTVRInstance  qtvr, 

U I  n  1 1 6  kind, 

float  minValue, 

float  maxValue  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

ki  nd 

The  type  of  constraint  to  set  (see  below), 
mi nVal ue 

A  floating-point  value  that  contains  the  desired  minimum  constraint  of  the 
specified  type. 

maxVal ue 

A  floating-point  value  that  contains  the  desired  maximum  constraint  of  the 
specified  type. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

kind  Constants 

kQTVRPan 

The  pan  angle.  The  associated  value  is  of  type  f  1  oat. 
kQTVRTilt 

The  tilt  angle.  The  associated  value  is  of  type  float. 
kQTVRFi  el  dOfVi  ew 

The  field  of  view.  The  associated  value  is  of  type  f  1  oat. 

Discussion 

This  function  sets  the  minimum  and  maximum  constraints  of  the  type  specified  by 
the  kind  parameter  to  the  values  specified  by  the  minValue  and  maxVal  ue  parameters. 
Note  that  when  you  want  to  specify  a  pan  angle  constraint,  the  mi  nVal  ue  and 
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m a  x  V  a  1  u  e  parameters  should  be  specified  so  that  a  clockwise  sweep  from  m  i  n  V  a  1  u  e  to 
maxVal  ue  selects  the  desired  angular  expanse.  For  example,  to  constrain  panning  in 
the  90-degree  expanse  that  spreads  out  45  degrees  on  each  side  of  the  pan  angle  0 
degrees,  you  should  set  the  mi  nVal  ue  parameter  to  315  degrees  and  the  maxVal  ue 
parameter  to  45  degrees.  Similarly,  to  constrain  panning  in  the  remaining 
270-degree  expanse,  you  should  set  the  mi  nVal  ue  parameter  to  45  degrees  and  the 
maxVal  ue  parameter  to  315  degrees. 

Special  Considerations 

The  values  passed  to  this  function  are  unaffected  by  the  current  control  settings. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Determining  Viewing  Limits  and  Constraints"  (V-2912) 

Related  Java  Methods 

qui  ckti  me .  vr .  QTVRInstance  .setConstraintsO 


See  Also 

Use  QTVRGetConstrai  nts  (11-1352)  to  get  a  movie's  minimum  and  maximum 
constraints. 


QTVRSetControlSetting 


Sets  the  state  of  a  control  setting  for  a  QTVR  object  node. 

OSErr  QTVRSetControlSetting  ( 

QTVRInstance  qtvr, 

QTVRControl Setti ng  setting, 

Bool ean  enabl e  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

setti ng 

A  control  setting  (see  below), 
enabl e 

A  Bool  ean  value  that  indicates  whether  the  specified  control  setting  is  to  be 
enabled  for  the  specified  object  node  (TRUE)  or  disabled  (FALSE). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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setting  Constants 

kQTVRWrapPan 

Set  wrapping  during  panning.  When  this  control  setting  is  enabled,  the  user  can 
wrap  around  from  the  current  pan  constraint  maximum  value  to  the  pan 
constraint  minimum  value  (or  vice  versa)  using  the  mouse  or  arrow  keys.  In 
addition,  calling  QTVRSetPanAngl  e  (11-1431)  with  a  pan  angle  that  is  either  less 
than  or  greater  than  the  current  pan  constraints  results  in  a  pan  angle  within  the 
current  pan  constraints.  Similarly,  QTVRWrapAndConstrai  n  (11-1446)  returnsapan 
angle  within  the  current  pan  constraints,  and  QTVRNudge  (11-1402)  wraps  views 
after  it  reaches  the  maximum  or  minimum  constraint  value. 

When  this  control  setting  is  disabled,  the  user  cannot  wrap  around  from  the 
current  pan  constraint  maximum  value  to  the  pan  constraint  minimum  value 
(or  vice  versa)  using  the  mouse  or  arrow  keys.  In  addition,  QTVRSetPanAngl  e 
returns  the  result  code  constraintReachedErr  when  passed  a  pan  angle  that  is 
either  less  than  or  greater  than  the  current  pan  constraints.  Similarly, 
QTVRWrapAndConstrai  n  returns  a  pan  angle  that  is  one  of  the  current  pan 
constraints,  and  QTVRNudge  returns  the  result  code  constrai  ntReachedErr  when 
it  reaches  the  maximum  or  minimum  constraint  value. 

Note  that  a  view  animation  stops  when  a  constraint  is  reached  unless 
palindrome  view  animation  or  wrapping  during  panning  is  enabled. 

kQTVRWrapTi  1 1 

Set  wrapping  during  tilting.  When  this  control  setting  is  enabled,  the  user  can 
wrap  around  from  the  current  tilt  constraint  maximum  value  to  the  tilt 
constraint  minimum  value  (or  vice  versa)  using  the  mouse  or  arrow  keys.  In 
addition,  calling  QTVRSetTi  1  tAngl  e  (11-1434)  with  a  tilt  angle  that  is  either  less 
than  or  greater  than  the  current  tilt  constraints  results  in  a  tilt  angle  within  the 
current  tilt  constraints.  Similarly,  QTVRWrapAndConstrai  n  (11-1446)  returns  a  tilt 
angle  within  the  current  tilt  constraints,  and  QTVRNudge  (11-1402)  wraps  views 
after  it  reaches  the  maximum  or  minimum  constraint  value. 

When  this  control  setting  is  disabled,  the  user  cannot  wrap  around  from  the 
current  tilt  constraint  maximum  value  to  the  tilt  constraint  minimum  value  (or 
vice  versa)  using  the  mouse  or  arrow  keys.  In  addition,  the  QTVRSetT i  1  tAngl  e 
function  returns  the  result  code  constrai  ntReachedErr  when  passed  a  tilt  angle 
that  is  either  less  than  or  greater  than  the  current  tilt  constraints.  Similarly, 
QTVRWrapAndConstrai  n  returns  a  tilt  angle  that  is  one  of  the  current  tilt 
constraints,  and  QTVRNudge  returns  the  result  code  constrai  ntReachedErr  when 
it  reaches  the  maximum  or  minimum  constraint  value. 
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kQTVRCanZoom 

Set  zooming  to  be  active.  When  this  control  setting  is  enabled,  the  user  can 
change  the  current  field  of  view  using  the  zoom-in  and  zoom-out  keys  on  the 
keyboard  (or  using  the  VR  controller  buttons).  In  addition,  you  can  use 
QTVRSetFi  el  dOfVi  ew  (11-1420)  to  alter  the  current  field  of  view.  Similarly, 
QTVRWrapAndConstrai  n  (11-1446)  returns  a  field  of  view  within  the  current  field 
of  view  constraints. 

When  this  control  is  disabled,  the  user  cannot  change  the  current  field  of  view 
using  the  zoom-in  and  zoom-out  keys  on  the  keyboard  (or  using  the  VR 
controller  buttons).  In  addition,  the  QTVRSetFi  el  dOfVi  ew  function  returns  the 
result  code  constrai  ntReachedErr  and  doesn't  change  the  field  of  view. 
Similarly,  QTVRWrapAndConstrai  n  returns  the  current  field  of  view 
kQTVRReverseHControl 

Reverse  the  direction  of  the  horizontal  control.  When  this  control  setting  is 
enabled,  the  user  can  change  an  object's  horizontal  view  using  the  mouse  or  the 
keyboard  arrows  with  reversed  values  for  mouse  horizontal  motion  and 
keyboard  left  and  right  arrows.  (In  other  words,  the  left  arrow  key  causes 
panning  to  the  right,  and  moving  the  mouse  right  causes  panning  to  the  left.) 
Similarly,  QTVRNudge  (11-1402)  nudges  left  when  you  pass  the  value  0  and  right 
when  you  pass  the  value  180.  This  control  setting  is  useful  when  an  object's 
frames  have  been  authored  in  reverse  order 

kQTVRReverseVControl 

Reverse  the  direction  of  the  vertical  control.  When  this  control  setting  is 
enabled,  the  user  can  change  an  object's  vertical  view  using  the  mouse  or  the 
keyboard  arrows  with  reversed  values  for  mouse  vertical  motion  and  keyboard 
up  and  down  arrows.  (In  other  words,  the  up  arrow  key  causes  tilting  down, 
and  moving  the  mouse  down  causes  tilting  up.)  Similarly,  QTVRNudge  (11-1402) 
nudges  up  when  you  pass  the  value  270  and  down  when  you  pass  the  value  90. 
This  control  setting  is  useful  when  an  object's  frames  have  been  authored  in 
reverse  order. 
kQTVRSwapHVControl 

Exchange  the  horizontal  and  vertical  controls.  When  this  setting  is  enabled,  the 
user  can  pan  left  using  the  up  arrow  key  and  tilt  up  using  the  left  arrow  key. 
Similarly,  QTVRNudge  (11-1402)  nudges  up  when  you  pass  the  value  180  and 
down  when  you  pass  the  value  0.  This  control  setting  is  useful  if  an  object  is  a 
single-row  or  multirow  movie  containing  vertically  changing  images.  This  is 
especially  useful  when  enabling  view  animation  for  an  object  with  animating 
vertical  changes  in  view  (because  objects  will  animate  only  along  rows,  not 
along  columns). 
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kQTVRT  ransl ati on 

Set  translation  to  be  active.  When  this  setting  is  enabled,  the  user  can  translate 
using  the  mouse  when  either  the  translation  key  is  held  down  or  the  controller 
translation  mode  button  is  toggled  on.  In  addition,  you  can  use 
QTVRSetVi  ewCenter  (11-1437)  to  set  a  horizontal  and  vertical  position  in  the 
current  display  coordinate  system.  When  this  setting  is  disabled, 
QTVRWrapAndConstrai  n  (11-1446)  always  returns  the  current  view  center,  and 
QTVRSetVi  ewCenter  (11-1437)  returns  the  result  code  constrai  ntReachedErr  and 
doesn't  change  the  current  view  center. 

Special  Considerations 

This  function  is  valid  only  for  object  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Object  Nodes"  (V-2909) 

See  Also 

Use  QTVRGetControl  Setti  ng  (11-1355)  to  get  the  current  state  of  a  control  setting  for 
an  object  node. 


QTVRSetEnteringNodeProc 


Installs  or  removes  a  node-entering  procedure. 

OSErr  QTVRSetEnteringNodeProc  ( 

QTVRInstance  qtvr, 

QTVREnteri  ngNodellPP  enteringNodeProc, 
SInt32  refCon, 

UInt32  flags  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

enteri ngNodeProc 

A  Universal  Procedure  Pointer  for  a  QTVREnteri  ngNodeProc  (III— 2128)  callback. 
To  remove  a  previously  installed  QTVREnteri  ngNodeProc  callback,  set 
enteringNodeProc  to  NIL. 
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refCon 

A  reference  constant.  This  value  is  passed  to  the  specified  node-entering 
callback.  Use  this  parameter  to  point  to  a  data  structure  containing  any 
information  your  callback  needs, 
fl  ags 

Unused.  Set  this  parameter  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  installs  the  procedure  specified  by  the  enter  ingNodeProc  parameter  as 
a  node-entering  procedure  for  the  QuickTime  VR  movie  specified  by  the  qtvr 
parameter.  Your  procedure  is  called  whenever  a  node  is  entered  (either  in  response 
to  user  actions  or  in  response  to  QuickTime  VR  Manager  functions  that  change 
nodes).  The  reference  constant  specified  by  the  refCon  parameter  is  passed 
unchanged  to  that  node-entering  procedure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  QuickTime  VR  Movie  Interactions"  (V-2912) 

Related  Java  Methods 

qui ckti me . vr . QTVRInstance .setEnteringNodeProct ) , 
qui ckti me . vr . QTVRInstance . remove Enteri ngNodeProct ) 


See  Also 

Use  QTVRSetLeavi  ngNodeProc  (11-1428)  to  install  or  remove  a  node-leaving 
procedure. 


QTVRSetFieldOfView 


Sets  the  vertical  field  of  view  of  a  QuickTime  VR  movie. 

OSErr  QTVRSetFieldOfView  ( 

QTVRInstance  qtvr, 

f 1  oat  f i el dOfVi ew  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
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fi  el  dOfVi ew 

The  desired  vertical  field  of  view  for  the  specified  movie.  This  value  is 
constrained  by  the  maximum  field  of  view  of  the  movie.  Values  that  lie  outside 
that  limit  are  clipped  to  the  maximum.  Pan  and  tilt  angle  values  are  also  clipped 
if,  when  combined  with  the  current  field  of  view,  they  would  cause  an  image  to 
lie  outside  the  current  constraints. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error.  If  the 
control  setting  kQTVRCanZoom  is  disabled,  the  field  of  view  is 
unchanged  and  this  function  returns  the  result  code 
constrai  nt  Reached  Err.  You  can  use  QTVRSetControl  Setting  (11-1416) 
to  control  the  setting  of  kQTVRCanZoom. 

Special  Considerations 

The  pan  and  tilt  angles  are  subject  to  the  current  pan  and  tilt  range  constraints,  as 
imposed  by  the  viewing  limits  and  the  current  field  of  view.  Accordingly,  if  you 
want  to  change  the  field  of  view,  you  should  do  so  before  adjusting  the  pan  or  tilt 
angles.  Otherwise,  the  pan  and  tilt  angles  are  clipped  against  the  current  field  of 
view,  which  may  result  in  an  incorrect  view  when  you  alter  the  field  of  view. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Manipulating  Viewing  Angles  and  Zooming"  (V-2905) 

Related  Java  Methods 

qui cktime . vr . QTVRInstance . set Fi el dOfVi ew( ) 


See  Also 

Use  QTVRGetFi  el  dOfVi  ew  (11-1360)  to  get  the  vertical  field  of  view  of  a  QuickTime  VR 
movie. 


QTVRSetFrameRate 


Sets  the  frame  rate  of  an  object  node. 

OSErr  QTVRSetFrameRate  ( 
QTVRInstance  qtvr, 

float  rate  ); 
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qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

rate 

The  desired  frame  rate  of  the  specified  movie.  A  frame  rate  is  a  floating-point 
value  in  the  range  from  -100.0  to  +100.0.  Positive  values  indicate  forward  rates, 
and  negative  values  indicate  reverse  rates.  Set  this  parameter  to  0  to  stop  the 
movie.  If  the  value  specified  lies  outside  the  valid  range,  this  function  returns 
the  result  code  constrai  ntReachedErr  and  sets  the  frame  rate  to  the  nearest 
constraint. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  most  useful  when  an  object  is  being  viewed  with  a  looping 
animation.  (The  current  view  of  the  object  may  contain  frames  that  are  played  in  a 
loop,  as  specified  by  the  file  format.)  You  can  use  this  function  to  change  the  frame 
rate  of  the  loop. 

Special  Considerations 

This  function  is  valid  only  for  object  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Object  Nodes"  (V-2909) 

See  Also 

Use  QTVRGetFrameRate  (11-1362)  to  get  the  frame  rate  of  an  object  node. 


QTVRSetlmagingProperty 

Sets  the  value  of  an  imaging  property  of  a  movie. 

OSErr  QTVRSetlmagingProperty  ( 

QTVRInstance  qtvr, 

QTVRImagi ngMode  i magi ngMode , 

UInt32  i magi ngProperty , 

SInt32  propertyVal ue  ); 
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qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRI instance  (11-1373). 
i magi ngMode 

An  imaging  mode  (see  below), 
i magi ngProperty 

An  imaging  property  (see  below). 
propertyVal ue 

The  desired  value  for  the  specified  imaging  property  for  the  specified  mode. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

imagingMode  Constants 

kQTVRStati c 

The  panorama  is  static 
kQTVRMoti on 

The  panorama  is  in  motion;  that  is,  an  action  such  as  panning  or  zooming  is 
occurring. 
kQTVRAll Modes 

All  currently  defined  imaging  modes.  You  can  specify  this  imaging  mode  when 
calling  QTVRSetlmagi  ngProperty  (11-1422)  to  assign  a  value  to  a  particular 
imaging  property  for  all  imaging  modes.  You  can  also  use  this  imaging  mode 
in  the  imagingMode  field  of  a  QTVRPanoImagi  ngAtom  (IV-2398)  structure  to  indicate 
a  default  value  for  a  particular  imaging  property  for  all  imaging  modes. 

imagingProperty  Constants 

kQTVRImagi ngCor recti  on 

The  correction  mode  property  (see  below).  This  property  determines  the  type 
of  image  correction  to  be  applied  when  imaging  a  panoramic  view. 

kQTVRImagi ngQual i ty 

The  imaging  quality  property  (see  below).  This  property  determines  the  quality 
of  the  output  image. 

kQTVRImagi ngDi rectDraw 

The  direct-drawing  property.  This  property  determines  the  immediate 
destination  of  an  image.  The  value  of  this  property  (as  specified  by  the 
propertyVal  ue  parameter)  is  interpreted  as  a  Bool  ean  value.  If  the  value  is  TRUE, 
then  images  are  computed  and  drawn  directly  to  the  final  destination  without 
first  being  drawn  in  the  prescreen  buffer  maintained  by  QuickTime  VR.  This 
value  provides  the  fastest  overall  frame  rate  but  may  result  in  relatively  slower 
individual  frame  drawing  for  high-quality,  high-resolution  images  on  lower 
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performance  systems.  If  the  value  of  this  property  is  FALSE,  then  images  are 
computed  and  drawn  first  into  the  prescreen  buffer  and  then  to  the  final 
destination.  This  value  provides  the  shortest  imaging  time  for  each  individual 
frame  but  results  in  a  reduced  overall  frame  rate. 

Note  that  the  kQTVRImagi  ngDi  rectDraw  property  cannot  always  be  supported. 
During  updates,  QuickTime  VR's  warping  engine  might  ignore  a  value  of  TRU  E 
and  draw  the  image  first  into  the  prescreen  buffer  and  then  into  the  final 
destination 

kQTVRImagi ngCurrentMode 

The  current  imaging  mode  property.  When  you  pass  this  property  selector  to 
QTVRGetlmagi  ngProperty  (11-1365),  it  returns,  in  the  propertyVal  ue  parameter, 
the  current  imaging  mode  (that  is,  either  kQTVRStati  c  or  kQTVRMoti  on).  If  the 
kQTVRImagi  ngDef aul  tVal  ue  bit  is  set,  the  default  imaging  mode  is  returned.  You 
can  get  but  not  set  the  value  of  this  property.  You  might  want  to  determine  the 
current  imaging  mode  in  an  imaging  callback  procedure  if  what  you  draw 
depends  on  the  current  imaging  mode. 

kQTVRImagi ngDefaultValue 

The  default  value  specifier.  You  can  OR  this  value  with  any  of  the  imaging 
property  types  to  get  or  set  the  default  value  of  that  property  type 

kQTVRImagingCorrection  Constants 

kQTVRNoCorrecti on 

Apply  no  warping.  The  source  panorama  is  reproduced  directly,  with  no  image 
correction. 

kQTVRParti al Correction 

Apply  one-dimensional  (horizontal)  warping.  This  kind  of  correction  is  often 
sufficient,  especially  for  outdoor  scenes. 

kQTVRFul 1  Correction 

Apply  two-dimensional  warping.  This  correction  mode  produces  images  in 
correct  perspective  from  the  source  panorama. 

kQTVRImagingQuality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 

codecNormal Qual i ty 

Image  reproduction  of  normal  quality. 
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codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 
codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field. 

Discussion 

Default  values  for  all  imaging  properties  can  be  contained  in  a  QuickTime  VR 
movie  file.  If  no  defaults  are  specified  in  a  movie  file,  the  QuickTime  VR  Manager 
uses  these  values:  for  static  mode,  the  kQTVRImagi  ngQual  i  ty  property  is 
codecHi  ghQual  i  ty  and  kQTVRImagi  ngDi  rectDraw  is  TRUE;  for  motion  mode,  the 
kQTVRImagi  ngQual  i  ty  property  is  codecLowQual  i  ty  and  kQTVRImagi  ngDi  rectDraw  is 
TRUE.  The  default  correction  mode  is  kQTVRFul  1  Cor  recti  on  for  both  static  and  motion 
imaging  modes.  Note  that  it  would  look  strange  to  have  one  correction  mode  for 
static  imaging  and  a  different  correction  mode  for  motion  imaging.  As  a  result,  you 
should  typically  set  the  i  magi  ngMode  parameter  to  kQTVRAl  1  Modes  when  setting  a 
property  of  type  kQTVRImagi  ngCorrecti  on. 

Special  Considerations 

This  function  is  valid  only  for  panoramic  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Imaging  Characteristics"  (V-2910) 

Related  Java  Methods 

qui cktime . vr . QTVRInstance . set  I magi ng Property ( ) 


See  Also 

Use  QTVRGetlmagi  ngProperty  (11-1365)  to  get  an  imaging  property. 


QTVRSetlnteractionProperty 


Sets  the  value  of  an  interaction  property. 

OSErr  QTVRSetlnteractionProperty  ( 
QTVRInstance  qtvr, 

UInt32  property, 

void  *value  ); 
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qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
property 

An  interaction  property  type  (see  below), 
val  ue 

The  desired  value  of  the  specified  interaction  property. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

property  Constants 

kQTVRInteracti onMouseCl 1 ckHysteresi s 

The  value  parameter  is  interpreted  as  an  unsigned  short  integer  that  represents 
the  mouse-click  hysteresis,  the  distance,  in  pixels,  from  the  location  of  a 
mouse-down  event  to  the  limit  within  which  the  cursor  is  considered  not  to 
have  moved.  In  other  words,  the  cursor  can  move  that  many  pixels  during  a 
mouse  click  and  still  have  the  event  considered  a  click.  The  default  mouse-click 
hysteresis  value  is  2.  This  property  is  valid  for  panoramas  only. 
kQTVRInteracti onMouseCl i ckTimeout 

The  value  parameter  is  interpreted  as  an  unsigned  long  integer  that  represents 
the  mouse-click  timeout,  the  number  of  ticks  after  which  a  mouse  click  times 
out  and  is  automatically  switched  from  a  hot  spot  selection  into  a  pan.  The 
default  mouse-click  timeout  value  is  30  ticks  (one-half  second).  This  property  is 
valid  for  panoramas  only. 

kQTVRInteracti onPanTiltSpeed 

The  panning  and  tilting  speed.  The  value  parameter  is  interpreted  as  an 
unsigned  long  integer  that  represents  the  relative  speed  of  panning  and  tilting. 
This  integer  should  be  from  1  (the  slowest  speed)  through  10  (the  fastest  speed); 
the  default  panning  and  tilting  speed  is  5.  This  property  is  valid  only  for 
panoramas. 

kQTVRInteracti onZoomSpeed 

The  value  parameter  is  interpreted  as  an  unsigned  long  integer  that  represents 
the  zooming  speed,  the  relative  speed  of  zooming  in  and  out.  This  integer 
should  be  from  1  (the  slowest  speed)  through  10  (the  fastest  speed);  the  default 
zooming  speed  is  5.  This  property  is  valid  for  both  objects  and  panoramas. 
kQTVRInteracti onTransl ateOnMouseDown 

The  translate  flag.  The  value  parameter  is  interpreted  asaBoolean  value  that 
indicates  whether  translate  mode  is  enabled  (true)  or  disabled  (false).  When 
translate  mode  is  enabled,  the  user  can  no  longer  pan  or  tilt  using  the  mouse; 
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instead,  dragging  the  cursor  causes  the  object  to  translate.  The  default  translate 
flag  value  is  false.  This  property  is  valid  for  objects  only. 

kQTVRInteracti onMouseMoti onScal e 

The  value  parameter  is  interpreted  as  a  pointer  to  a  floating-point  number  that 
represents  the  mouse-motion  scale,  the  number  of  degrees  or  radians  that  an 
object  or  panorama  is  panned  or  tilted  when  the  cursor  is  dragged  the  entire 
width  of  the  object  bounding  box.  The  default  value  is  180.0.  This  property  is 
valid  for  objects  only. 

kQTVRInteracti onNudgeMode 

This  parameter  lets  you  set  the  QuickTime  VR  nudge  mode  (see  below)  to  either 
rotate,  translate,  or  be  the  same  as  the  current  mouse  mode. 

Nudge  Mode  Constants 

kQTVRNudgeRotate 

Set  the  nudge  mode  to  rotate  the  object. 
kQTVRNudgeT ransl  ate 

Set  the  nudge  mode  to  translate  the  image. 
kQTVRNudgeSameAs Mouse 

Set  the  nudge  mode  to  the  same  as  the  current  mouse  mode,  which  you  can 
determine  by  calling  QTVRGetCurrentMouseMode  (11-1358). 

Discussion 

This  function  sets  the  value  of  the  interaction  property  of  the  type  specified  by  the 
property  parameter  for  the  movie  specified  by  the  qtvr  parameter  to  the  value 
specified  by  the  value  parameter.  For  types  that  occupy  32  or  fewer  bits  of  memory, 
you  pass  the  desired  value  itself  (cast  to  a  voi  d*  type)  in  the  value  parameter.  For 
structures  and  floating-point  values,  you  must  pass  a  pointer  to  the  desired  value  in 
the  value  parameter.  Note  that  floating-point  values  are  usually  stored  as  32-bit 
values,  but  compilers  differ  in  how  they  pass  floating-point  values  as  parameters; 
as  a  result,  this  function  demands  that  floating-point  values  always  be  passed  by 
reference. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  QuickTime  VR  Movie  Interactions"  (V-2912) 

See  Also 

Use  QTVRGetlnteracti  onProperty  (11-1368)  to  get  an  interaction  property. 
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QTVRSetLeavingNodeProc 


Installs  or  removes  a  node-leaving  procedure. 

OSErr  QTVRSetLeavingNodeProc  ( 

QTVRInstance  qtvr, 

QTVRLeavi ngNodeUPP  leavingNodeProc, 
SInt32  refCon, 

UInt32  f 1 ags  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

1 eavi ngNodeProc 

A  Universal  Procedure  Pointer  for  a  QTVRLeavi  ngNodeProc  (III— 2130)  callback. 
To  remove  a  previously  installed  QTVRLeavi  ngNodeProc  callback,  set 
leavingNodeProc  to  NIL. 

refCon 

A  reference  constant.  This  value  is  passed  to  the  specified  node-leaving 
callback.  Use  this  parameter  to  point  to  a  data  structure  containing  any 
information  your  callback  needs, 
fl  ags 

Unused.  Set  this  parameter  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  installs  the  procedure  specified  by  the  leavingNodeProc  parameter  as 
a  node-leaving  procedure  for  the  QuickTime  VR  movie  specified  by  the  qtvr 
parameter.  Your  procedure  is  called  whenever  a  node  is  left  (either  in  response  to 
user  actions  or  in  response  to  QuickTime  VR  Manager  functions  that  change  nodes). 
The  reference  constant  specified  by  the  refCon  parameter  is  passed  unchanged  to 
that  node-leaving  procedure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  QuickTime  VR  Movie  Interactions"  (V-2912) 

Related  Java  Methods 

qui ckti me . vr . QTVRInstance .set LeavingNodeProc! ) , 
qui ckti me . vr . QTVRInstance . removeLeavi ngNodeProc!) 
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See  Also 

Use  QTVRSetEnteri  ngNodeProc  (11-1419)  to  install  or  remove  a  node-entering 
procedure. 


QT  VRSetMouseDownT  racking 


Sets  the  state  of  mouse-down  tracking. 

OSErr  QTVRSetMouseDownTracking  ( 
QTVRInstance  qtvr. 

Boolean  enable  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
enabl e 

A  Bool  ean  value  that  indicates  whether  QuickTime  VR  should  handle 
mouse-down  tracking  for  the  specified  movie  (TRUE)  or  not  (FALSE). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

By  default,  QuickTime  VR  tracks  mouse  clicks  in  a  QuickTime  VR  movie  and 
triggers  hot  spots  as  appropriate.  If  you  disable  mouse-down  tracking  (by  passing 
FALSE  in  the  enabl  e  parameter),  you  must  call  QTVRMouseDown  (11-1391), 

QTVRMouseSti  1 1  Down  (11-1395),  and  QTVRMouseUp  (11-1398)  at  the  appropriate  times  to 
handle  user  actions. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Handling  Events"  (V-2907) 

See  Also 

Use  QTVRGetMouseDownT racki  ng  (11-1370)  to  get  the  current  mouse-down  tracking 
state  of  a  QuickTime  VR  movie. 


QTVRSetMouseOverHotSpotProc 


Installs  or  removes  a  mouse  over  hot  spot  procedure. 
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OSErr  QTVRSetMouseOverHotSpotProc  ( 

QTVRInstance  qtvr, 

QTVRMouseOverHotSpotUPP  mouseOverHotSpotProc, 
SInt32  refCon, 

UInt32  f 1 ags  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
mouseOverHotSpotProc 

A  Universal  Procedure  Pointer  for  a  QTVRMouseOverHotSpotProc  (III— 2131) 
callback.  To  remove  a  previously  installed  QTVRMouseOverHotSpotUPP  callback, 
set  mouseOverHotSpotProc  to  NIL. 
refCon 

A  reference  constant.  This  value  is  passed  to  the  specified  mouse  over  hot  spot 
callback.  Use  this  parameter  to  point  to  a  data  structure  containing  any 
information  your  callback  needs. 

fl  ags 

Unused.  Set  this  parameter  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  installs  the  routine  specified  by  the  mouseOverHotSpotProc  parameter 
as  a  mouse  over  hot  spot  procedure  for  the  QuickTime  VR  movie  specified  by  the 
qtvr  parameter.  Subsequent  user  actions  (such  as  moving  the  cursor  over  an 
enabled  hot  spot  in  that  movie)  cause  the  callback  routine  to  be  executed.  The 
reference  constant  specified  by  the  refCon  parameter  is  passed  unchanged  to  your 
callback  routine. 

Special  Considerations 

Your  mouse  over  hot  spot  procedure  is  called  only  for  enabled  hot  spots. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Hot  Spots"  (V-2906) 

Related  Java  Methods 

quicktime.vr. QTVRInstance. setMouseOverHotSpotProct ) , 
qui ckti me . vr . QTVRInstance . removeMouseOverHotSpotProct ) 
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QTVRSetMouseOverT  racking 


Sets  the  state  of  mouse-over  tracking. 

OSErr  QTVRSetMouseOverTracking  ( 
QTVRInstance  qtvr. 

Boolean  enable  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

enabl e 

A  Boolean  value  that  indicates  whether  QuickTime  VR  should  handle 
mouse-over  tracking  for  the  specified  movie  (TRUE)  or  not  (FALSE). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

By  default,  QuickTime  VR  tracks  mouse  movements  in  a  QuickTime  VR  movie  and 
changes  the  shape  of  the  cursor  as  appropriate.  If  you  disable  mouse-over  tracking 
(bypassing  FALSE  in  the  enabl  e  parameter),  you  must  call  QTVRMouseEnter  (11-1392), 
QTVRMouseWi  t h  1  n  (11-1401),  and  QTVRMouseLeave  (11-1394)  at  the  appropriate  times  to 
handle  user  actions. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Handling  Events"  (V-2907) 

See  Also 

Use  QTVRGetMouseOverT racki  ng  (11-1370)  to  get  the  current  mouse-over  tracking 
state  of  a  QuickTime  VR  movie. 


QTVRSetPanAngle 


Sets  the  pan  angle  of  a  QuickTime  VR  movie. 

OSErr  QTVRSetPanAngle  ( 

QTVRInstance  qtvr, 

float  panAngle  ); 
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qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
panAngl e 

The  desired  pan  angle  of  the  specified  movie.  This  value  is  constrained  by  the 
maximum  and  minimum  pan  angles  of  the  movie.  If  the  angle  falls  outside  of 
those  constraints  and  the  control  setting  kQTVRWrapPan  is  disabled,  the  angle  is 
set  to  the  minimum  or  maximum,  whichever  is  closer.  If  wrapping  is  enabled, 
the  pan  angle  is  clipped  to  fall  within  the  constraints.  Pan  angle  values  are  also 
clipped  if  the  requested  pan  angle,  when  combined  with  the  current  tilt  angle 
and  field  of  view,  would  cause  an  image  to  lie  outside  the  current  constraints. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error.  This 
function  returns  the  result  code  constraintReachedErr  if  wrapping  is 
off  and  the  angle  is  set  to  the  minimum  or  maximum  constraint 
value. 


Special  Considerations 

The  pan  and  tilt  angles  are  subject  to  the  current  pan  and  tilt  range  constraints,  as 
imposed  by  the  viewing  limits  and  the  current  field  of  view.  Accordingly,  if  you 
want  to  change  the  field  of  view,  you  should  do  so  before  adjusting  the  pan  or  tilt 
angles.  Otherwise,  the  pan  and  tilt  angles  are  clipped  against  the  current  field  of 
view,  which  may  result  in  an  incorrect  view  when  you  alter  the  field  of  view. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Manipulating  Viewing  Angles  and  Zooming"  (V-2905) 

Related  Java  Methods 

qui ckti me . vr . QTVRInstance .setPan Angle! ) 


See  Also 

Use  QTVRGetPanAngl  e  (11-1373)  to  get  the  pan  angle  of  a  movie.  Use 
QTVRGetVi  ewl  ngLi  mi  ts  (11-1379)  to  get  the  current  viewing  limits  of  a  movie.  Use 
QTVRSetControl  Setti  ng  (11-1416)  to  control  the  setting  of  kQTVRWrapPan. 


QTVRSetPrescreenlmagingCompleteProc 

Installs  or  removes  a  prescreen  buffer  imaging  completion  procedure. 
OSErr  QTVRSetPrescreenlmagi ngCompl eteProc  ( 


11-1432 


Inside  QuickTime:  Function  l-Q 


QTVRSetPrescreenlmagingCompleteProc 


QTVRInstance 
QTVRImagi  ngCompl  etellPP 
SInt32 
UInt32 


qtvr , 

i magi ngCompl eteProc , 
refCon , 
flags  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

i magi ngCompl eteProc 

A  Universal  Procedure  Pointer  for  a  QTVRImagi  ngCompl  eteProc  (III— 2129) 
callback.  To  remove  a  previously  installed  QTVRImagi  ngCompl  eteProc  callback, 
set  i  magi  ngCompl  eteProc  to  NIL. 
refCon 

A  reference  constant.  This  value  is  passed  to  the  specified  prescreen  buffer 
imaging  completion  callback.  Use  this  parameter  to  point  to  a  data  structure 
containing  any  information  your  callback  needs, 
fl  ags 

A  constant  (see  below)  that  causes  a  draw  attempt  on  every  idle  passed  to  the 
movie  controller  besides  being  called  whenever  QuickTime  VR  finishes 
drawing  an  image  into  the  prescreen  buffer. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

kQTVRP reScreen Every Idl e 

Causes  a  draw  attempt  on  every  idle  passed  to  the  movie  controller. 

Discussion 

This  function  installs  the  procedure  specified  by  the  1  magi  ngCompl  eteProc  parameter 
as  a  prescreen  buffer  imaging  completion  procedure  for  the  QuickTime  VR  movie 
specified  by  the  qtvr  parameter.  Your  procedure  is  called  whenever  QuickTime  VR 
finishes  drawing  an  image  into  the  prescreen  buffer.  The  reference  constant 
specified  by  the  refCon  parameter  is  passed  unchanged  to  that  prescreen  buffer 
imaging  completion  procedure. 

Special  Considerations 

QTVRSetPrescreenlmagi  ngCompl  eteProc  is  valid  only  for  panoramic  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTImeVR.h 

Programming  summary:  "Accessing  Image  Buffers"  (V-2914) 


Inside  QuickTime:  Function  l-Q 


11-1433 


QT  VR  S  et  Tilt  Angle 


Related  Java  Methods 

qui  ckti  me .  vr .  QTVRI instance  .setPrescreenlmagi  ngCompl  eteProc( ) , 
qui ckti me . vr . QTVRInstance . removePrescreenlmagi ngCompl eteProc( ) 

See  Also 

Use  QTVRSetBackBuf ferlmagi  ngProc  (11-1411)  to  install  or  remove  a  back  buffer 
imaging  procedure. 


QT  VRSetT  ilt  Angle 


Sets  the  tilt  angle  of  a  QuickTime  VR  movie. 

OSErr  QTVRSetT i 1 tAngl e  ( 

QTVRInstance  qtvr, 

f 1  oat  ti 1 tAngl e  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

ti 1 tAngl e 

The  desired  tilt  angle  of  the  specified  movie.  This  value  is  constrained  by  the 
maximum  and  minimum  tilt  angles  of  the  movie.  If  the  angle  falls  outside  of 
those  constraints  and  the  control  setting  kQTVRWrapT  1 1 1  is  disabled,  the  angle  is 
set  to  the  minimum  or  maximum,  whichever  is  closer.  If  wrapping  is  enabled, 
the  tilt  angle  is  clipped  to  fall  within  the  constraints.  Tilt  angle  values  are  also 
clipped  if  the  requested  tilt  angle,  when  combined  with  the  current  pan  angle 
and  field  of  view,  would  cause  an  image  to  lie  outside  the  current  constraints. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error.  This 
function  returns  the  result  code  constrai  ntReachedErr  if  wrapping  is 
off  and  the  angle  is  set  to  the  minimum  or  maximum  constraint 
value. 


Special  Considerations 

The  pan  and  tilt  angles  are  subject  to  the  current  pan  and  tilt  range  constraints,  as 
imposed  by  the  viewing  limits  and  the  current  field  of  view.  Accordingly,  if  you 
want  to  change  the  field  of  view,  you  should  do  so  before  adjusting  the  pan  or  tilt 
angles.  Otherwise,  the  pan  and  tilt  angles  are  clipped  against  the  current  field  of 
view,  which  may  result  in  an  incorrect  view  when  you  alter  the  field  of  view. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Inside  QuickTime:  Function  l-Q 


QTVRSetTransitionProperty 


Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Manipulating  Viewing  Angles  and  Zooming"  (V-2905) 

Related  Java  Methods 

qui cktime . vr . QTVRInstance . setT i 1 tAngl e( ) 


See  Also 

Use  QTVRGetT  1 1  tAngl  e  (11-1377)  to  get  the  tilt  angle  of  a  movie.  Use 
QTVRGetVi  ewi  ngLi  mi  ts  (11-1379)  to  get  the  current  viewing  limits  of  a  movie.  Use 
QTVRSetControl  Setti  ng  (11-1416)  to  control  the  setting  of  kQTVRWrapT i  1 1. 


QT  VRSetT  ransitionProperty 


Sets  the  value  of  a  transition  property. 


OSErr  QTVRSetTransitionProperty  ( 
QTVRInstance  qtvr, 

UInt32  transitionType, 

UInt32  transi ti onProperty , 

SInt32  transi ti onVal ue  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

transi ti onType 

A  type  of  transition  (see  below), 
transi ti onProperty 

A  type  of  transition  property  (see  below), 
transi ti onVal ue 

The  desired  value  for  the  specified  transition  property. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

transitionType  Constant 

kQTVRT  ransi ti onSwi ng 

A  transition  between  two  views  in  a  single  node. 

transitionProperty  Constants 

kQTVRT  ransi ti on Speed 

The  speed  at  which  the  transition  should  occur.  The  transi  ti  onVal  ue  for  this 
parameter  should  be  an  integer  from  1  (the  slowest  transition  speed)  through 
10  (the  fastest  transition  speed). 


Inside  QuickTime:  Function  l-Q 
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QTVRSetTransitionProperty 


kQTVRT ransi ti onDi recti  on 

The  direction  in  which  the  transition  should  occur .  The  t  r  a  n  s  i  t  i  o  n  V  a  1  u  e  for  this 
parameter  should  be  a  constant  (see  below)  that  indicates  the  direction  in  which 
the  view  should  swing  while  moving  from  the  current  view  to  the  new  view. 
This  direction  can  be  left  or  right,  or  it  can  have  the  value  -1,  which  causes  the 
default  direction  to  be  used.  By  default,  a  swing  transition  occurs  along  the 
shortest  route  between  the  two  views. 

kQTVRTransitionDirection  Constants 

kQTVRRi ght 

Swing  the  view  to  the  right. 
kQTVRUpRi ght 

Swing  the  view  up  and  to  the  right. 
kQTVRUp 

Swing  the  view  up. 
kQTVRUpLeft 

Swing  the  view  up  and  to  the  left. 
kQTVRLeft 

Swing  the  view  to  the  left. 
kkQTVRDownLeft 

Swing  the  view  down  and  to  the  left. 
kQTVRDown 

Swing  the  view  down. 
kQTVRDownRi ght 

Swing  the  view  down  and  to  the  right. 

Discussion 

This  function  sets  the  value  of  the  transition  property  whose  type  is  specified  by  the 
transi  ti  onType  and  transi  ti  onProperty  parameters  for  the  movie  specified  by  the 
qtvr  parameter  to  the  value  specified  by  the  transi  ti  onVal  ue  parameter.  Note  that 
calling  this  function  simply  sets  a  transition  property's  value;  you  must  still  call 
QTVREnabl  eT ransi  ti  on  (11-1341)  to  enable  that  transition  effect. 

Special  Considerations 

QTVRSetT ransi  ti  onProperty  is  valid  only  for  panoramic  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Imaging  Characteristics"  (V-2910) 
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Inside  QuickTime:  Function  l-Q 


QTVRSetViewCenter 


See  Also 

Use  QTVREnabl  eT ransi  ti  on  (11-1341)  to  enable  a  transition  effect. 


QTVRSetViewCenter 


Sets  the  view  center  of  a  QuickTime  VR  movie. 

OSErr  QTVRSetViewCenter  ( 

QTVRInstance  qtvr, 

const  QTVRF1 oatPoi nt  *viewCenter  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
vi ewCenter 

A  pointer  to  a  QTVRF1  oatPoi  nt  (IV-2396)  structure  that  contains  the  desired 
view  center  of  the  specified  movie.  This  point  is  constrained  by  the  current  field 
of  view  of  the  movie.  The  values  you  pass  in  the  QTVRF1  oatPoi  nt  structure  are 
adjusted  so  that  the  magnified  area  does  not  show  anything  outside  the  view. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error.  If  the 
kQTVRT  ransi  at  ion  control  setting  is  disabled,  this  function  returns  the 
result  code  constrai  ntReachedErr  and  doesn't  change  the  current 
view  center.  You  can  use  QTVRSetControl  Setti  ng  (11-1416)  to  control 
the  setting  of  kQTVRT  ransi  ati  on. 

Special  Considerations 

QTVRSetVi  ewCenter  is  valid  only  for  object  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Manipulating  Viewing  Angles  and  Zooming"  (V-2905) 

Related  Java  Methods 

qui cktime . vr . QTVRInstance . set Vi ewCenter! ) 


See  Also 

Use  QTVRGetVi  ewCenter  (11-1378)  to  get  the  view  center  of  a  movie. 


Inside  QuickTime:  Function  l-Q 
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QT  VR  S  et  Vie  wCurrentTime 


QT  VRSetV  iewCurrentT  ime 


Sets  the  time  in  the  current  QTVR  view. 

OSErr  QTVRSetVi ewCurrentTi me  ( 
QTVRInstance  qtvr, 

TimeVal ue  time  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

time 

The  desired  time  in  the  current  view.  This  value  should  be  greater  than  or  equal 
to  0  and  less  than  or  equ al  to  the  value  returned  by  Q  T  V  R G  e  t  C  u  r  r  e  n  t  V  i  e w  D  u  r  a  t  i  o  n 
(11-1360). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error.  This 
function  returns  the  result  code  ti  meNotlnVi  ewErr  if  the  specified 
time  value  is  greater  than  or  equal  to  the  view  duration  of  the 
specified  object  node;  in  addition,  it  sets  the  current  view  time  to  1 
less  than  the  view  duration.  Similarly,  this  function  returns  the  result 
code  ti  meNotlnVi  ewErr  if  the  specified  time  value  is  less  than  0;  in 
that  case,  it  sets  the  current  view  time  to  0. 

Special  Considerations 

QTVRSetVi ewCurrentT ime  is  valid  only  for  object  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Object  Nodes"  (V-2909) 

See  Also 

Use  QTVRGetVi  ewCurrentT i  me  (11-1379)  to  get  the  current  time  of  an  object  node. 


QT  VRSetV  iewParameter 


Undocumented 

OSErr  QTVRSetVi ewParameter  ( 
QTVRInstance  qtvr, 

UInt32  vi ewParameter , 
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Inside  QuickTime:  Function  l-Q 


QTVRSetViewRate 


void  *value, 

UInt32  flagsln  ); 

qtvr 

Undocumented 
vi ewParameter 

Undocumented 
val  ue 

Undocumented 
fl agsln 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 


QTVRSetViewRate 


Sets  the  view  rate  of  a  QTVR  object  node. 

OSErr  QTVRSetViewRate  ( 

QTVRInstance  qtvr, 

float  rate  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRI instance  (11-1373). 

rate 

The  desired  view  rate  of  the  specified  movie.  A  view  rate  is  a  floating-point 
value  in  the  range  from  -100.0  to  +100.0.  Positive  values  indicate  forward  rates, 
and  negative  values  indicate  reverse  rates.  Set  this  parameter  to  0  to  stop  the 
movie. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  sets  the  view  rate  of  the  object  node  specified  by  the  qtvr  parameter 
to  the  rate  specified  by  the  rate  parameter.  A  node's  view  rate  might  be  modified  by 


Inside  QuickTime:  Function  l-Q 
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QTVRSetViewState 


the  current  animation  settings.  If  the  value  specified  in  the  rate  parameter  lies 
outside  the  valid  range,  this  function  returns  the  result  code  constrai  ntReachedErr 
and  sets  the  view  rate  to  the  nearest  constraint. 

Special  Considerations 

QTVRSetVi  ewRate  is  valid  only  for  object  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Object  Nodes"  (V-2909) 

See  Also 

For  the  corresponding  get  function,  see  QTVRGetVi  ewRate  (11-1381).  Use 
QTVRGetVi  ewRate  to  get  the  current  view  rate  of  an  object  node. 


QT  VRSetV  iewState 


Sets  the  value  of  a  QTVR  view  state. 

OSErr  QTVRSetViewState  ( 

QTVRInstance  qtvr, 

QTVRVi ewStateType  vi ewStateType  , 

UIntl6  state  )  ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

vi ewStateType 

A  view  state  type  (see  below), 
state 

The  desired  value  of  the  specified  type  of  view  state. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

viewStateType  Constants 

kQTVRDefault 

The  default  view  state  of  the  current  view.  The  default  view  state  is  a  set  of 
object  images  defined  by  view  duration,  row,  and  column.  The  default  view 
state  image  for  a  given  view  is  displayed  when  the  mouse  button  is  not  down. 


11-1440 


Inside  QuickTime:  Function  l-Q 


QTVRSetVisible 


kQTVRCurrent 

The  current  view  state  of  the  current  view.  The  current  view  state  can  be  any  of 
the  view  states  authored  in  an  object  movie.  Setting  the  current  view  state  does 
not  change  the  view  state  designated  as  the  kQTVRDefaul  t  or  kQTVRMouseDown 
view  state.  The  effect  of  changing  the  current  view  state  lasts  until  a  transition 
to  the  mouse-down  or  default  view  state  occurs. 
kQTVRMouseDown 

The  mouse-down  state  of  the  current  view.  The  mouse-down  view  state  is  a  set 
of  object  images  defined  by  view  duration,  row,  and  column.  The  mouse-down 
view  state  image  for  a  given  view  is  displayed  when  the  user  holds  the  mouse 
button  down  while  the  cursor  is  over  an  object  movie. 

Special  Considerations 

QTVRSetVi  ewState  is  valid  only  for  object  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Object  Nodes"  (V-2909) 

See  Also 

Use  QTVRGetVi  ewState  (11-1382)  to  get  the  value  of  a  view  state. 


QTVRSetVisible 


Sets  a  VR  movie's  visibility  state. 

OSErr  QTVRSetVisible  ( 
QTVRInstance  qtvr. 

Boolean  visible  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
vi  si  bl  e 

A  Bool  ea  n  value  that  indicates  whether  the  specified  movie  is  to  be  visible  (TRU  E) 
or  not  (FALSE). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Inside  QuickTime:  Function  l-Q 
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QTVRShowDefaultView 


Discussion 

Setting  the  visibility  state  to  FALSE  is  useful  if  you  want  to  turn  off  imaging  a 
QuickTime  VR  movie  without  purging  the  associated  data  from  memory.  When  a 
panoramic  node's  visibility  state  is  FALSE,  the  corrected  image  is  still  drawn  to  the 
prescreen  buffer.  You  can  access  the  data  in  that  buffer  by  calling 
QTVRSetPrescreenlmagi  ngCompl  eteProc  (11-1432). 

Special  Considerations 

This  function  is  valid  only  for  panoramic  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Imaging  Characteristics"  (V-2910) 

See  Also 

Use  QTVRGetVi  sibl  e  (11-1384)  to  get  the  visibility  state  of  a  movie. 


QT  VRShowDef  aultV  ie  w 


Displays  the  default  view  of  a  QTVR  node. 

OSErr  QTVRShowDefaultView  ( 

QTVRInstance  qtvr  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  sets  the  default  values  of  the  pan  angle,  tilt  angle,  field  of  view,  view 
center  (for  object  nodes),  default  state,  mouse-down  state,  and  all  applicable 
animation  and  control  settings  for  the  VR  movie  specified  by  the  qtvr  parameter.  A 
VR  movie's  default  view  values  are  stored  in  the  movie  file. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Manipulating  Viewing  Angles  and  Zooming"  (V-2905) 
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Inside  QuickTime:  Function  l-Q 


QTVRTiltToRow 


Related  Java  Methods 

qui cktime . vr . QTVRInstance . showDef aul tVi ew( ) 


QTVRTiltToRow 

Obtains  the  row  number  in  the  QTVR  object  image  array  that  corresponds  to  a  tilt 
angle. 

short  QTVRTiltToRow  ( 

QTVRInstance  qtvr, 

float  tiltAngle  ); 

qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
ti 1 tAngl e 

A  tilt  angle. 

function  result  The  zero-based  row  number  in  the  current  object  image  array  that 
corresponds  to  the  tilt  angle  specified  by  the  ti  1  tAngl  e  parameter. 

Special  Considerations 

This  function  is  valid  only  for  object  nodes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Converting  Angles  and  Points"  (V-2911) 

Related  Java  Methods 

qui cktime . vr . QTVRInstance .til tToRowI ) 


QT  VRT  riggerHotSpot 

Triggers  a  QTVR  hot  spot. 

OSErr  QTVRTri ggerHotSpot  ( 

QTVRInstance  qtvr, 

UInt32  hotSpotID, 

QTAtomContai ner  nodeinfo, 

QTAtom  selectedAtom  ); 


Inside  QuickTime:  Function  l-Q 
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QTVRTriggerHotSpot 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
hotSpotID 

A  hot  spot  ID. 
nodeinfo 

A  node  information  atom  container,  obtained  from  a  previous  call  to 
QTVRGetNodelnfo  (11-1371).  You  can  pass  the  value  0  in  this  parameter  to  have 
QuickTime  determine  the  appropriate  node  information  atom  container, 
sel ectedAtom 

The  atom  of  the  hot  spot  to  trigger.  You  can  pass  the  value  0  in  this  parameter 
to  have  QuickTime  determine  the  appropriate  hot  spot  atom. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

One  way  you  can  use  this  function  is  to  execute  any  hot  spot  without  the  user's 
having  clicked  it.  Usually,  you  need  only  specify  the  qtvr  instance  and  the  hot  spot 
ID.  You  can  pass  zero  for  the  nodeinfo  and  sel  ectedAtom  parameters. 

The  more  common  use  of  this  function  is  not  in  calling  it  directly,  but  in  setting  up 
an  intercept  procedure  on  it.  This  function  is  called  internally  by  QuickTime 
whenever  a  user  clicks  a  hot  spot.  You  can  intercept  calls  to  trigger  your  custom  hot 
spots,  which  allows  you  to  perform  any  custom  actions  you  desire. 

When  this  function  is  called  internally  (and  then  intercepted  by  your  intercept 
procedure),  the  node  Info  and  sel  ectedAtom  parameters  have  been  properly  set  by 
QuickTime  and  are  available  for  your  use.  For  undefined  hot  spots  that  do  not  have 
an  associated  hot  spot  atom  in  the  node  i  nf  o  atom  container,  the  sel  ectedAtom 
parameter  will  be  set  to  zero. 

Special  Considerations 

You  can  call  this  function  even  on  hot  spots  that  are  currently  disabled. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Hot  Spots"  (V-2906) 

Related  Java  Methods 

qui ckti me . vr . QTVRInstance .triggerHotSpott ) 
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QTVRUpdate 


See  Also 

Use  QTVRInstal  1  InterceptProc  (11-1387)  to  install  an  intercept  procedure. 


QTVRUpdate 


Forces  an  immediate  update  of  a  QuickTime  VR  movie  image. 

OSErr  QTVRUpdate  ( 

QTVRInstance  qtvr, 

QTVRImagi ngMode  imagingMode  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRI instance  (11-1373). 
i magi ngMode 

An  imaging  mode.  You  can  specify  kQTVRCurrentMode  (see  below)  to  use  the 
current  imaging  mode. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

imagingMode  Constants 

kQTVRCurrentMode 

The  current  imaging  mode. 

Discussion 

This  function  immediately  updates  the  image  for  the  QuickTime  VR  movie 
specified  by  the  qtvr  parameter,  without  waiting  for  the  next  call  to  MoviesTask 
(11-973)  in  your  application's  main  event  loop.  If  you  plan  to  call  this  function 
repeatedly  for  a  movie  instance,  then  for  improved  performance  you  should  bracket 
those  calls  with  calls  to  QTVRBegi  nUpdateStream  (11-1335)  and  QTVREndUpdateStream 
(11-1343). 

Special  Considerations 

If  you  call  this  function  after  calling  QTVRBegi  nUpdateStream  (11-1335)  but  before 
calling  QTVREndUpdateStream  (11-1343),  the  i  magi  ngMode  parameter  passed  to  it  must 
be  the  same  as  the  imagingMode  parameter  passed  to  QTVRBegi  nUpdateStream.  If  you 
do  not  specify  the  same  imaging  mode  to  those  two  functions,  an  error  will  result. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Managing  Imaging  Characteristics"  (V-2910) 


Inside  QuickTime:  Function  l-Q 
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QTVRWrapAndConstrain 


Related  Java  Methods 

qui  ckti  me .  vr .  QTVRI instance .  update  ( ) 


QTVRWrapAndConstrain 


Preflights  a  change  in  the  viewing  or  control  characteristics  of  a  QTVR  object  or 
panoramic  node. 


OSErr  QTVRWrapAndConstrain 


QTVRInstance  qtvr, 
short  kind, 

float  value, 

float  *resul 


( 


t 


) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

ki  nd 

A  constraint  type  (see  below), 
val  ue 

The  desired  value  of  the  specified  viewing  characteristic, 
resul t 

On  return,  the  value  to  which  the  specified  viewing  characteristic  would  be 
set  if  it  were  changed. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

kind  Constants 

kQTVRPan 

The  pan  angle.  The  associated  value  is  of  type  f  1  oat. 
kQTVRTilt 

The  tilt  angle.  The  associated  value  is  of  type  f  1  oat. 
kQTVRFi el dOfVi ew 

The  field  of  view.  The  associated  value  is  of  type  float. 
kQTVRVi ewCenterH 

The  horizontal  view  center.  This  value  is  valid  only  for  this  function,  which 
returns  the  horizontal  view  center  constrained  in  the  current  field  of  view.  The 
minimum  and  maximum  values  of  the  horizontal  view  center  change  for  every 
field-of-view  setting.  If  the  field  of  view  of  the  object  is  the  maximum  field  of 
view,  the  object's  horizontal  view  center  is  constrained  to  a  single  value  that  is 
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QuadToQuadMatrix 


the  horizontal  center  of  the  object  image  in  display  coordinates  (rounding 
down  any  fractional  pixels). 

kQTVRVi ewCenterV 

The  vertical  view  center.  This  value  is  valid  only  for  this  function,  which 
returns  the  vertical  view  center  constrained  in  the  current  field  of  view.  The 
minimum  and  maximum  values  of  the  vertical  view  center  change  for  every 
field-of-view  setting.  If  the  field  of  view  of  the  object  is  the  maximum  field  of 
view,  the  object's  vertical  view  center  is  constrained  to  a  single  value  that  is  the 
vertical  center  of  the  object  image  in  display  coordinates  (rounding  down  any 
fractional  pixels). 

Discussion 

This  function  returns,  in  the  result  parameter,  the  constrained  or  wrapped  value 
that  would  result  from  setting  the  viewing  or  control  characteristic  specified  by 
the  kind  parameter  to  the  value  specified  by  the  value  parameter.  For  example,  if  the 
ki  nd  parameter  is  set  to  kQTVRPan,  then  this  function  returns  the  value  that  would 
result  from  calling  QTVRSetPanAngl  e  (11-1431)  with  its  panAngl  e  parameter  set  to  the 
value  parameter.  Similarly,  you  can  use  this  function  to  find  the  current  bounds  of 
the  view  center.  It  takes  into  account  the  current  constraints  and  wrapping  modes 
of  the  node  specified  by  the  qtvr  parameter.  This  function  does  not  change  the 
current  view  or  other  settings  of  the  specified  object  or  panorama. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Converting  Angles  and  Points"  (V-2911) 

Related  Java  Methods 

qui cktime . vr . QTVRInstance . wrapAndConstrai n( ) 


QuadT  oQuadMatrix 


Undocumented 


OSErr  QuadToQuadMatrix  ( 

const  Fixed  *source, 

const  Fixed  *dest, 

MatrixRecord  *map  ); 


source 

Undocumented 


Inside  QuickTime:  Function  l-Q 
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QuadToQuadMatrix 


dest 

Undocumented 

map 

A  pointer  to  a  Matri  xRecord  (IV-2304)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Related  Java  Methods 

qui ckti me . std . i mage . Matri x. Matri x( ) 
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Volume  HI 


Functions  R-Z  and  Callbacks 


RectMatrix 


RectMatrix 


Creates  a  matrix  that  performs  the  translate  and  scale  operation  described  by  the 
relationship  between  two  rectangles. 

void  RectMatrix  ( 

Matri xRecord 
const  Rect 
const  Rect 

matri x 

A  pointer  to  a  Matri  xRecord  (IV-2304)  structure.  This  function  updates  the 
contents  of  this  matrix  so  that  the  matrix  describes  a  transformation  from  points 
in  the  rectangle  specified  by  the  srcRect  parameter  to  points  in  the  rectangle 
specified  by  the  dstRect  parameter.  The  previous  contents  of  the  matrix  are 
ignored. 
srcRect 

A  pointer  to  the  source  Rect  (IV-2399)  structure. 
dstRect 

A  pointer  to  the  destination  Rect  (IV-2399)  structure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Matrices"  (V-2764) 

Related  Java  Methods 

qui ckti me . std . image . Matrix. rect ( ) 


*matrix, 
*srcRect, 
*dstRect  ); 


RegisterComponent 


Makes  a  component  that  is  resident  in  memory  available  for  use  by  applications  or 
other  clients. 

Component  RegisterComponent  ( 

ComponentDescri pti on  *cd. 

Component  Rout  i  nellPP  component  EntryPoi  nt , 


Inside  QuickTime:  Functions  R-Z 
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RegisterComponent 


short 
Handl e 
Hand"!  e 
Handl e 


gl obal  , 

componentName , 
componentlnfo , 
componentlcon  ) ; 


cd 

A  Component  Descri  pti  on  (IV-2212)  structure  that  describes  the  component  to  be 
registered.  You  must  correctly  fill  in  the  fields  of  this  record  before  calling  this 
function.  When  applications  search  for  components  using  Fi  ndNextComponent 
(1-360),  the  Component  Manager  compares  the  attributes  you  specify  here  with 
those  specified  by  the  application.  If  the  attributes  match,  this  function  returns 
the  component  identifier. 

componentEntryPoi nt 

A  Universal  Procedure  Pointer  to  the  main  entry  point  of  the  component  you 
are  registering.  The  routine  referred  to  by  this  parameter  receives  all  requests 
for  the  component, 
gl obal 

Flags  (see  below)  that  control  the  scope  of  component  registration. 
componentName 

A  handle  to  the  component's  name.  Set  this  parameter  to  N I L  if  you  do  not  want 
to  assign  a  name  to  the  component. 

componentlnfo 

A  handle  to  the  component's  information  string.  Set  this  parameter  to  N I L  if  you 
do  not  want  to  assign  an  information  string  to  the  component, 
componentlcon 

A  handle  to  the  component's  32-by-32  pixel  black-and-white  icon.  Set  this 
parameter  to  N I L  if  you  do  not  want  to  supply  an  icon  for  this  component.  Note 
that  this  icon  is  not  used  by  QuickTime;  you  supply  an  icon  only  so  that  other 
components  or  applications  can  display  your  component's  icon  if  needed. 

function  result  The  component  identifier  assigned  to  the  component  by  the 

Component  Manager.  If  it  cannot  register  the  component,  this 
function  returns  N I L.  If  this  function  fails  to  register  a  component 
because  one  with  identical  characteristics  already  exists,  it  returns  0. 

global  Constants 

regi sterCmpGl obal 

Indicates  that  this  component  should  be  made  available  to  other  applications 
and  clients  as  well  as  the  one  performing  the  registration.  If  you  do  not  specify 
this  flag,  the  component  is  available  for  use  only  by  the  registering  application 
or  component. 
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RegisterComponentResource 


regi sterCmpNoDupl  i  cates 

Indicates  that  if  a  component  with  identical  characteristics  to  the  one  being 
registered  already  exists,  then  the  new  one  should  not  be  registered.  The 
function  returns  0  in  this  situation.  If  you  do  not  specify  this  flag,  the 
component  is  registered  even  if  a  component  with  identical  characteristics  to 
the  one  being  registered  already  exists, 
regi sterCompAfter 

Indicates  that  this  component  should  be  registered  after  all  other  components 
with  the  same  component  type.  Usually  components  are  registered  before 
others  with  identical  descriptions;  specifying  this  flag  overrides  that  behavior. 

Discussion 

This  function  registers  the  specified  component,  recording  the  information 
specified  in  the  cd,  componentName,  componentlnfo,  and  componentlcon  parameters. 
Once  a  component  has  been  registered,  applications  can  find  and  open  it  using  the 
standard  Component  Manager  routines. 

Special  Considerations 

Components  you  register  with  the  this  function  must  be  in  memory  when  you  call 
it.  Note  that  a  component  residing  in  your  application  heap  remains  registered  until 
your  application  unregisters  it  or  quits.  A  component  residing  in  the  system  heap 
and  registered  by  your  application  remains  registered  until  your  application 
unregisters  it  or  until  the  computer  is  shut  down. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 

See  Also 

If  you  want  to  register  a  component  that  is  stored  in  a  file,  use 
Regi  sterComponentResource  (III — 1453). 


RegisterComponentResource 


Makes  a  component  that  is  stored  in  a  file  available  for  use  by  applications  or  other 
clients. 

Component  RegisterComponentResource  ( 

ComponentResourceHandl e  cr, 

short  global  ); 
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RegisterComponentResource 


cr 

A  handle  to  a  component  resource  that  describes  the  component  to  be 
registered.  Components  you  register  with  this  function  must  be  stored  in  a  file 
as  a  ComponentResource  (IV-2219)  structure.  The  component  resource  contains 
all  the  information  required  to  register  the  component, 
gl obal 

Flags  (see  below)  that  control  the  scope  of  component  registration. 

function  result  The  component  identifier  assigned  to  the  component  by  the 

Component  Manager.  If  it  cannot  register  the  component,  this 
function  returns  N I L.  If  this  function  fails  to  register  a  component 
because  one  with  identical  characteristics  already  exists,  it  returns  0. 

global  Constants 

regi sterCmpGl obal 

Indicates  that  this  component  should  be  made  available  to  other  applications 
and  clients  as  well  as  the  one  performing  the  registration.  If  you  do  not  specify 
this  flag,  the  component  is  available  for  use  only  by  the  registering  application 
or  component, 
regi sterCmpNoDupl i cates 

Indicates  that  if  a  component  with  identical  characteristics  to  the  one  being 
registered  already  exists,  then  the  new  one  should  not  be  registered.  The 
function  returns  0  in  this  situation.  If  you  do  not  specify  this  flag,  the 
component  is  registered  even  if  a  component  with  identical  characteristics  to 
the  one  being  registered  already  exists, 
regi sterCompAfter 

Indicates  that  this  component  should  be  registered  after  all  other  components 
with  the  same  component  type.  Usually  components  are  registered  before 
others  with  identical  descriptions;  specifying  this  flag  overrides  that  behavior. 

Discussion 

This  function  does  not  actually  load  the  code  specified  by  the  component  resource 
into  memory.  Rather,  the  Component  Manager  loads  the  component  code  the  first 
time  an  application  opens  the  component.  If  the  code  is  not  in  the  same  file  as  the 
component  resource  or  if  the  Component  Manager  cannot  find  the  file,  the  open 
request  fails. 

Special  Considerations 

Note  that  a  component  registered  locally  by  your  application  remains  registered 
until  your  application  unregisters  it  or  quits.  A  component  registered  globally  by 
your  application  remains  registered  until  your  application  unregisters  it  or  until  the 
computer  is  shut  down. 
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RegisterComponentResourceFile 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 

See  Also 

If  you  want  to  register  a  component  that  is  in  memory,  use  Regi  sterComponent 
(III— 1451). 

RegisterComponentResourceFile 

Registers  all  component  resources  in  a  given  resource  file. 

long  RegisterComponentResourceFile  ( 
short  resRefNum, 

short  global  ); 

resRefNum 

The  reference  number  of  the  resource  file  containing  the  components  to 
register. 

gl obal 

Flags  (see  below)  that  control  the  scope  of  component  registration. 

function  result  If  RegisterComponentResourceFile  successfully  registers  all 

components  in  the  specified  resource  file,  it  returns  the  number  of 
components  registered.  If  it  could  not  register  one  or  more  of  the 
components  in  the  resource  file  or  if  the  specified  file  reference 
number  is  invalid,  it  returns  a  negative  function  result. 

global  Constants 

regi sterCmpGl obal 

Indicates  that  this  component  should  be  made  available  to  other  applications 
and  clients  as  well  as  the  one  performing  the  registration.  If  you  do  not  specify 
this  flag,  the  component  is  available  for  use  only  by  the  registering  application 
or  component. 

regi sterCmpNoDupl i cates 

Indicates  that  if  a  component  with  identical  characteristics  to  the  one  being 
registered  already  exists,  then  the  new  one  should  not  be  registered.  The 
function  returns  0  in  this  situation.  If  you  do  not  specify  this  flag,  the 
component  is  registered  even  if  a  component  with  identical  characteristics  to 
the  one  being  registered  already  exists. 
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regi sterCompAfter 

Indicates  that  this  component  should  be  registered  after  all  other  components 
with  the  same  component  type.  Usually  components  are  registered  before 
others  with  identical  descriptions;  specifying  this  flag  overrides  that  behavior. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 

See  Also 

See  Regi sterComponentResource  (III — 1453). 


RemoveCallBackFromTimeBase 

Removes  a  callback  event  from  the  list  of  scheduled  callback  events. 

OSErr  RemoveCallBackFromTimeBase  ( 

QTCal 1  Back  cb  ) ; 


cb 

The  callback  event  for  the  operation.  Your  clock  component  obtains  this  value 
from  the  parameters  passed  to  your  Cl  ockCal  1  MeWhen  (1-91)  function. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

Your  clock  component  should  call  this  function  when  your  Cl  ockCancel  Cal  1  Back 
(1-93)  function  determines  that  your  component  can  cancel  the  callback  event. 

Special  Considerations 

Your  component  should  call  this  function  only  for  callback  events  that  were 
successfully  added  to  the  schedule  with  AddCal  1  BackToTimeBase  (1-21). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Movie  Toolbox  Clock  Support  Functions"  (V-2869) 
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RemovelmageDescriptionExtension 


Removes  a  specified  extension  from  an  ImageDescri  pti  on  (IV-2285)  structure. 

OSErr  RemovelmageDescri pti onExtensi on  ( 

ImageDescri pti onHandl e  desc, 

long  idType, 

long  index  ); 


desc 

A  handle  to  an  ImageDescri  pti  on  (IV-2285)  structure, 
i  dType 

The  type  of  extension  to  remove, 
i  ndex 

The  index  of  the  extension  to  remove.  This  is  a  number  between  1  and  the  count 
returned  by  CountlmageDescri  pti  onExtensi  onType  (1-143). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  allows  an  application  to  remove  a  specified  extension  from  an 
ImageDescri  pti  on  (IV-2285)  structure.  Note  that  any  extensions  that  are  present  in 
the  structure  after  the  deleted  extension  will  have  their  index  numbers  renumbered. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Image  Descriptions"  (V-2790) 


RemoveMovieExecuteWiredActionsProc 


Removes  a  Movi  eExecuteWi  redActi  onsProc  (III— 2101)  callback  from  a  movie. 

OSErr  RemoveMovi eExecuteWi redActi onsProc  ( 

Movie  theMovie, 

Movi  eExecuteWi  redActi  onsLIPP  proc, 

void  *refCon  ); 
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theMovi e 

A  movie  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e 
(11-1084). 

proc 

A  Movi  eExecuteWi  redActi  onsProc  (III— 2101)  callback  that  was  previously 
installed  using  AddMovi  eExecuteWi  redActi  onsProc  (1-36). 

refCon 

A  reference  constant  that  is  passed  to  your  callback.  Use  this  parameter  to  point 
to  a  data  structure  containing  any  information  your  callback  needs. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es .  h 


RemoveMovieResource 


Removes  a  movie  resource  from  a  specified  movie  file. 

OSErr  RemoveMovieResource  ( 
short  resRefNum, 

short  resld  ) ; 

resRefNum 

Identifies  the  movie  file  that  contains  the  movie  resource.  Your  application 
obtains  this  value  from  OpenMovieFile  (11-1133). 

resld 

ID  of  the  resource  to  be  removed. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Saving  Movies"  (V-2715) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . remove Res ource( ) 


RemoveSoundDescriptionExtension 


Removes  an  extension  from  a  SoundDescri  pti  on  (IV-2449)  structure. 

OSErr  RemoveSoundDescri pti onExtensi on  ( 

SoundDescri pti onHandl e  desc, 

OSType  idType  ); 


desc 

A  handle  to  the  SoundDescri  pti  on  (IV-2449)  structure  to  remove  the  extension 
from. 

i  dType 

A  four-byte  signature  identifying  the  type  of  data  being  removed  from  the 
SoundDescri  pti  on  structure. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Related  Java  Methods 

qui ckti me . std .movi es .medi a . SoundDescri pti on . removeExtensi  on( ) 


RemoveUserData 


Removes  an  item  from  a  user  data  list. 

OSErr  RemoveUserData  ( 

UserData  theUserData, 

OSType  udType, 

long  index  ); 


Inside  QuickTime:  Functions  R-Z 


III-1459 


RemoveUserD  ataText 


theUserData 

The  user  data  list  for  this  operation.  You  obtain  this  list  reference  by  calling 
GetMovi  ellserData  (1-499),  GetTrackUserData  (1-546),  or  GetMedi  aUserData 
(1-456). 

udType 

The  item's  type  value, 
i  ndex 

The  item's  index  value.  This  parameter  must  specify  an  item  in  the  user  data 
list  identified  by  the  theUserData  parameter. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

After  the  Movie  Toolbox  removes  the  item,  it  renumbers  the  remaining  items  of  that 
type  so  that  their  index  values  are  sequential  and  start  at  1. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  User  Data"  (V-2743) 

Related  Java  Methods 

qu i c kti me. std. mo vies. media. User Data, remove Data ( ) 


RemoveUserDataT  ext 

Removes  language-tagged  text  from  an  item  in  a  user  data  list. 

OSErr  RemoveUserDataText  ( 

UserData  theUserData, 

OSType  udType, 

long  index, 

short  i tl Regi onTag  ) ; 

theUserData 

The  user  data  list  for  this  operation.  You  obtain  this  list  reference  by  calling  the 
GetMovi  eUserData  (1-499),  GetT rackUserData  (1-546),  or  GetMedi  aUserData 
(1-456). 
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ReplaceDSequencelmageDescription 


udType 

The  item's  type  value, 
i  ndex 

The  item's  index  value.  This  parameter  must  specify  an  item  in  the  user  data 
list  identified  by  the  thellserData  parameter. 

i tl Regi onTag 

The  language  code  of  the  text  to  be  removed.  See  "Localization  Codes" 
(IV-2673). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  User  Data"  (V-2743) 

Related  Java  Methods 

qui cktime . std .movi es .medi a.UserData. removeText( ) 


ReplaceDSequencelmageDescription 

Undocumented 

OSErr  Repl aceDSequencelmageDescri  pti  on  ( 

ImageSequence  seqlD, 

ImageDescri pti onHandl e  newDesc  ); 

seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi  n  (1-238). 
newDesc 

A  handle  to  an  ImageDescri  pti  on  (IV-2285)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


Inside  QuickTime:  Functions  R-Z 


III-1461 


ResolveComponentAlias 


ResolveComponentAlias 

Undocumented 

Component  ResolveComponentAlias  ( 
Component  aComponent  ) ; 

aComponent 

A  component  instance. 
function  result  A  component  instance. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 


RotateMatrix 


Modifies  the  contents  of  a  matrix  so  that  it  defines  a  rotation  operation. 


void  RotateMatrix 
Matri xRecord 
Fi  xed 
Fi  xed 
Fi  xed 


*m , 

degrees , 
aboutX , 
aboutY  ) ; 


m 

A  pointer  to  a  Matri  xRecord  (IV-2304)  structure, 
degrees 

The  number  of  degrees  of  rotation. 
aboutX 

The  x  coordinate  of  the  anchor  point  of  rotation. 
aboutY 

The  y  coordinate  of  the  anchor  point  of  rotation. 

Discussion 

This  function  updates  the  contents  of  a  matrix  so  that  the  matrix  describes  a  rotation 
operation;  that  is,  it  concatenates  the  rotation  transformations  onto  whatever  was 
initially  in  the  matrix  structure.  You  specify  the  direction  and  amount  of  rotation 
with  the  degrees  parameter.  You  specify  the  point  of  rotation  with  the  aboutX  and 
aboutY  parameters. 


III-1462 
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RTPMPDoUserDialog 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Matrices"  (V-2764) 

Related  Java  Methods 

qui ckti me . std . image . Matrix. rotate ( ) 


RTPMPDoUserDialog 


Obtains  media-specific  settings  from  the  user  through  a  dialog  box. 

ComponentResul t  RTPMPDoUserDialog  ( 

RTPMedi aPacketi zer  rtpm. 

Modal  Fi  1  terUPP  inFilterUPP, 

Boolean  *canceled  ); 


rtpm 

The  component  instance  of  the  media  packetizer. 
i n  F i 1 terUPP 

A  Modal  Fi  1  terProc  (III— 2098)  callback,  which  may  be  used  in  a  call  to  the  Mac 
OS  Modal  Di  al  og  function. 

cancel ed 

On  return,  a  Boolean  which  is  TRUE  if  the  user  pressed  the  cancel  button  in  the 
dialog  box.  If  this  parameter  is  returned  TRUE,  the  settings  prior  to  calling  this 
function  should  be  retained. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  invokes  a  media  packetizer's  modal  dialog  to  obtain  user  settings.  If 
the  packetizer  supports  "more  settings,"  you  can  put  up  a  dialog  allowing  the  user 
to  enter  media-specific  settings.  You  can  determine  whether  a  packetizer  has  this 
character!  sti  c  by  calling  RTPMPHasCharacteri  sti  c  (III— 1471)).  The  settings  can  be 
obtained  for  storage  by  calling  RTPMPGetSetti  ngs  IntoAtomContai  nerAtAtom 
(III— 1469),  and  can  be  restored  or  set  directly  from  an  application  by  calling 
RTPMPSetSetti  ngsFromAtomContai  nerAtAtom  (III — 1481). 

Special  Considerations 

This  function  may  be  called  at  any  time. 


Inside  QuickTime:  Functions  R-Z 


III-1463 


RTPMPFlush 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


RTPMPFlush 


Renamed  RTPMPReset  (III— 1474). 

ComponentResul t  RTPMPFlush  ( 

RTPMedi aPacketi zer  rtpm, 

SInt32  inFlags, 

SInt32  *outFl ags  ) ; 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


RTPMPGetlnfo 


Obtains  information  of  various  types  from  a  media  packetizer. 

ComponentResul t  RTPMPGetlnfo  ( 

RTPMedi aPacketi zer  rtpm, 

OSType  inSelector, 

voi d  *i oParams  ) ; 


rtpm 

The  component  instance  of  the  media  packetizer  you  want  information  from, 
i nSel ector 

The  selector  for  the  type  information  you  want  (see  below), 
i oParams 

A  pointer  to  a  data  structure  of  the  appropriate  type  to  hold  the  information 
you  are  requesting.  You  need  to  allocate  and  dispose  of  this  data  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  qtsBadSel  ectorErr  if 

inSelector  requests  a  selector  you  do  not  support.  Returns  noErr  if 
there  is  no  error. 


III-1464 
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RTPMPG  etlnf  o 


inSelector  Constants 

kRTPMPPayloadTypelnfo 

The  function  fills  a  data  structure  of  type  RTPMPPayl  oadTypeParams  (IV-2407), 
which  describes  the  payload  being  used.  If  the  f  1  ags  field  of  this  structure 
contains  kRTPMPPayl  oadTypeStati  cFl  ag,  then  the  payl  oadNumber  field  contains 
the  RTP  payload  number;  if  the  flags  field  of  the  structure  contains 
kRTPMPPayl  oadTypeDyn  ami  c  FI  a  g,  then  the  payl  oad  Name  field  contains  the  name  of 
the  dynamic  payload  encoding  being  use.  The  caller  must  copy  the  payl  oad  Name 
field  data  for  it  to  be  persistent. 

kRTPMPRTPTi meScal  el nfo 

The  function  returns  the  RTP  time  scale  used  by  this  packetizer  if  the  time  scale 
must  be  a  specific  value;  otherwise  it  returns  an  error  for  this  selector. 
kRTPMPRequi red Samp! eDescriptionlnfo 

The  function  returns  a  handle  to  a  Sampl  eDescri  pti  on  (IV-2414)  structure 
specifying  that  only  data  with  the  given  sample  description  is  supported;  if  no 
such  structure  exists,  it  returns  an  error  for  this  selector. 
kRTPMPMi nPayl oadSi  ze 

The  function  returns  the  minimum  payload  size  of  packets  allowed  by  this 
packetizer  as  a  value  of  type  UInt32. 

kRTPMPMi nPacketDurati  on 

The  function  returns  the  minimum  packet  duration  allowed  by  this  packetizer, 
in  milliseconds,  as  a  value  of  type  UInt32. 
kRTPMPSugges ted  Repea tPktCount Inf o 

The  function  returns  the  suggested  number  of  repeat  packets  to  send  for  this 
media,  as  a  value  of  type  UInt32.  This  will  typically  be  0  for  audio  or  video,  1 
for  text  or  MIDI. 

kRTPM PSugges ted  Repea tedPkt Spa ci  nglnf o 

The  function  returns  the  suggested  temporal  distance  between  repeat  packets, 
in  milliseconds,  as  a  value  of  type  UInt32. 

Discussion 

This  function  can  be  called  at  any  time. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 

See  Also 

For  the  corresponding  set  function,  see  RTPMPSetlnfo  (III— 1475). 
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III-1465 


RTPMPGetMaxPacketDuration 


RTPMPGetMaxPacketDuration 


Reads  the  maximum  packet  duration  currently  set  for  this  packetizer. 

ComponentResul t  RTPMPGetMaxPacketDuration  ( 

RTPMedi aPacketi zer  rtpm, 

UInt32  *outMaxPacketDurati on  ); 


rtpm 

The  component  instance  of  the  media  packetizer. 
outMaxPacketDurati on 

On  return,  a  pointer  to  a  32-bit  integer  containing  the  maximum  packet 
duration,  in  milliseconds,  that  the  packetizer  is  set  to  use. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  maximum  allowable  packet  duration  can  change  during  a  presentation,  so  you 
should  obtain  this  value  immediately  before  using  it. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 

See  Also 

For  the  corresponding  set  function,  see  RTPMPSetMaxPacketDurati  on  (III— 1477). 


RTPMPGetMaxPacketSize 


Returns  the  maximum  packet  size,  in  bytes,  that  the  packetizer  is  set  to  create. 

ComponentResul t  RTPMPGetMaxPacketSize  ( 

RTPMedi aPacketi zer  rtpm, 

UInt32  *outMaxPacketSi ze  ); 


rtpm 

The  component  instance  of  the  media  packetizer. 
outMaxPacketSi  ze 

On  return,  a  pointer  to  a  32-bit  integer  containing  the  maximum  packet  size,  in 
bytes,  that  the  packetizer  is  set  to  create. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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RTPMPGetMediaType 


Discussion 

The  maximum  allowable  packet  size  can  change  during  a  presentation,  so  you 
should  obtain  this  value  immediately  before  using  it. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 

See  Also 

You  can  set  the  maximum  packet  size  by  calling  RTPMPSetMaxPacketSi  ze  (III— 1477). 


RTPMPGetMediaType 


Obtains  the  data  type  being  handled  by  a  media  packetizer. 

ComponentResul t  RTPMPGetMediaType  ( 

RTPMedi aPacketi zer  rtpm, 

OSType  *outMedi aType  ); 


rtpm 

The  component  instance  of  the  media  packetizer. 
outMedi aType 

On  return,  a  pointer  to  the  media's  data  type,  such  as  Vi  deoMedi  aType  or 
SoundMedi  aType;  see  "Data  References"  (IV-2661). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

The  media's  data  type  must  be  set  prior  to  calling  RTPMPSetSampl  eData  (III— 1480).  It 
cannot  change  afterward. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 

See  Also 

You  can  set  the  media's  data  type  by  calling  RTPMPSetMedi  aType  (III— 1478). 
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RTPMPGetPacketBuilder 


RTPMPGetPacketBuilder 


Obtains  the  component  instance  of  the  packet  builder  component  being  used  by  a 
media  packetizer. 

ComponentResul t  RTPMPGetPacketBuilder  ( 

RTPMedi aPacketi zer  rtpm, 

Componentlnstance  *outPacketBui 1 der  ); 


rtpm 

The  component  instance  of  the  media  packetizer  whose  packet  builder  you  are 
interested  in. 

outPacketBui 1 der 

On  return,  a  pointer  to  the  component  instance  of  the  packet  builder 
component  in  use  by  this  media  packetizer. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 

See  Also 

You  can  set  a  packet  builder  instance  by  calling  RTPMPSetPacketBui  1  der  (III— 1479). 


RTPMPGetSettings  AsT  ext 


Return  the  media-specific  settings  of  a  media  packetizer  as  text  in  a  format 
presentable  to  the  user. 

ComponentResul t  RTPMPGetSettingsAsText  ( 

RTPMedi aPacketi zer  rtpm, 

Handle  *text  ); 


rtpm 

The  component  instance  of  a  media  packetizer. 

text 

Return  a  handle  to  a  copy  of  your  user  settings  in  text  format.  The  text  is 
formatted  as  simple  array  of  characters.  There  is  no  size  byte  or  null 
termination.  Allocate  the  handle  to  fit  the  text  precisely. 


III-1468 
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RTPMPGetSettingsIntoAtomContainerAtAtom 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  expects  you  to  return  your  user  settings  as  text.  It  should  be  called 
only  if  the  media  packetizer  supports  packetizer-specific  settings.  To  determine  if 
your  media  packetizer  supports  this  function,  the  application  may  call 
RTPMPHasCharacteri  sti  c  (III — 1471). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 

See  Also 

Packetizer-specific  settings  can  be  set  by  RTPMPSetSetti  ngsFromAtomContai  nerAtAtom 
(III— 1481).  You  may  be  asked  to  bring  up  a  dialog  which  allows  the  user  to  change 
the  settings  through  RTPMPDollserDi  al  og  (III— 1463). 


RTPMPGetSettingsIntoAtomContainerAtAtom 


Obtains  the  media-specific  setting  of  a  media  packetizer. 

ComponentResul t  RTPMPGetSetti ngs IntoAtomContai nerAtAtom  ( 
RTPMedi aPacketi zer  rtpm, 

QTAtomContai ner  inOutContainer, 

QTAtom  inParentAtom  ); 


rtpm 

The  component  instance  of  the  media  packetizer. 
i nOutContai ner 

The  atom  container  that  holds  the  settings  atom,  which  the  caller  must  allocate, 
i nParentAtom 

The  atom  that  will  hold  the  settings. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  should  be  called  only  if  the  media  packetizer  supports 
packetizer-specific  settings.  To  determine  if  a  media  packetizer  supports  this 
function,  call  RTPMPHasCharacteri  sti  c  (III— 1471). 

Version  Notes 

Introduced  in  QuickTime  4. 
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RTPMPGetTimeBase 


Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 

See  Also 

You  can  set  packetizer-specific  settings  by  calling 

RTPMPSetSettingsFromAtomContainerAtAtom  (III— 1481).  To  bring  up  a  dialog  which 
the  user  can  use  to  change  the  settings,  call  RTPMPDoUserDi  al  og  (III— 1463). 


RTPMPGetTimeBase 


Returns  the  time  base  passed  to  a  media  packetizer  by  RTPMPSetT i  meBase  (III— 1481). 

ComponentResul t  RTPMPGetTimeBase  ( 

RTPMedi aPacketi zer  rtpm, 

TimeBase  *outTimeBase  ); 


rtpm 

The  component  instance  of  your  media  packetizer. 
outT i meBase 

A  pointer  to  the  time  base  passed  to  you  by  RTPMPSetT i  meBase  (III— 1481). 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 

See  Also 

For  the  corresponding  set  function,  see  RTPMPSetT i meBase  (III— 1481). 


RTPMPGetTimeScale 


Obtains  the  time  scale  in  use  by  a  media  packetizer. 

ComponentResul t  RTPMPGetTimeScale  ( 

RTPMedi aPacketi zer  rtpm, 

TimeScale  *outTimeScal e  ); 


rtpm 

The  component  instance  of  media  packetizer  component. 
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RTPMPHasCharacteristic 


outT i meScal e 

On  return,  contains  a  pointer  to  the  time  scale  in  use  by  the  packetizer.  The  time 
scale  indicates  the  number  of  time  units  that  pass  in  one  second  when  the  media 
is  playing  at  a  rate  of  1. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 

See  Also 

For  the  corresponding  set  function,  see  RTPMPSetTi meScal  e  (III— 1482). 


RTPMPHasCharacteristic 


Determines  whether  a  media  packetizer  has  a  particular  characteristic,  such  as 
whether  it  supports  a  user  settings  dialog. 

ComponentResul t  RTPMPHasCharacteristic  ( 

RTPMedi aPacketi zer  rtpm, 

OSType  inSelector, 

Boolean  *outHas!t  ); 


rtpm 

The  component  instance  of  the  media  packetizer. 
i nSel ector 

A  selector  for  the  characteri  sti  c  you  want  to  know  about. 
outHas It 

On  return,  contains  a  Bool  ean  value  that  is  TRUE  if  the  media  packetizer  has  this 
characteristic,  FALSE  otherwise. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inSelector  Constants 

kRTPMPNoSampl eDataRequi redCharacteri sti c 

The  media  packetizer  does  not  require  the  actual  sample  data  to  perform 
packetization;  the  caller  can  pass  in  N I L  data  pointers  instead  of  pointers  to  the 
actual  media  data.  See  RTPMPSetSampl  eData  (III— 1480). 
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RTPMPIdle 


kRTPMPHas User Sett i ngsDi al ogCharacteri sti c 

The  media  packetizer  supports  RTPMPDoUserDi  al  og  (III— 1463), 

RTPMPGetSetti ngs IntoAtomContai nerAtAtom  (III — 1469),  and 
RTPMPSetSetti ngsFromAtomContai nerAtAtom  (III — 1481). 

kRTPMPPrefersReliableTransportCharacteristic 

The  media  packetizer  prefers  its  data  to  be  sent  reliably,  such  as  in  text  or  music 
tracks. 

kRTPMPRequiresOutOfBandDimensionsCharacteristic 

The  original  visual  dimensions  of  the  media  data  cannot  be  determined  simply 
by  looking  at  the  media  packets;  they  must  be  transmitted  by  some  other 
method. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


RTPMPIdle 


Called  periodically  in  your  event  loop  to  allocate  time  to  each  media  packetizer. 

ComponentResul t  RTPMPIdle  ( 

RTPMedi aPacketi zer  rtpm, 

SInt32  inFlags, 

SInt32  *outFlags  ); 


rtpm 

The  component  instance  of  the  media  packetizer. 
i  n FI  ags 

There  are  currently  no  defined  flags. 
outFl  ags 

On  return,  contains  a  pointer  to  a  signed  32-bit  integer  that  holds  a  flag  (see 
below)  from  the  packetizer. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

outFlags  Constant 

kRTPMPSti 11  Processing Data 

If  this  flag  is  set,  there  is  still  data  in  the  queue  to  be  processed.  Call  this  function 
repeatedly  until  this  flag  is  not  returned. 
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RTPMPInitialize 


Discussion 

The  packetizer  will  use  this  time  to  process  the  data  in  its  buffer.  If  the  data  has  not 
all  been  processed,  this  function  returns  the  kRTPMPSti  11  Process ingData  flag.  Data 
is  placed  in  the  buffer  by  RTPMPSetSampl  eData  (III— 1480). 

Special  Considerations 

The  packetizer  may  make  calls  to  the  packet  builder  in  response  to  this  call. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


RTPMPInitialize 


Initializes  a  media  packetizer  component. 

ComponentResul t  RTPMPInitialize  ( 
RTPMedi aPacketi zer  rtpm, 

SInt32  inFlags  ); 


rtpm 

The  component  instance  of  the  media  packetizer. 
i n FI  ags 

A  signed  32-bit  integer  containing  the  flags  (see  below)  you  wish  to  pass  to  the 
packetizer  at  start-up. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inFlags  Constant 

kRTPMPReal ti meModeFl ag 

The  packetizer  is  being  called  in  a  real-time  situation  (for  example,  live 
broadcasting). 

Discussion 

The  calling  component  must  call  this  function  before  sending  any  data  to  a  media 
packetizer  or  making  any  RTPMPSet  calls.  The  calling  component  then  calls 
RTPMPSetSampl  eData  (III— 1480)  and  RTPMPIdle  (III— 1472)  repeatedly.  The  calling 
component  passes  sample  data  (obtained,  for  example,  from  GetMedi  aSampl  e 
(1-443)),  to  the  media  packetizer  by  calling  RTPMPSetSampl  eData.  If 
RTPMPSetSampl  eData  or  RTPMPIdl  e  return  the  flag  kRTPMPSti  1 1  Processi  ngData,  then 
the  calling  component  should  call  RT  P  M  P I  d  1  e;  if  not,  it  is  free  to  call 
RTPMPSetSampl eData  again. 
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RTPMPPreflightMedia 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


RTPMPPreflightMedia 


Determines  whether  your  packetizer  can  work  with  a  given  media  type  and  sample 
description. 

ComponentResul t  RTPMPPreflightMedia  ( 

RTPMedi aPacketi zer  rtpm, 

OSType  inMediaType, 

Sampl eDescri pti onHandl e  i nSampl eDescri pti on  ); 


rtpm 

The  component  instance  of  your  media  packetizer. 
i nMedi aType 

The  media  type,  such  as  '  vi  de see  "Data  References"  (IV-2661). 
inSampleDescription 

A  handle  to  the  Sampl  eDescri  pti  on  (IV-2414)  structure. 

function  result  Return  noErr  if  you  can  packetize  this  type  of  data;  return 
qtstlnsupportedFeatureErr  if  you  cannot.  See  "Error  Codes" 
(IV-2663). 

Discussion 

This  function  must  be  implemented  by  your  packetizer.  It  will  be  called  before  you 
are  asked  to  packetize  any  data. 

Version  Notes 

Introduced  in  QuickTime  4. 
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C  interface  file:  QTStreami  ngComponents .  h 


RTPMPReset 


Allows  a  media  packetizer  to  stop  packetizing  its  current  input,  set  its  state  to  idle, 
and  flush  its  input  buffer. 

ComponentResul t  RTPMPReset  ( 


III-1474 
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RTPMedi aPacketi zer  rtpm, 

SInt32  inFlags  ); 


rtpm 

The  component  instance  of  the  media  packetizer. 
i  n  FI  ags 

A  signed  32-bit  integer  containing  any  flags  you  are  passing  to  the  media 
packetizer.  There  are  currently  no  defined  flags. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  can  use  this  function  to  stop  the  media  packetizer  and  flush  its  input  buffer 
when  you  wish  to  stop  transmitting  immediately,  when  you  are  skipping  forward 
or  backward  in  the  stream,  or  if  the  network  data  connection  is  interrupted. 

Version  Notes 

Introduced  in  QuickTime  4. 
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RTPMPSetlnfo 


Sets  any  one  of  several  parameters  for  a  media  packetizer. 

ComponentResul t  RTPMPSetlnfo  ( 

RTPMedi aPacketi zer  rtpm, 

OSType  inSelector, 

const  void  *ioParams  ); 


rtpm 

The  component  instance  of  the  media  packetizer. 
i nSel ector 

A  selector  (see  below)  for  the  type  of  information  you  wish  to  set. 
i oParams 

A  pointer  to  a  data  structure  of  the  appropriate  type  for  the  information  you  are 
passing. 

function  result  Return  qtsBadSel  ectorErr  if  you  do  not  support  the  selector.  Return 
noErr  if  there  is  no  error.  See  "Error  Codes"  (IV-2663). 
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RTPMPSetlnfo 


inSelector  Constants 

kQTSSourceT  rackIDInfo 

The  source  track  ID  as  a  value  of  type  UInt32. 
kQTSSource Layer  Info 

The  source  layer  number  as  a  value  of  type  U I  nt  1 6. 
kQTSSource Language  Info 

The  source  language  as  a  value  of  type  U Inti 6;  see  "Localization  Codes" 
(IV-2673). 

kQTSSourceT  rackFlagsInfo 

The  source  track  flags  as  a  value  of  type  SInt32. 
kQTSSourceDi mens i ons Info 

The  source  dimensions  as  a  QTSDi mensi  onParams  (IV-2368)  structure. 
kQTSSource Vo 1 umeslnfo 

The  source  audio  volumes  as  a  QTSVol  umesParams  (IV-2390)  structure. 
kQTSSourceMatri xlnfo 

The  source  matrix  as  a  MatrixRecord  (IV-2304)  structure. 
kQTSSourceCl i pRectlnfo 

The  source  clipping  rectangle  as  a  Rect  (IV-2399)  structure. 
kQTSSourceGraphi csModelnfo 

The  source  graphics  mode  as  a  QTSGraphi  csModeParams  (IV-2372)  structure. 
kQTSSourceBoundi ngRectlnfo 

The  source  bounding  rectangle  as  a  Rect  (IV-2399)  structure. 
kQTSSourceScal elnfo 

The  source  scale  as  a  Point  (IV-2339)  structure. 
kQTSSourceUser Data  Info 

The  source  user  data  as  a  UserDataRecord  (IV-2496)  structure. 
kQTSSource I nputMapInfo 

The  source  input  map  as  a  QT  atom  container. 

Discussion 

This  function  is  used  to  pass  track-level  information  about  the  media  track  to  be 
packetized,  such  as  its  track  ID,  layer,  and  transformation  matrix.  Return 
qtsBadSelectorErr  unless  your  packetizer  is  able  to  transmit  this  kind  of  data  to 
your  reassembler  for  use  in  the  client  movie. 

Version  Notes 

Introduced  in  QuickTime  4. 
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Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 

See  Also 

For  the  corresponding  get  function,  see  RTPMPGetlnfo  (III— 1464). 


RTPMPSetMaxPacketDuration 


Sets  the  maximum  packet  duration  that  the  media  packetizer  is  to  use. 

ComponentResul t  RTPMPSetMaxPacketDuration  ( 

RTPMedi aPacketizer  rtpm, 

UInt32  i nMaxPacketDurati on  ); 


rtpm 

The  component  instance  of  the  media  packetizer. 
i nMaxPacketDurati on 

An  unsigned  32-bit  integer  containing  the  maximum  packet  duration  in 
milliseconds.  This  value  should  not  be  smaller  than  the  value  returned  from 
RTPMPGetlnfo  (III— 1464)  with  the  kRTPMPMi nPacketDurati  on  selector. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  maximum  packet  duration  cannot  be  changed  during  a  presentation,  and  this 
function  cannot  be  called  after  calling  RTPMPSetSampl  eData  (III— 1480). 

Special  Considerations 

If  RTPMPSetMaxPacketDurati  on  is  not  called,  a  default  value  will  be  used. 

Version  Notes 

Introduced  in  QuickTime  4. 
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See  Also 

For  the  corresponding  get  function,  see  RTPMPGetMaxPacketDurati  on  (III— 1466). 


RTPMPSetMaxPacketSize 

Sets  the  maximum  packet  size  for  packets  created  by  a  media  packetizer. 
ComponentResul t  RTPMPSetMaxPacketSize  ( 
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RTPMPSetMediaType 


RTPMedi aPacketi zer  rtpm, 

UInt32  i nMaxPacketSi ze  ); 


rtpm 

The  component  instance  of  the  media  packetizer. 
i nMaxPacketSi ze 

An  unsigned  32-bit  integer  specifying  the  maximum  size,  in  bytes,  of  packets  to 
be  created.  This  value  must  not  be  smaller  than  the  value  returned  from 
RTPMPGetlnfo  (III— 1464)  with  the  kRTPMPMi  nPayl  oadSi  ze  selector.  The  media 
packetizer  will  not  create  packets  larger  than  this  value.  The  limit  applies  only 
to  the  payload  data. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  maximum  packet  size  cannot  change  during  a  presentation.  Streaming  will  be 
most  efficient  if  this  value  is  set  to  the  largest  packet  size  that  can  traverse  the 
network  without  being  split.  RTPMPSetMaxPacketSize  may  not  be  called  after  calling 
RTPMPSetSampi  eData  (III — 1480). 

Special  Considerations 

If  RTPMPSetMaxPacketSi  ze  is  not  called,  a  default  value  will  be  used. 

Version  Notes 

Introduced  in  QuickTime  4. 
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See  Also 

For  the  corresponding  get  function,  see  RTPMPGetMaxPacketSi  ze  (III— 1466). 


RTPMPSetMediaT  ype 


Sets  the  type  of  media  that  a  media  packetizer  will  process. 

ComponentResul t  RTPMPSetMediaType  ( 

RTPMedi aPacketi zer  rtpm, 

OSType  inMediaType  ); 


rtpm 

The  component  instance  of  the  media  packetizer. 
i nMedi aType 

The  media  type;  see  "Data  References"  (IV-2661). 
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RTPMPSetPacketBuilder 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  media  type  must  be  set  prior  to  calling  RTPMPSetSampl  eData  (III— 1480)  and 
cannot  change  after  such  calls. 

Version  Notes 

Introduced  in  QuickTime  4. 
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See  Also 

For  the  corresponding  get  function,  see  RTPMPGetMediaType  (III— 1467). 


RTPMPSetPacketBuilder 


Selects  which  packet  builder  a  media  packetizer  will  use. 

ComponentResul t  RTPMPSetPacketBuilder  ( 

RTPMedi aPacketi zer  rtpm, 

Componentlnstance  i nPacketBui 1 der  ); 


rtpm 

The  component  instance  of  the  media  packetizer. 
i nPacketBui 1 der 

The  component  instance  of  the  packet  builder  component  to  use. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

A  media  packetizer  always  sends  its  output  to  a  packet  builder.  The  specified  packet 
builder  may  assemble  actual  RTP  packets,  or  it  may  use  information  about  the 
packet  to  build  a  hint  track.  You  must  set  the  packet  builder  using  this  call  prior  to 
any  calls  to  RTPMPSetSampl  eData  (III— 1480).  You  can  also  use  this  function  to 
dynamically  change  the  packet  builder  a  media  packetizer  uses. 

Version  Notes 

Introduced  in  QuickTime  4. 
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See  Also 

Use  RT  PM  PGet  Packet  Bui  1  der  (III— 1468)  to  get  the  packet  builder  currently  being  used. 
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RTPMPSetSampleData 


RTPMPSetSampleData 


Provides  sample  data  directly  to  a  media  packetizer  component. 

ComponentResul t  RTPMPSetSampleData  ( 

RTPMedi aPacketi zer  rtpm, 

const  RTPMPSampl eDataParams  *i nSampl eData  , 

SInt32  *outFlags  ); 


rtpm 

The  component  instance  of  the  media  packetizer. 

1 nSampl eData 

A  pointer  to  a  RTPMPSampl  eDataParams  (IV-2407)  structure  containing  the 
sample  data  you  are  passing.  Calling  this  routine  adds  data  cumulatively  to  any 
previous  calls  to  this  function.  The  data  can  contain  any  number  of  samples  (1 
or  more),  or  a  partial  sample. 
outFl  ags 

Flags  (see  below)  that  indicate  processing  status.  This  function  will  return 
kRTPMPWantsMoreDataFl  ag  if  it  has  completed  processing  of  all  pending  data. 
Otherwise,  you  must  make  calls  to  RT  P  M  P I  d  1  e  (III— 1472)  until  this  function  no 
longer  returns  kRTPMPSti  1 1  Processi  ngData. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

outFlags  Constants 

kRTPMPWantsMoreDataFl  ag 

Returned  if  this  function  has  completed  processing  of  all  pending  data. 
kRTPMPSti 11 Processi  ngData 

Returned  if  this  function  is  still  processing  data. 

Discussion 

This  routine  is  called  to  pass  media  data  directly  to  a  media  packetizer.  The 
packetizer  will  not  copy  this  data;  it  will  call  the  release  callback  when  it  is  finished 
with  it.  The  media  packetizer  may  or  may  not  make  calls  to  the  packet  builder  in 
response  to  this  call. 

Special  Considerations 

This  call  is  normally  followed  by  a  series  of  calls  to  RTPMPIdl  e  (III— 1472),  which 
grants  time  to  the  media  packetizer  in  order  to  process  the  data  passed  by  this 
function. 

Version  Notes 

Introduced  in  QuickTime  4. 
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RTPMPSetSettingsFromAtomContainerAtAtom 


Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


RTPMPSetSettingsFromAtomContainerAtAtom 


Sets  the  media-specific  settings  of  a  media  packetizer,  using  an  atom  inside  an  atom 
container. 

ComponentResul t  RTPMPSetSettingsFromAtomContai nerAtAtom  ( 

RTPMedi aPacketi zer  rtpm, 

QTAtomContai ner  inContainer, 

QTAtom  inParentAtom  ); 


rtpm 

The  component  instance  of  the  media  packetizer. 
i nContai ner 

The  atom  container  that  holds  the  settings  atom, 
i nParentAtom 

The  atom  that  holds  the  settings. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  should  be  called  only  if  the  media  packetizer  supports 
packetizer-specific  settings.  To  determine  if  a  media  packetizer  supports  this 
function,  call  RTPMPHasCharacteri  sti  c  (III— 1471). 

Version  Notes 

Introduced  in  QuickTime  4. 
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See  Also 

You  can  get  packetizer-specific  settings  with 

RTPMPGetSetti  ngs  IntoAtomContai  nerAtAtom  (III— 1469).  To  bring  up  a  dialog  which 
the  user  can  use  to  change  the  settings,  call  RTPMPDoUserDi  al  og  (III— 1463). 


RTPMPSetTimeBase 

Tells  your  packetizer  what  time  base  is  in  use  by  the  calling  application. 
ComponentResul t  RTPMPSetTimeBase  ( 
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RTPMPSetTimeScale 


RTPMedi aPacketi zer  rtpm, 

TimeBase  inTimeBase  ); 


rtpm 

Component  instance  of  your  packetizer. 
inTimeBase 

The  time  base  in  use  for  this  stream.  You  can  query  this  time  base  to  find  out 
the  current  time  in  the  stream. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  may  be  called  during  setup  for  a  live  transmission. 

Special  Considerations 

Your  packetizer  should  not  rely  on  receiving  this  call. 

Version  Notes 

Introduced  in  QuickTime  4. 
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See  Also 

For  the  corresponding  get  function,  see  RTPMPGetTimeBase  (III— 1470). 


RTPMPSetTimeScale 


Sets  the  time  scale  the  media  packetizer  will  use. 

ComponentResul t  RTPMPSetTimeScale  ( 

RTPMedi aPacketi zer  rtpm, 

TimeScale  inTimeScale  ); 


rtpm 

The  component  instance  of  the  media  packetizer. 
inTimeScale 

The  time  scale  to  use. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  time  scale  is  the  number  of  time  units  that  pass  in  one  second  when  the  media 
is  playing  at  a  rate  of  1 .  This  time  scale  gives  meaning  to  the  times  used  when  calling 
RTPMPSetSampl  eData  (III — 1480). 
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RTPPBAddPacketLiteralData 


Special  Considerations 

The  time  scale  must  be  set  before  calling  RTPMPSetSampl  eData  (III— 1480). 

Version  Notes 
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See  Also 

For  the  corresponding  get  function,  see  RTPMPGetT i  meScal  e  (III— 1470). 


RTPPBAddPacketLiteralData 


Passes  literal  data  directly  to  a  packet  builder  component. 


ComponentResul t  RTPPBAddPacketLiteralData  ( 


RTPPacketBui 1 der 
SInt32 

RTPPacketGroupRef 

RTPPacketRef 

UInt8 

UInt32 

RTP Packet  Repea ted Data  Ref 


rtpb , 
i  n  FI  ags  , 
i nPacketGroup , 
i nPacket , 

*i  nData , 
i nData  Length , 
*outDataRef  ); 


rtpb 

The  component  instance  of  the  packet  builder  component, 
i n FI  ags 

A  signed  32-bit  integer  containing  any  flags  you  are  passing.  There  are 
currently  no  defined  flags, 
l nPacketGroup 

The  packet  group  containing  the  packet  into  which  the  data  will  be  placed.  This 
is  normally  a  reference  returned  by  RTPPBBegi  nPacketGroup  (III— 1490). 

i nPacket 

The  RTP  packet  into  which  the  data  will  be  placed.  This  is  normally  a  reference 
returned  by  RTPPBBegi  nPacket  (III— 1489). 

i nData 

A  pointer  to  the  data  you  are  passing, 
i nData  Length 

An  unsigned  32-bit  integer  containing  the  length,  in  bytes,  of  the  data  you  are 
passing. 


Inside  QuickTime:  Functions  R-Z 


III-1483 


RTPPBAddPacketRepeatedData 


outDataRef 

On  return,  contains  a  pointer  to  a  data  reference.  Use  this  reference  if  you  wish 
to  later  tell  the  packet  builder  to  use  this  same  data  again,  without  having  to 
literally  pass  the  data  again.  Pass  in  N I L  if  you  do  not  need  the  packet  builder  to 
repeat  the  data.  If  you  do  not  pass  in  N I L,  you  must  dispose  of  the  data  explicitly 
by  calling  RTPPBRel  easeRepeatedData  (III— 1497). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  will  return  a  reference  which  can  be  used  to  specify  the  same  data 
repeatedly  without  having  to  pass  in  the  data  again.  This  is  done  by  calling 
RTPPBAddPacketRepeatedData  (III— 1484)  with  the  reference  which  was  returned  by 
this  function.  For  example,  you  can  use  this  function  to  insert  static  header 
information  into  a  packet  prior  to  inserting  media  sample  data.  It  will  return  a  data 
reference  you  can  use  to  insert  the  same  static  information  into  later  packets. 

Special  Considerations 

To  specify  media  data  to  be  placed  in  a  packet,  a  media  packetizer  should  call 
RTPPBAddPacketSampl  eData  (III — 1485). 

Version  Notes 
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See  Also 

When  a  reference  returned  by  RTPPBAddPacketLi  teral  Data  is  no  longer  needed,  it 
should  be  disposed  of  by  using  the  call  RTPPBRel  easeRepeatedData  (III— 1497). 


RTPPBAddPacketRepeatedData 


Tells  a  packet  builder  component  to  insert  previously-specified  data  into  a  packet. 


ComponentResul t  RTPPBAddPacketRepeatedData  ( 


RTPPacketBui 1 der 
SInt32 

RTPPacketGroupRef 

RTPPacketRef 

RTPPacket Repeated Data  Ref 


rtpb , 
i  n  FI  ags  , 
i nPacketGroup , 
i  nPacket , 
i nDataRef  ) ; 


rtpb 

The  component  instance  of  the  packet  builder  component. 


III-1484 
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RTPPBAddPacketSampleData 


i  n FI  ags 

A  signed  32-bit  integer  containing  any  flags  you  are  passing.  There  are 
currently  no  defined  flags, 
i nPacketGroup 

The  packet  group  containing  the  packet  into  which  the  data  will  be  placed.  This 
is  normally  a  reference  returned  by  RTPPBBegi  nPacketGroup  (III— 1490). 

i nPacket 

The  RTP  packet  into  which  the  data  will  be  placed.  This  is  normally  a  reference 
returned  by  RTPPBBegi  nPacket  (III— 1489). 
i nDataRef 

A  reference  to  the  data  to  repeat.  This  is  normally  a  data  reference  returned  by 
RTP  PB  Add  Packet  Li  teralData  (III — 1483)  or  RTPPBAddPacketSampl  eData  (III — 1485). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Use  this  function  to  cause  a  packet  builder  component  to  repeatedly  insert  the  same 
data  into  packets  without  having  to  pass  the  data  each  time.  This  is  typically  done 
to  repeat  static  header  information  into  a  series  of  packets,  or  to  insert 
previously-sent  sample  data  into  a  redundant  packet.  The  data  is  first  specified  by 
a  call  to  RTPPBAddPacketLi  teral  Data  (III— 1483)  or  RTPPBAddPacketSampl  eData 
(III— 1485),  which  inserts  the  data  the  first  time  and  returns  a  data  reference.  The  data 
reference  is  then  used  with  this  function  to  send  the  data  again. 

Special  Considerations 

When  you  are  done  sending  the  repeated  data,  release  the  data  structure  by  calling 
RTPPBRel  easeRepeatedData  (III — 1497). 

Version  Notes 
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RTPPBAddPacketSampleData 


Commands  a  packet  builder  component  to  insert  media  sample  data  into  a  packet. 


ComponentResul t  RTPPBAddPacketSampleData  ( 
RTPPacketBui 1 der  rtpb, 

SInt32  inFlags, 

RTPPacketGroupRef  i nPacketGroup , 

RTPPacketRef  inPacket, 
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RTPPBAddPacketSampleData 


RTPMPSampleDataParams 

UInt32 

UInt32 

RTPPacket Repeated Data  Ref 


*i n Samp 1 e Data  Pa  rams , 
i nSampl eOffset , 
in Samp 1 eData Length , 
*outDataRef  )  ; 


rtpb 

The  component  instance  of  the  packet  builder  component, 
i  n FI  ags 

A  signed  32-bit  integer  containing  any  flags  you  are  passing.  There  are 
currently  no  defined  flags, 
i nPacketGroup 

The  packet  group  containing  the  packet  into  which  the  data  will  be  placed.  This 
is  normally  a  reference  returned  by  RTPPBBegi  nPacketGroup  (III— 1490). 
i nPacket 

The  RTP  packet  into  which  the  data  will  be  placed.  This  is  normally  a  reference 
returned  by  RTPPBBegi  nPacket  (III— 1489). 

i nSampl eData Pa  rams 

A  pointer  to  a  RTPMPSampl  eData  Pa  rams  (IV-2407)  structure  for  the  sample  data 
you  are  inserting, 
i nSampl eOffset 

A  32-bit  unsigned  integer  containing  the  offset  into  the  sample  media,  in  bytes, 
i nSampl eData Length 

A  32-bit  unsigned  integer  specifying  the  number  of  bytes  of  media  sample  data 
to  insert  into  the  packet. 

outDataRef 

On  return,  contains  a  pointer  to  a  data  reference.  Use  this  reference  if  you  wish 
to  later  tell  the  packet  builder  to  use  this  same  sample  data  again,  without 
having  to  literally  pass  the  data  again.  Pass  in  N I L  if  you  do  not  need  the  packet 
builder  to  repeat  the  data.  If  you  do  not  pass  in  N I L  ,  you  must  dispose  of  the 
data  explicitly  by  calling  RTPPBRel  easeRepeatedData  (III— 1497). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  will  return  a  reference  which  can  be  used  to  specify  the  same  data 
repeatedly  without  having  to  pass  in  the  data  again.  The  media  packetizer  specifies 
the  offset  into  the  media  and  the  length  of  the  sample  to  insert.  You  can  insert  data 
repeatedly  by  calling  RTPPBAddPacketRepeatedData  (III— 1484)  with  the  reference 
which  was  returned  by  RTPPBAddPacketLi  teral  Data  (III— 1483). 


III-1486 
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RTPPBAddPacketSampleData64 


Special  Considerations 

When  a  reference  is  no  longer  needed,  it  should  be  disposed  of  by  using  the  call 
RTPPBRel  easeRepeatedData  (III — 1497). 

Version  Notes 

Introduced  in  QuickTime  4. 
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RTPPBAddPacketSampleData64 


Provides  a  64-bit  version  of  RTPPBAddPacketSampl  eData  (III— 1485)  for  large  sample 
media. 


ComponentResul  t  RTPPBAddPacketSampl eData64  ( 


RTPPacketBui 1 der 
SInt32 

RTPPacketGroupRef 
RTPPacketRef 
RTPMPSampleDataParams 
const  UInt64 
UInt32 

RTP Packet Repea ted Data  Ref 


rtpb , 
i  n FI  ags  , 
i nPacketGroup , 
i nPacket , 

*inSampleDataParams, 
*i nSampl eOf f set , 
i nSampl eData Length , 
*outDataRef  ); 


rtpb 

The  component  instance  of  the  packet  builder  component, 
i  n FI  ags 

A  signed  32-bit  integer  containing  any  flags  you  are  passing.  There  are 
currently  no  defined  flags, 
i nPacketGroup 

The  packet  group  containing  the  packet  into  which  the  data  will  be  placed.  This 
is  normally  a  reference  returned  by  RTPPBBegi  nPacketGroup  (III— 1490). 

l nPacket 

The  RTP  packet  into  which  the  data  will  be  placed.  This  is  normally  a  reference 
returned  by  RTPPBBegi  nPacket  (III— 1489). 

i nSampl eDataParams 

A  pointer  to  a  RTPMPSampl  eDataParams  (IV-2407)  structure  for  the  sample  data 
you  are  inserting, 
i nSampl eOf f set 

A  64-bit  unsigned  integer  containing  the  offset  into  the  sample  media,  in  bytes. 
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III-1487 


RTPPBAddRepeatPacket 


in Samp 1 eData Length 

A  32-bit  unsigned  integer  specifying  the  number  of  bytes  of  media  sample  data 
to  insert  into  the  packet. 
outDataRef 

On  return,  contains  a  pointer  to  a  data  reference.  Use  this  reference  if  you  wish 
to  later  tell  the  packet  builder  to  use  this  same  sample  data  again,  without 
having  to  literally  pass  the  data  again.  Pass  in  N I L  if  you  do  not  need  the  packet 
builder  to  repeat  the  data.  If  you  do  not  pass  in  N I L  ,  you  must  dispose  of  the 
data  explicitly  by  calling  RTPPBRel  easeRepeatedData  (III— 1497). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 
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See  Also 

For  details  of  using  this  function,  see  RTPPBAddPacketSampl  eData  (III— 1485). 


RTPPBAddRepeatPacket 

Undocumented 


ComponentResul t  RTPPBAddRepeatPacket  ( 


RTPPacketBui 1 der 
SInt32 

RTPPacketGroupRef 
RTPPacketRef 
TimeVal ue 
UInt32 


rtpb , 
i  n FI  ags  , 
i nPacketGroup , 
i nPacket , 

i nTransmi ssi onOffset , 
i nSequenceNumber  ) ; 


rtpb 

The  component  instance  of  the  packet  builder  component, 
i  n FI  ags 

A  signed  32-bit  integer  containing  any  flags  you  are  passing.  There  are 
currently  no  defined  flags. 

i nPacketGroup 

The  packet  group  containing  the  packet  into  which  the  data  will  be  placed.  This 
is  normally  a  reference  returned  by  RTPPBBegi  nPacketGroup  (III— 1490). 


III-1488 
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RTPPBBeginPacket 


i nPacket 

The  RTP  packet  into  which  the  data  will  be  placed.  This  is  normally  a  reference 
returned  by  RTPPBBeginPacket  (III— 1489). 
i nTransmi ssi onOf f set 
Undocumented 
l nSequenceNumber 
Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 
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RTPPBBeginPacket 


Tells  a  packet  builder  to  cr 

ComponentResul t  RTPPBBeg 
RTPPacketBui 1 der 
SInt32 

RTPPacketGroupRef 
UInt32 

RTPPacketRef 


;ate  a  new  packet. 

nPacket  ( 
rtpb , 
i  n FI  ags  , 
i nPacketGroup , 
i nPacketMedi aData Length, 
*outPacket  ); 


rtpb 

The  component  instance  of  the  packet  builder  component, 
i  n FI  ags 

A  signed  32-bit  integer  containing  any  flags  you  are  passing.  There  are 
currently  no  defined  flags, 
i nPacketGroup 

The  packet  group  containing  the  new  packet.  This  is  normally  a  reference 
returned  by  RTPPBBegi  nPacketGroup  (III— 1490). 

i nPacketMedi aData Length 

An  unsigned  32-bit  integer  specifying  the  maximum  length  of  data  that  will  be 
inserted  into  this  packet.  This  includes  the  data  for  all  subsequent 
RTPPBAddPacketLi  teral  Data  (III — 1483),  RTPPBAddPacketSampl  eData  (III — 1485), 
and  RTPPBAddPacketRepeatedData  (III— 1484)  calls  until  the  packet  is  closed.  The 
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RTPPBBeginPacketGroup 


value  of  this  parameter  maybe  larger,  but  must  not  be  smaller,  than  the  amount 
of  data  inserted  in  the  packet. 

outPacket 

On  return,  contains  a  pointer  to  the  packet.  Use  this  reference  to  insert  data  into 
the  packet. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  media  packetizer  uses  this  function  to  create  each  new  packet,  before  inserting 
any  literal,  repeated,  or  sample  data.  A  call  to  RTPPBBeginPacketGroup  (III— 1490) 
must  be  made  before  creating  the  first  packet  in  a  group.  Data  can  be  inserted  into 
the  packet  using  RTPPBAddPacketLi  teral  Data  (III— 1483), 

RTPPBAddPacketRepeatedData  (III — 1484),  or  RTPPBAddPacketSampl  eData  (III — 1485). 
When  the  packet  is  complete,  call  RTPPBEndPacket  (III— 1491). 

Version  Notes 

Introduced  in  QuickTime  4. 
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RTPPBBeginPacketGroup 


Tells  a  packet  builder  to  create  a  new  packet  group. 


ComponentResul t  RTPPBBeginPacketGroup  ( 
RTPPacketBui 1 der  rtpb, 

SInt32  inFlags, 

UInt32  i nTi meStamp , 

RTPPacketGroupRef  *outPacketGroup  ) ; 


rtpb 

The  component  instance  of  the  packet  builder  component, 
i  n FI  ags 

A  signed  32-bit  integer  containing  any  flags  you  are  passing.  There  are 
currently  no  defined  flags, 
i nT i meStamp 

A  unsigned  32-bit  integer  containing  the  time  stamp  for  this  packet  group. 


III-1490 
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RTPPBEndPacket 


outPacketGroup 

On  return,  contains  a  pointer  to  a  reference  to  the  packet  group.  Use  this  data 
reference  when  creating  a  new  packet  or  inserting  data  into  a  packet  that 
belongs  to  this  group. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

A  media  packetizer  creates  a  packet  group  using  this  function.  The  data  reference 
returned  by  this  function  is  then  used  to  create  a  series  of  packets  that  belong  to  this 
group.  The  data  reference  is  also  required  when  inserting  data  into  packets. 

Special  Considerations 

When  the  packet  group  is  complete,  call  RTPPBEndPacketGroup  (III— 1492). 

Version  Notes 

Introduced  in  QuickTime  4. 
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RTPPBEndPacket 


Tells  a  packet  builder  that  a  packet  is  complete. 


ComponentResul t  RTPPBEndPacket  ( 


RTPPacketBui 1 der 
SInt32 

RTPPacketGroupRef 

RTPPacketRef 

UInt32 

UInt32 


rtpb , 
i  n FI  ags  , 
i nPacketGroup , 
i nPacket , 
i nT i meOf f set , 
inDuration  ); 


rtpb 

The  component  instance  of  the  packet  builder  component, 
i  nFl  ags 

A  signed  32-bit  integer  containing  any  flags  you  are  passing.  There  are 
currently  no  defined  flags. 

i nPacketGroup 

The  packet  group  containing  the  new  packet.  This  is  normally  a  reference 
returned  by  RTPPBBegi  nPacketGroup  (III— 1490). 
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III-1491 


RTPPBEndPacketGroup 


i  nPacket 

The  RTP  packet  containing  the  data.  This  is  normally  a  reference  returned  by 
RTPPBBegi nPacket  (III — 1489). 

fnTimeOffset 

The  time  offset  at  which  the  media  sample  data  contained  in  this  packet  begins, 
in  milliseconds.  This  offset  is  added  to  the  RTP  transmission  time  to  determine 
when  to  send  the  packet. 

i nDurati on 

The  duration  of  this  packet,  specified  in  milliseconds. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Call  this  function  once  when  each  packet  is  complete. 

Version  Notes 
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RTPPBEndPacketGroup 


Tells  a  packet  builder  component  that  a  packet  group  is  complete. 

ComponentResul t  RTPPBEndPacketGroup  ( 

RTPPacketBui 1 der  rtpb, 

SInt32  inFlags, 

RTPPacketGroupRef  i nPacketGroup  ); 


rtpb 

The  component  instance  of  the  packet  builder  component, 
i  n  FI  ags 

A  signed  32-bit  integer  containing  any  flags  you  are  passing.  There  are 
currently  no  defined  flags. 

i nPacketGroup 

A  data  reference  to  the  packet  group  being  ended.  This  is  normally  a  data 
reference  returned  by  RTPPBBegi  nPacketGroup  (III— 1490). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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RTPPB  G  etCallb  ack 


Discussion 

This  function  should  be  called  when  all  the  packets  in  a  group  are  complete  and  the 
media  packetizer  is  ready  either  to  create  a  new  packet  group  or  to  terminate  the 
stream. 

Version  Notes 

Introduced  in  QuickTime  4. 
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RTPPBGetCallback 


Gets  the  callback  used  to  communicate  with  the  caller  of  a  media  packetizer. 

ComponentResul t  RTPPBGetCallback  ( 

RTPPacketBui 1 der  rtpb, 

RTPPBCal 1 backUPP  *outCal 1  back, 

void  **outRefCon  ); 


rtpb 

The  component  instance  of  the  packet  builder  component. 
outCal 1  back 

A  pointer  to  an  RTPPBCal  1  backProc  (III— 2133)  callback. 
outRefCon 

A  handle  to  any  data  your  callback  needs. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 
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See  Also 

For  the  corresponding  set  function,  see  RTPPBSetCal  1  back  (III— 1497). 


RTPPBGetlnfo 


Gets  information  about  a  streaming  packet  builder. 

ComponentResul t  RTPPBGetlnfo  ( 

RTPPacketBui 1 der  rtpb. 
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III-1493 


RTPPBGetPacketSequenceNumber 


OSType  InSelector, 

voi d  *i oParams  ) ; 

rtpb 

The  component  instance  of  the  packet  builder  component. 

1 nSel ector 

A  constant  (see  below)  that  defines  the  type  of  information  to  retrieve, 
i oParams 

A  pointer  to  the  retrieved  information. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inSelector  Constant 

kRTPBufferDel ay  Info 

A  U I  n  1 3  2  value  that  represents  the  buffer  delay  in  the  current  time  scale. 

Version  Notes 
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See  Also 

For  the  corresponding  set  function,  see  RTPPBSetlnfo  (III— 1498). 


RTPPBGetPacketSequenceNumber 


Gets  the  relative  sequence  number  for  a  streaming  packet. 


Component Res u 1 t  RTPPBGetPacketSequenceNumber 


RTPPacketBui 1 der 
SInt32 

RTPPacketGroupRef 

RTPPacketRef 

UInt32 


rtpb , 
i  nFl  ags , 
i nPacketGroup , 
i nPacket , 

*out Sequence Number 


( 


) : 


rtpb 

The  component  instance  of  the  packet  builder  component, 
i  nFl  ags 

Undocumented 
i nPacketGroup 

A  data  reference  to  a  packet  group.  This  is  normally  a  data  reference  returned 
by  RTPPBBegi  nPacketGroup  (III— 1490). 


III-1494 
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RTPPBGetPacketTimeStampOffset 


i nPacket 

The  RTP  packet.  This  is  normally  a  reference  returned  by  RTPPBBegi  nPacket 
(III— 1489). 

outSequenceN umber 

A  pointer  to  the  sequence  number. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 
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See  Also 

For  the  corresponding  set  function,  see  RTPPBSetPacketSequenceNumber  (III— 1499). 


RTPPBGetPacketTimeStampOffset 


Undocumented 


Component Res ul t  RTPPBGetPacketT l meStampOf f set 


RTPPacketBui 1 der 
SInt32 

RTPPacketGroupRef 

RTPPacketRef 

SInt32 


rtpb , 
i  n Ft  ags  , 
i nPacketGroup , 
i nPacket , 

*outTi meStampOf f set 


( 


rtpb 

The  component  instance  of  the  packet  builder  component, 
i  n Ft  ags 

A  signed  32-bit  integer  containing  any  flags  you  are  passing.  There  are 
currently  no  defined  flags, 
i nPacketGroup 

The  packet  group  containing  the  packet  of  interest.  This  is  normally  a  reference 
returned  by  RTPPBBegi  nPacketGroup  (III— 1490). 

i nPacket 

The  RTP  packet  of  interest.  This  is  normally  a  reference  returned  by 
RTPPBBegi  nPacket  (III— 1489). 

outTi meStampOf f set 
Undocumented 


Inside  QuickTime:  Functions  R-Z 


III-1495 


RTPPBGetSampleData 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Version  Notes 
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RTPPB  GetSampleData 


Undocumented 

ComponentResul t  RTPPBGetSampl eData  ( 

RTPPacketBui 1 der  rtpb, 

RTPMPSampleDataParams  *inParams , 
const  UInt64  *inStartOffset , 

UInt8  *outDataBuffer , 

UInt32  i nBytesToRead , 

UInt32  *outBytesRead , 

SInt32  *outFlags  ); 

rtpb 

The  component  instance  of  the  packet  builder  component, 
i nParams 

A  pointer  to  a  RTPMPSampleDataParams  (IV-2407)  structure, 
i nStartOffset 

Undocumented 

outDataBuffer 

Undocumented 
i nBytesToRead 

Undocumented 

outBytesRead 

Undocumented 
outFl  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 
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RTPPBReleaseRepeatedData 


RTPPBReleaseRepeatedData 


Lets  a  packet  builder  deallocate  data  that  will  no  longer  be  used. 

ComponentResul t  RTPPBReleaseRepeatedData  ( 

RTPPacketBui 1 der  rtpb, 

RTPPacketRepeatedDataRef  inDataRef  ); 


rtpb 

The  component  instance  of  the  packet  builder  component, 
i nDataRef 

The  data  reference  to  the  repeated  data.  This  is  normally  a  data  reference 
returned  by  RTPPBAddPacketLi  teral  Data  (III— 1483)  or  RTPPBAddPacketSampl  eData 
(III— 1485). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  must  release  the  data  if  you  have  allowed  RTPPBAddPacketLi  teral  Data  (III— 1483) 
or  RTPPBAddPacketSampl  eData  (III— 1485)  to  return  a  data  reference,  even  if  you  have 
not  called  RTPPBAddPacketRepeatedData  (III-1484)must  either  pass  NIL  to  the  data 
reference  when  adding  literal  or  sample  data,  or  you  must  release  the  data  by 
calling  this  function. 

Version  Notes 

Introduced  in  QuickTime  4. 
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RTPPBSetCallback 


Sets  the  callback  used  to  communicate  with  the  caller  of  a  media  packetizer. 

ComponentResul t  RTPPBSetCallback  ( 

RTPPacketBui 1 der  rtpb, 

RTPPBCal 1 backUPP  inCallback, 

void  *1nRefCon  ); 


rtpb 

The  component  instance  of  the  packet  builder  component. 
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III-1497 


RTPPBSetlnfo 


i nCal 1  back 

A  Universal  Procedure  Pointer  that  references  anRTPPBCallbackProc  (III— 2133) 
callback, 
i nRefCon 

A  pointer  to  any  data  your  callback  needs. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 
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See  Also 

For  the  corresponding  get  function,  see  RTPPBGetCal  1  back  (III— 1493). 


RTPPBSetlnfo 


Sets  information  for  a  streaming  packet  builder. 

ComponentResul t  RTPPBSetlnfo  ( 

RTPPacketBui 1 der  rtpb, 

OSType  inSelector, 

voi d  *1 oParams  ) ; 


rtpb 

The  component  instance  of  the  packet  builder  component. 

1 nSel ector 

A  constant  (see  below)  that  defines  the  type  of  information  to  set. 

1 oParams 

A  pointer  to  the  information. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inSelector  Constant 

kRTPBufferDel ay  Info 

A  U I  n  1 3  2  value  that  represents  the  buffer  delay  in  the  current  time  scale. 
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III-1498 
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RTPPBSetPacketSequenceNumber 


See  Also 

For  the  corresponding  get  function,  see  RTPPBGetlnfo  (III— 1493). 


RTPPBSetPacketSequenceNumber 


Sets  the  relative  sequence  number  for  a  streaming  packet. 


Component  Res  ill  t  RTPPBSetPacketSequenceNumber 


RTPPacketBui 1 der 
SInt32 

RTPPacketGroupRef 

RTPPacketRef 

UInt32 


rtpb , 
i  n Ft  ags  , 
i nPacketGroup , 
i nPacket , 

i nSequenceNumber  ); 


( 


rtpb 

The  component  instance  of  the  packet  builder  component, 
i  n FI  ags 

Undocumented 
i nPacketGroup 

A  data  reference  to  a  packet  group.  This  is  normally  a  data  reference  returned 
by  RTPPBBegi nPacketGroup  (III— 1490). 

i nPacket 

The  RTP  packet.  This  is  normally  a  reference  returned  by  RTPPBBegi  nPacket 
(III— 1489). 

i nSequenceNumber 

The  sequence  number  to  be  set. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 
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See  Also 

For  the  corresponding  get  function,  see  RTPPBGetPacketSequenceNumber  (III— 1494). 


RTPPBSetPacketTimeStampOffset 

Undocumented 
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III-1499 


RTPRssm  Adj  ustPacketParams 


Component Res ul t  RTPPBSetPacketT i meStampOf f set 


RTPPacketBui 1 der 
SInt32 

RTPPacketGroupRef 

RTPPacketRef 

SInt32 


rtpb , 
i  n FI  ags  , 
i nPacketGroup , 
i nPacket , 

i nTi meStampOffset  ); 


( 


rtpb 

The  component  instance  of  the  packet  builder  component. 

1  n FI  ags 

A  signed  32-bit  integer  containing  any  flags  you  are  passing.  There  are 
currently  no  defined  flags. 

i nPacketGroup 

The  packet  group  containing  the  packet  of  interest.  This  is  normally  a  reference 
returned  by  RTPPBBegi  nPacketGroup  (III— 1490). 
i  nPacket 

The  RTP  packet  of  interest.  This  is  normally  a  reference  returned  by 
RTPPBBegi  nPacket  (III — 1489). 
i nT i meStampOffset 
Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 
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C  interface  file:  QTStreami  ngComponents .  h 


RTPRssm  Adj  ustPacketParams 


Called  by  the  base  reassembler  when  it  is  processing  a  packet,  allowing  your  packet 
reassembler  to  adjust  the  packet  parameters  before  the  packet  is  processed. 

ComponentResul t  RTPRssmAdjustPacketParams  ( 

RTPReassembl er  rtpr, 

RTPRssmPacket  *inPacket, 

SInt32  i  n FT  ags  ) ; 


rtpr 

The  component  instance  of  your  packet  reassembler 


III-1500 


Inside  QuickTime:  Functions  R-Z 


RTPRssmClearCachedPackets 


i nPacket 

A  pointer  to  the  packet  whose  parameters  can  be  adjusted, 
i  n  FI  ags 

A  signed  32-bit  integer  containing  any  flags  (see  below)  being  passed  to  your 
packet  reassembler. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inFlags  Constants 

Undocumented 

Undocumented 

Discussion 

Your  packet  reassembler  can  adjust  the  following  parameters  in  each  packet: 
payl  oadHeaderLength,  data  Length,  server  Edi  t  Pa  rams,  and  chunk  FI  ags.  If  your  packet 
reassembler  does  not  implement  this  function,  or  takes  no  action,  the  default  for 
these  parameters  will  be:  payl  oadHeaderLength  =  fixed  header  length  that  is  set 
(default  is  0);  dataLength  =  <packet  data>  -  transportHeaderLength  - 
payl  oadHeaderLength;  no  serverEditParams;  chunkFlags  =  0. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


RTPRssmClearCachedPackets 


Forces  the  base  reassembler  to  flush  all  packets  currently  queued  in  its  lists. 

ComponentResul t  RTPRssmClearCachedPackets  ( 

RTPReassembl er  rtpr, 

SInt32  inFlags  ); 


rtpr 

The  component  instance  of  the  base  reassembler, 
i  n FI  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Inside  QuickTime:  Functions  R-Z 


III-1501 


RTPRssmComputeChunkSize 


Discussion 

This  function  retains  the  last  sequence  number  and  related  information.  It  is  useful 
only  when  the  base  reassembler  is  operating  with  the 

kRTPRssmQueueAndllseMarkerBi  t FI  ag  flag  set;  see  RTPRssmSetCapabi  1  i  ti  es  (III — 1520). 

Version  Notes 

Introduced  in  QuickTime  4.1.  Replaces  RTPRssmFl  ushPackets. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 

See  Also 

See  RTPRssmReset  (III — 1516). 


RTPRssmComputeChunkSize 


Lets  your  packet  reassembler  compute  the  size  of  a  chunk,  based  on  the  packet  list 
for  the  chunk,  using  your  own  algorithm. 

ComponentResul t  RTPRssmComputeChunkSize  ( 

RTPReassembl er  rtpr, 

RTPRssmPacket  *inPacketListHead, 

SInt32  inFlags, 

UInt32  *outChunkDataSi ze  ); 


rtpr 

The  component  instance  of  your  packet  reassembler, 
i nPacketLi stHead 

A  pointer  to  the  list  of  packets  that  make  up  this  chunk, 
i  n FI  ags 

A  signed  32-bit  integer  containing  any  flags  being  passed  to  your  packet 
reassembler. 

outChunkDataSi ze 

You  should  return  a  pointer  to  an  unsigned  32-bit  variable  containing  the 
calculated  size  for  this  chunk. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  called  once  for  each  packet  list.  Implement  this  function  only  if  you 
need  to  override  the  base  reassembler's  default  computation.  If  you  do  not 
implement  this  call,  the  base  reassembler  will  compute  the  chunk  size  by  summing 
the  data  lengths  for  all  packets  in  the  list. 


III-1502 


Inside  QuickTime:  Functions  R-Z 


RTPRssmCopyDataToChunk 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


RTPRssmCopy  DataT  oChunk 


Lets  your  packet  reassembler  write  the  chunk  data,  based  on  the  list  of  packets  for 
the  chunk,  using  your  own  algorithm. 


ComponentResul t  RTPRssmCopyDataToChunk  ( 


RTPReassembl  er 

RTPRssmPacket 

UInt32 

SHChunkRecord 

SInt32 


rtpr , 

*i  nPacketLi stHead , 
i nMaxChunkDataSi  ze , 
*i nChunk, 
inFlags  ); 


rtpr 

The  component  instance  of  your  packet  reassembler, 
i nPacketLi stHead 

A  pointer  to  the  list  of  packets  that  make  up  this  chunk, 
i nMaxChunkDataSi ze 

An  unsigned  32-bit  integer  containing  the  maximum  allowable  chunks  size, 
i nChunk 

A  pointer  to  the  chunk  record.  Write  the  chunk  data  to  this  record, 
i n FI  ags 

A  32-bit  signed  integer  containing  any  flags  (see  below)  being  passed  to  your 
media  packetizer. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inFlags  Constants 

Undocumented 

Undocumented 

Discussion 

This  function  is  useful,  for  example,  when  an  H.261  packet  reassembler  must  adjust 
the  byte  at  packet  boundaries.  Implement  this  function  only  if  you  need  to  override 
the  base  reassembler's  default  behavior.  If  you  do  not  implement  this  function,  the 
base  reassembler  will  write  the  chunk  data  by  taking  dataLength  bytes  from  each 


Inside  QuickTime:  Functions  R-Z 


III-1503 


RTPRssmDecrChunkRefCount 


packet,  starting  at  an  offset  of  (<packet  data>  +  transportHeaderLength  + 
payl  oadHeader Length). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


RTPRssmDecrChunkRefCount 


Tells  the  base  reassembler  to  dispose  of  a  chunk  that  it  has  created  or  preserved  for 
you. 

ComponentResul t  RTPRssmDecrChunkRefCount  ( 

RTPReassembl er  rtpr, 

SHChunkRecord  *inChunk  ); 


rtpr 

The  component  instance  of  the  base  reassembler  component, 
i  nChunk 

A  pointer  to  the  chunk  record  to  dispose. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

If  you  have  overridden  RTPRssmSendPacketLi  st  (III— 1518)  behavior,  and  are 
instructing  the  base  reassembler  to  construct  chunks  manually,  your  packet 
assembler  must  explicitly  dispose  of  the  chunks  by  calling  either  this  function  or 
RTPRssmSendChunkAndDecrRefCount  (III— 1517).  This  function  is  also  used  to  release  a 
chunk  you  have  preserved  using  RTPRssmlncrChunkRefCount  (III— 1513). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


RTPRssmFillPacketListParams 


Fills  in  a  packet  structure  manually. 

ComponentResul t  RTPRssmFillPacketListParams  ( 
RTPReassembl er  rtpr. 


III-1504 


Inside  QuickTime:  Functions  R-Z 


RTPRssmGetCapabilities 


RTPRssmPacket 

SInt32 

SInt32 


*i n Packet  Li stHead  , 
i nNumWraparounds , 
inFlags  ); 


rtpr 

The  component  instance  of  the  base  reassembler, 
l nPacketLi stHead 

A  pointer  to  the  RTPRssmPacket  (IV-2412)  packet  structure, 
i nNumWraparounds 

The  high-order  32  bits  of  the  timestamp  for  this  packet.  The  low-order  32  bits 
are  found  in  the  RTP  packet  header, 
i  n  FI  ags 

A  signed  32-bit  integer  containing  any  flags  (see  below)  you  are  passing  to  the 
base  reassembler. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inFlags  Constants 

Undocumented 

Undocumented 

Discussion 

Call  this  function  only  if  your  packet  reassembler  is  overriding  the 
RTPRssmSendPacketLi  st  (III— 1518)  behavior.  The  base  reassembler  will  call  back  to 
your  packet  reassembler  using  RTPRssmAdjustPacketParams  (III— 1500)  and 
RTPRssmComputeChunkSi ze  (III — 1502). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


RTPRssmGetCapabilities 


Obtains  the  current  flag  settings  for  the  base  reassembler. 

ComponentResul t  RTPRssmGetCapabilities  ( 

RTPReassembl er  rtpr, 

SInt32  *outFlags  ); 


rtpr 

The  component  instance  of  the  base  reassembler. 


Inside  QuickTime:  Functions  R-Z 


III-1505 


RTPRssmGetChunkAndlncrRefCount 


outFl  ags 

On  return,  contains  a  pointer  to  the  reassembler's  current  flags  (see  below). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

outFlags  Constants 

kRTPRssm Every Packet AC hunk FI  ag 

Tells  the  base  reassembler  to  treat  every  packet  as  a  chunk,  as  would  be  the  case 
for  uLaw  audio,  for  example. 

kRTPRssmQueueAndllseMarkerBi  t FI  ag 

Tells  the  base  reassembler  to  queue  incoming  packets  and  assemble  a  chunk 
when  a  packet  has  the  marker  bit  set  or  the  RTP  time  stamp  changes. 
kRTPRssmTrackLostPacketsFlag 

Tells  the  base  reassembler  to  check  the  RTP  sequence  numbers  and  set  the 
kRTPRssmLostSomePackets  flag  if  any  packets  are  missing  from  the  packet  list 
when  it  calls  your  reassembler's  RTPRssmSendPacketLi  st  (III— 1518)  function. 
kRTPRssmNoReorderi ngRequi  red  FI  ag 

Tells  the  base  reassembler  that  packets  do  not  need  to  come  in 
sequence-number  order,  as  would  be  the  case  for  uLaw  audio,  for  example. 

Discussion 

Your  packet  reassembler  can  call  this  function  at  any  time. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 

See  Also 

For  the  corresponding  set  function,  see  RTPRssmSetCapabi  1  i  ti  es  (III— 1520). 

RTPRssmGetChunkAndlncrRefCount 

Causes  the  base  reassembler  to  create  a  chunk  for  you  manually. 

ComponentResul t  RTPRssmGetChunkAndlncrRefCount  ( 

RTPReassembl er  rtpr, 

UInt32  i nChunkDataSi ze , 

const  TimeVal ue64  *inChunkPresentationTime, 

SFIChunkRecord  **outChunk  ); 

rtpr 

The  component  instance  of  the  base  reassembler  component. 


III-1506  Inside  QuickTime:  Functions  R-Z 


RTPRssmGetlnfo 


i nChunkDataSi ze 

An  unsigned  32-bit  integer  containing  the  size  of  the  chunk's  data  portion,  in 
bytes. 

i nChunkPresentati onTime 

A  pointer  to  a  64-bit  time  value  specifying  the  time  at  which  this  chunk  should 
be  presented,  in  units  of  the  stream's  time  scale. 

outChunk 

On  return,  contains  a  pointer  to  a  newly-created  SHChunkRecord  (IV-2436) 
structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  useful  if  you  are  overriding  the  RTPRssmSendPacketLi  st  (III— 1518) 
behavior  and  constructing  the  chunk  yourself.  You  must  explicitly  dispose  of  the 
chunk  when  you  are  done  with  it  by  calling  either  RTPRssmDecrChunkRefCount 
(III — 1504)  or  RTPRssmSendChunkAndDecrRefCount  (III — 1517). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents  .  h 


RTPRssmGetlnfo 


Obtains  information  about  your  packet  reassembler. 

ComponentResul t  RTPRssmGetlnfo  ( 

RTPReassembl er  rtpr, 

OSType  inSelector, 

void  *ioParams  ); 


rtpr 

The  component  instance  of  your  packet  reassembler, 
i nSel ector 

A  selector  (see  below)  for  the  information  desired, 
i oParams 

A  pointer  to  a  data  structure  appropriate  for  the  type  of  data  requested  (see 
below) .  If  your  component  understands  the  selector,  write  the  requested 
information  into  the  data  structure  this  parameter  points  to. 


Inside  QuickTime:  Functions  R-Z 


III-1507 


RTPRssmGetlnfo 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inSelector  Constants 

kQTSSourceT  rackIDInfo 

The  source  track  ID  as  a  U I  nt32;  constant  value  is  '  oti  d ' . 
kQTSSource Layer  Info 

The  source  layer  number  as  a  U I  n  1 1 6;  constant  value  is  '  o  1  y  r ' . 
kQTSSource Language  Info 

The  source  language  code  as  a  U I  n  1 1 6;  constant  value  is  '  o  1  n  g ' .  See 
"Localization  Codes"  (IV-2673). 

kQTSSourceT  rackFlagsInfo 

The  source  track  flag  set  as  an  S I  n  1 3  2;  constant  value  is  '  o t  f  1 ' . 
kQTSSourceDi mens i ons Info 

The  source  dimensions  as  a  QTSDi mensi  onParams  (IV-2368)  structure;  constant 
value  is  'odim'. 
kQTSSource Vo 1 umeslnfo 

The  source  sound  volumes  as  a  QTSVol  umes  Pa  rams  (IV-2390)  structure;  constant 
value  is  '  ovol  ' . 

kQTSSourceMatri xlnfo 

The  source  matrix  as  a  Matri  xRecord  (IV-2304)  structure;  constant  value  is 
' omat ' . 

kQTSSourceCl i pRectlnfo 

The  source  clipping  rectangle  as  a  Rect  (IV-2399)  structure;  constant  value  is 
'  ocl  p  ' . 

kQTSSourceGraphi csModelnfo 

The  source  graphics  mode  as  a  QTSGraphi  csModeParams  (IV-2372)  structure; 
constant  value  is  'ogrm'. 

kQTSSourceScal elnfo 

The  source  scaling  factors  as  a  Poi  nt  (IV-2339)  structure;  constant  value  is 
' oscl ' . 

kQTSSourceBoundi ngRectlnfo 

The  source  bounding  rectangle  as  a  Rect  (IV-2399)  structure;  constant  value  is 
' orct ' . 

kQTSSourcellser  Data  Info 

The  source's  user  data  as  a  UserData  Record  (IV-2496)  structure;  constant  value 
is  '  oudt ' . 

kQTSSource I nputMapInfo 

The  source  input  map  as  a  QT  atom  container;  constant  value  is  '  oi  mp ' . 


III-1508 
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RTPRssmGetPayloadHeaderLength 


Discussion 

Implement  this  function  only  for  the  selectors  you  understand.  Delegate  this 
function  to  the  base  reassembler  for  any  other  selectors.  The  base  reassembler  will 
correctly  return  an  error  if  it  doesn't  understand  the  selector  either. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 

See  Also 

For  the  corresponding  set  function,  see  RTPRssmSetlnfo  (III— 1521).  Also  see 
RTPRssmHasCharacteri  sti  c  (III — 1512). 


RTPRssmGetPayloadHeaderLength 


Obtains  the  current  value  of  the  fixed  payload  header  length  from  the  base 
reassembler. 

ComponentResul t  RTPRssmGetPayloadHeaderLength  ( 

RTPReassembl er  rtpr, 

UInt32  *outPayl oadHeaderLength  ); 


rtpr 

The  component  instance  of  the  base  reassembler  component. 
outPayl oadHeaderLength 

On  return,  contains  a  pointer  to  an  unsigned  32-bit  integer  containing  the 
length  of  the  payload  header  in  bytes.  If  your  packet  reassembler  does  not 
implement  RTPRssmAdjustPacketParams  (III— 1 500),  or  takes  no  action,  the  default 
payl  oadHeaderLength  is  the  fixed  header  length  that  is  set  (default  is  0). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  packet  reassembler  can  call  this  function  at  any  time. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 

See  Also 

For  the  corresponding  set  function,  see  RTPRssmSetPayl  oadHeaderLength  (III— 1523). 


Inside  QuickTime:  Functions  R-Z 


III-1509 


RTPRssmGetStreamHandler 


RTPRssmGetStreamHandler 


Obtains  the  component  instance  of  the  stream  handler  to  which  the  base 
reassembler  is  sending  your  output. 

ComponentResul t  RTPRssmGetStreamHancn  er  ( 

RTPReassembl er  rtpr, 

Componentlnstance  *outStreamHandl er  ); 


rtpr 

The  component  instance  of  the  base  reassembler. 
outStreamHandl er 

On  return,  contains  a  pointer  to  the  component  instance  of  the  stream  handler 
your  output  is  being  sent  to  by  the  base  reassembler. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 

See  Also 

For  the  corresponding  set  function,  see  RTPRssmSetStreamHandl  er  (III— 1524). 


RTPRssmGetTimeScale 


Obtains  the  current  time  scale  from  the  base  reassembler. 

ComponentResul t  RTPRssmGetTimeScale  ( 

RTPReassembl er  rtpr, 

TimeScale  *outSHTimeScale  ); 


rtpr 

The  component  instance  of  the  base  reassembler. 
outSHTimeScale 

On  return,  contains  a  pointer  to  the  time  scale  in  use  by  the  stream  handler  that 
is  processing  your  output. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 


III-1510 
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RTPRssmGetTimeScaleFromPacket 


Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 

See  Also 

For  the  corresponding  set  function,  see  RTPRssmSetTi  meScal  e  (III— 1525). 


RTPRssmGetTimeScaleFromPacket 


Lets  your  packet  reassembler  extract  the  time  scale  from  a  received  packet  and 
return  it  to  the  base  reassembler. 

ComponentResul t  RTPRssmGetTimeScaleFromPacket  ( 

RTPReassembl er  rtpr, 

QTSStreamBuf f er  *i nStreamBuf f er , 

TimeScale  *outTimeScale  ); 


rtpr 

The  component  instance  of  your  packet  reassembler, 
l nStreamBuf fer 

A  pointer  to  a  received  packet  from  which  you  may  be  able  to  extract  a  time 
scale. 

outT i meScal e 

Return  a  pointer  to  a  valid  time  scale  or  return  an  error.  If  you  return  a  time 
scale,  the  packet  will  be  processed  normally.  If  you  return  an  error,  the  packet 
will  be  discarded. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

If  your  packet  reassembler  has  not  specified  a  time  scale  as  part  of 
RTPRssmNewStreamHandl  er  (III— 1514),  or  by  calling  RTPRssmSetT i  meScal  e  (III— 1525), 
the  base  reassembler  calls  this  function  when  it  receives  packets,  which  allows  your 
packet  reassembler  to  extract  the  time  scale  from  a  received  packet  and  return  it  to 
the  base  reassembler.  Your  packet  reassembler  must  set  a  time  scale  for  the  stream 
handler  before  the  base  reassembler  can  process  any  incoming  packets.  If  your 
packet  reassembler  doesn't  know  the  time  scale  of  its  media  in  advance,  because  the 
time  scale  is  contained  in  the  packet  header  for  example,  the  base  reassembler  will 
prompt  you  for  a  time  scale  whenever  it  receives  a  packet.  If  your  packet 
reassembler  always  uses  the  same  time  scale,  it  should  set  the  time  scale  when  it 
opens  a  stream  handler,  and  it  does  not  need  to  implement  this  function.  The  base 
reassembler  will  discard  received  packets  until  it  has  been  given  a  valid  time  scale. 


Inside  QuickTime:  Functions  R-Z 


III-1511 


RTPRssmHandleNewPacket 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


RTPRssmHandleNewPacket 


Called  whenever  a  new  packet  arrives,  giving  your  packet  reassembler  the 
opportunity  to  process  the  packet. 

ComponentResul t  RTPRssmHancn  eNewPacket  ( 

RTPReassembl er  rtpr, 

QTSStreamBuffer  *1 nStreamBuffer , 

SInt32  i nNumWraparounds  ); 


rtpr 

The  component  instance  of  your  packet  reassembler, 
i nStreamBuffer 

A  pointer  to  the  newly-arrived  packet, 
i nNumWraparounds 

The  upper  32  bits  of  the  64-bit  timestamp  (the  lower  32  bits  are  in  the  RTP 
packet  timestamp). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  should  implement  this  function  only  if  you  need  to  process  the  packet  yourself, 
or  if  you  need  to  extract  information  from  the  packets  as  they  arrive  (you  need  to 
monitor  the  payload  header,  for  example).  If  you  implement  this  function,  you  can 
process  the  packet  as  needed,  then  delegate  the  default  processing  to  the  base 
reassembler. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


RTPRssmHasCharacteristic 


Determines  what  features  your  reassembler  supports. 


III-1512 
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RTPRssmlncrChunkRefCount 


Component  Res  ul  t  RTPRssmHasCharacteri  sti  c 
RTPReassembl  er  rtpr, 

OSType  inCharacteristic, 

Boolean  *outHas!t  ); 


( 


rtpr 

The  component  instance  of  your  packet  reassembler, 
i nCharacteri sti c 

A  constant  (see  below)  that  defines  the  character!  sti  c  being  tested. 
outHas It 

A  pointer  to  a  Boolean  value  that  is  TRUE  if  your  packet  reassembler  has  the 
characteristic,  FALSE  otherwise. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inCharacteristic  Constants 

Undocumented 

Undocumented 


Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 

See  Also 

See  RTPRssmGetlnfo  (III — 1507)  and  RTPRssmSetlnfo  (III — 1521). 


RTPRssmlncrChunkRefCount 


Tells  the  base  reassembler  to  keep  a  copy  of  the  most  recent  chunk  after  it  has  been 
sent. 

ComponentResul t  RTPRssmlncrChunkRefCount  ( 

RTPReassembl er  rtpr, 

SHChunkRecord  *inChunk  ); 


rtpr 

The  component  instance  of  the  base  reassembler, 
i nChunk 

A  pointer  to  the  chunk  record  you  want  to  preserve. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Inside  QuickTime:  Functions  R-Z 


III-1513 


RTPRssmlnitialize 


Discussion 

This  function  is  used  to  assist  in  loss  recovery,  for  example.  You  must  call 
RTPRssmDecrChunkRefCount  (III— 1504)  to  release  the  chunk  when  you  no  longer  need 
it. 

Version  Notes 

Introduced  in  QuickTime  4. 
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RTPRssmlnitialize 


Called  when  the  base  reassembler  is  ready  to  have  your  packet  reassembler  begin 
handling  media  packets. 

ComponentResul t  RTPRssmlnitialize  ( 

RTPReassembl er  rtpr, 

RTPRssmlni tParams  *inlni tParams  ); 


rtpr 

The  component  instance  of  your  packet  reassembler 
i nlni tParams 

A  pointer  to  an  RTPRssmlni  tParams  (IV-2411)  structure.  Use  the  information 
contained  in  this  structure  to  initialize  your  component. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  not  called  when  the  base  reassembler  opens  your  component  for 
payload  registration  information. 

Version  Notes 

Introduced  in  QuickTime  4. 
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RTPRssmNewStreamHandler 


Opens  a  new  stream  handler  and  closes  any  currently-open  stream  handler. 

ComponentResul t  RTPRssmNewStreamHandler  ( 

RTPReassembl er  rtpr, 


III-1514 
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RTPRssmReleasePacketList 


OSType 

Sampl eDescri pti on Hand! e 

TimeScale 

Componentlnstance 


i nSHType , 

i nSampl eDescri pti on  , 
i nSHT i meScal e , 
*outHandler  ); 


rtpr 

The  component  instance  of  the  base  reassembler, 
i nSHType 

The  stream  handler  type, 
i nSampl eDescri pti on 

A  handle  to  a  Sampl  eDescri  pti  on  (IV-2414)  structure  appropriate  for  this  media 
type.  Pass  in  N I L  if  you  don't  know  the  media  type  yet.  This  structure  is  passed 
by  reference;  the  caller  is  responsible  for  maintaining  it. 
i nSHTimeScal e 

The  time  scale  for  the  stream  handler  to  use.  Pass  in  0  if  the  time  scale  is  not  yet 
known. 

outHandl er 

On  return,  contains  a  pointer  to  the  component  instance  of  the  stream  handler 
that  has  been  opened. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  must  pass  in  a  valid  Sampl  eDescri  pti  on  (IV-2414)  structure  and  time  scale 
before  the  stream  handler  can  process  packets.  If  you  do  not  pass  them  as  part  of 
this  function,  do  so  using  RTPRssmSetTimeScale  (III— 1525)  and 
RTPRssmSetSampl  eDescri  pti  on  (III — 1524). 

Version  Notes 

Introduced  in  QuickTime  4. 
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RTPRssmReleasePacketList 


Releases  memory  associated  with  a  packet  list  that  your  packet  reassembler  created 
itself,  or  a  list  your  reassembler  took  ownership  of  as  a  result  of  implementing 
RTPRssmSendPacketLi  st  (III — 1518). 

ComponentResul t  RTPRssmReleasePacketList  ( 

RTPReassembl er  rtpr. 
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III-1515 


RTPRssmReset 


RTPRssmPacket  *i nPacketLi stHead  ); 


rtpr 

The  component  instance  of  the  base  reassembler, 
i nPacketLi stHead 

A  pointer  to  the  packet  list  to  dispose  of. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  is  a  housekeeping  function  that  you  do  not  need  to  perform  for  packet  lists 
created  and  handled  by  the  base  reassembler,  only  for  packet  lists  that  you  create  or 
take  ownership  of  yourself. 

Version  Notes 

Introduced  in  QuickTime  4. 
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RTPRssmReset 


Called  to  reset  all  packet  reassembler  and  base  reassembler  variables  for  a  new  run 
of  data. 

ComponentResul t  RTPRssmReset  ( 

RTPReassembl er  rtpr, 

SInt32  i  n FI  ags  ) ; 


rtpr 

The  component  instance  of  your  reassembler. 

1  n FI  ags 

A  signed  32-bit  integer  containing  any  flags  being  passed.  No  flags  are 
currently  defined. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  differs  from  RTPRssmCl  earCachedPackets  (III— 1501),  which  disposes  of 
the  packets  but  still  retains  the  last  sequence  number  and  related  information;  this 
function  resets  all  variables  as  if  the  reassembler  were  just  opened. 

Version  Notes 

Introduced  in  QuickTime  4. 
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RTPRssmSendChunkAndDecrRefCount 


Programming  Info 
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See  Also 

See  RTPRssmCl earCachedPackets  (III — 1501). 


RTPRssmSendChunkAndDecrRefCount 


Called  by  the  packet  reassembler  when  it  has  finished  constructing  a  chunk  and 
wants  the  base  reassembler  to  send  it  to  the  stream  handler. 

ComponentResul t  RTPRssmSendChunkAndDecrRefCount  ( 

RTPReassembl er  rtpr, 

SHChunkRecord  *inChunk, 

const  SHServerEdi tParameters  *i nServerEdi t  ); 


rtpr 

The  component  instance  of  the  base  reassembler, 
i nChunk 

A  pointer  to  an  SHChunkRecord  (IV-2436)  structure, 
l nServerEdi t 

A  pointer  to  an  SHServerEdi  tParameters  (IV-2437)  structure  containing  the 
server  edit  parameters.  Pass  in  N I L  if  there  is  no  server  edit. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Use  this  function  to  manually  send  a  chunk  if  you  have  overridden  the  default 
behavior  of  RTPRssmSendPacketList  (III— 1518).  This  function  will  decrement  the 
reference  count  of  the  chunk. 

Version  Notes 

Introduced  in  QuickTime  4. 
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RTPRssmSendLostChunk 


Allows  the  base  reassembler  to  send  loss  notification  to  the  stream  handler. 

ComponentResul t  RTPRssmSendLostChunk  ( 

RTPReassembl er  rtpr. 
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III-1517 


RTPRssmSendPacketList 


const  TimeVal ue64  *i nChunkPresentati onTime  ); 


rtpr 

The  component  instance  of  the  base  reassembler, 
i nChunkPresentati onTime 

A  pointer  to  a  64-bit  time  value  indicating  when  the  chunk  would  have  been 
presented,  in  units  of  the  stream's  time  scale. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Loss  notification  is  normally  performed  automatically  by  the  base  reassembler.  Use 
this  function  if  you  are  handling  losses  or  sending  chunks  manually. 

Version  Notes 

Introduced  in  QuickTime  4. 
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RTPRssmSendPacketList 


Called  when  the  base  reassembler  is  ready  to  send  a  sample  or  chunk  based  on  a  list 
of  packets. 


ComponentResul t  RTPRssmSendPacketList  ( 

RTPReassembl er  rtpr, 

RTPRssmPacket  *i nPacketLi stHead , 

const  TimeValue64  *inLastChunkPresentationTime, 

SInt32  i  n FT  ags  )  ; 


rtpr 

The  component  instance  of  your  packet  reassembler, 
i nPacketLi stHead 

A  pointer  to  the  packet  list. 
inLastChunkPresentati  onTime 

A  pointer  to  a  time  value  which  specifies  when  to  present  this  chunk,  in  units 
of  the  stream's  time  scale. 

i  n  FI  ags 

A  signed  32-bit  integer  containing  any  flags  being  passed  (see  below). 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


III-1518 
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RTPRssmSendStreamBufferRange 


inFlags  Constant 

kRTPRssm Lost Some Packets 

A  packet  loss  has  occurred. 

Discussion 

Implement  this  call  if  your  packet  reassembler  needs  to  modify  the  packet  list,  or  if 
it  overrides  the  default  handling  of  packet  loss.  If  you  do  not  implement  this  call, 
the  base  reassembler  will  adjust  the  packet  parameters  on  all  packets  in  the  list, 
compute  the  chunk  size,  and  send  the  chunk.  If  packet  loss  has  occurred,  all  the 
packets  will  be  discarded  and  the  stream  handler  will  be  informed  that  the  chunk 
has  been  lost. 

Version  Notes 

Introduced  in  QuickTime  4. 
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RTPRssmSendStreamBufferRange 


Notifies  the  base  reassembler  to  construct  and  send  a  chunk  based  on  a  part  of  the 
stream  buffer. 

ComponentResul t  RTPRssmSendStreamBufferRange  ( 

RTPReassembl er  rtpr, 

RTPSendStreamBufferRangeParams  *inParams  ); 


rtpr 

The  component  instance  of  the  base  reassembler, 
i nParams 

A  pointer  to  an  RTPSendStreamBufferRangeParams  (IV-2413)  structure,  which 
specifies  the  stream  buffer,  presentation  time,  start  position  in  the  buffer,  length 
of  the  data  in  bytes,  and  any  flags. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  contents  of  the  stream  buffer  will  be  referenced,  not  copied.  You  are  responsible 
for  maintaining  valid  data  in  the  stream  buffer. 

Version  Notes 

Introduced  in  QuickTime  4. 
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III-1519 


RTPRssmSendStreamHandlerChanged 


RTPRssmSendStreamHandlerChanged 


Called  when  you  have  changed  something  in  the  stream  handler  and  you  want  the 
notification  propagated. 

ComponentResul t  RTPRssmSendStreamHandl erChanged  ( 

RTPReassembl er  rtpr  ); 


rtpr 

The  component  instance  of  the  base  reassembler. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  useful,  for  example,  if  you  have  changed  the  dimensions  of  the 
video. 

Version  Notes 

Introduced  in  QuickTime  4. 
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RTPRssmSetCapabilities 


Sets  the  capabilities  of  a  streaming  packet  reassembler. 

ComponentResul t  RTPRssmSetCapabilities  ( 
RTPReassembl er  rtpr, 

SInt32  inFlags, 

SInt32  i  n FI  agsMask  ) ; 


rtpr 

The  component  instance  of  the  base  reassembler, 
i  n FI  ags 

A  signed  32-bit  integer  containing  the  logical  OR  of  all  the  flags  (see  below)  you 
are  setting, 
i n  FI agsMask 

Use  this  field  to  preserve  the  state  of  any  flags  you  do  not  wish  to  alter.  If  a  flag 
(see  below)  is  set  in  this  field,  and  is  not  set  in  the  i  n  FI  ags  field,  it  will  not  be 
changed  from  its  current  setting. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


III-1520 
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RTPRssmSetlnfo 


inFlags  Constants 

kRTPRssmE very Packet AC hunk FI  ag 

Tells  the  base  reassembler  to  treat  every  packet  as  a  chunk,  as  would  be  the  case 
for  uLaw  audio,  for  example. 

kRTPRssmQueueAndllseMarkerBi  t FI  ag 

Tells  the  base  reassembler  to  queue  incoming  packets  and  assemble  a  chunk 
when  a  packet  has  the  marker  bit  set  or  the  RTP  time  stamp  changes. 
kRTP Rs smTr a ckLost Packets  FI  ag 

Tells  the  base  reassembler  to  check  the  RTP  sequence  numbers  and  set  the 
kRTPRssmLostSomePackets  flag  if  any  packets  are  missing  from  the  packet  list 
when  it  calls  your  reassembler's  RTPRssmSendPacketLi  st  (III— 1518)  function. 
kRTP RssmNo Reorder! ngRequi  red  FI  ag 

Tells  the  base  reassembler  that  packets  do  not  need  to  come  in 
sequence-number  order,  as  would  be  the  case  for  uLaw  audio,  for  example. 

Discussion 

Your  packet  reassembler  can  call  this  function  at  any  time. 

Version  Notes 

Introduced  in  QuickTime  4. 
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See  Also 

For  the  corresponding  get  function,  see  RTPRssmGetCapabi  1  i  ti  es  (III— 1505). 


RTPRssmSetlnfo 


Sets  various  parameters  of  your  packet  reassembler;  it  is  also  called  to  set 
parameters  of  the  base  reassembler. 

ComponentResul t  RTPRssmSetlnfo  ( 

RTPReassembl er  rtpr, 

OSType  inSelector, 

void  *ioParams  ); 


rtpr 

The  component  instance  of  your  packet  reassembler, 
i nSel ector 

A  selector  (see  below)  for  the  information  being  set.  Ignore  any  selectors  you  do 
not  understand. 
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III-1521 


RTPRs  smSetlnfo 


i oParams 

A  pointer  to  the  information  that  should  be  set. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inSelector  Constants 

kQTSSourceT  rackIDInfo 

The  source  track  ID  as  a  UInt32;  constant  value  is  '  oti  d ' . 
kQTSSource Layer  Info 

The  source  layer  number  as  a  U I  n  1 1 6;  constant  value  is  '  o  1  y  r ' . 
kQTSSource Language  Info 

The  source  language  code  as  a  U I  n  1 1 6;  constant  value  is  '  o  1  n  g ' .  See 
"Localization  Codes"  (IV-2673). 
kQTSSourceT  rackLlagsInfo 

The  source  track  flag  set  as  an  S I  n  1 3  2;  constant  value  is  '  o t  f  1 ' . 
kQTSSourceDi mensionslnfo 

The  source  dimensions  as  a  QTSDi mensi onParams  (IV-2368)  structure;  constant 
value  is  'odim'. 
kQTSSource Vo 1 umeslnfo 

The  source  sound  volumes  as  a  QTSVol  umes  Pa  rams  (IV-2390)  structure;  constant 
value  is  '  ovol  ' . 
kQTSSourceMatri xlnfo 

The  source  matrix  as  a  Matri  xRecord  (IV-2304)  structure;  constant  value  is 
' omat ' . 

kQTSSourceCl i pRectlnfo 

The  source  clipping  rectangle  as  a  Rect  (IV-2399)  structure;  constant  value  is 
'  ocl  p ' . 

kQTSSourceGraphi csModelnfo 

The  source  graphics  mode  as  a  QTSGraphi  csModeParams  (IV-2372)  structure; 
constant  value  is  'ogrm'. 
kQTSSourceScal elnfo 

The  source  scaling  factors  as  a  Poi  nt  (IV-2339)  structure;  constant  value  is 
' oscl  ' . 

kQTSSourceBoundi ngRectlnfo 

The  source  bounding  rectangle  as  a  Rect  (IV-2399)  structure;  constant  value  is 
' orct ' . 


III-1522 


Inside  QuickTime:  Functions  R-Z 


RTPRssmSetPayloadHeaderLength 


kQTSSourceUserData Inf o 

The  source's  user  data  as  a  UserDataRecord  (IV-2496)  structure;  constant  value 
is  1  oudt 1 . 

kQTSSourcelnputMapInf o 

The  source  input  map  as  a  QT  atom  container;  constant  value  is  ’  oi  mp ' . 

Discussion 

Delegate  this  function  to  the  base  reassembler  for  any  selectors  you  don't 
understand.  If  the  base  reassembler  doesn't  understand  them  either,  it  will  return 
an  error  to  the  caller. 

Version  Notes 

Introduced  in  QuickTime  4. 
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See  Also 

For  the  corresponding  get  function,  see  RTPRssmGetlnfo  (III— 1507).  Also  see 
RTPRssmHasCharacteri  sti  c  (III — 1512). 


RTPRssmSetPayloadHeaderLength 


Called  by  the  packet  reassembler  to  set  a  fixed  header  length  for  your  payload. 

ComponentResul t  RTPRssmSetPayloadHeaderLength  ( 

RTPReassembl er  rtpr, 

UInt32  i nPayl oadHeaderLength  ); 


rtpr 

The  component  instance  of  the  base  reassembler, 
i nPayl oadHeaderLength 

An  unsigned  32-bit  integer  containing  the  fixed  payload  header  length,  in 
bytes.  If  your  packet  reassembler  does  not  implement 
RTPRssmAdjustPacketParams  (III— 1500),  or  takes  no  action,  the  default 
pay!  oadHeaderLength  is  the  fixed  header  length  that  is  set  (default  is  0). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 
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III-1523 


RTPRssmSetSampleDescription 


See  Also 

For  the  corresponding  get  function,  see  RTPRssmGetPayl  oadHeaderLength  (III— 1509). 


RTPRssmSetSampleDescription 


Changes  the  Sampl  eDescri  pti  on  (IV-2414)  structure  being  used  by  the  stream 
handler;  all  subsequent  samples  will  be  marked  with  this  new  structure. 

ComponentResult  RTPRssmSetSampleDescription  ( 

RTPReassembl er  rtpr, 

Sampl eDescri pti onHandl e  i nSampl eDescri pti on  ); 


rtpr 

The  component  instance  of  the  base  reassembler. 
inSampleDescription 

The  handle  of  a  Sampl  eDescri  pti  on  (IV-2414)  structure  to  use.  You  are 
responsible  for  keeping  the  handle  and  the  data  structure  valid  during 
subsequent  operations. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  Sampl  eDescri  pti  on  structure  is  not  passed  on  a  per-packet  basis,  but  a 
per-sample  basis,  so  the  Sampl  eDescri  pti  on  (IV-2414)  structure  should  not  be 
changed  until  a  complete  sample  (sometimes  called  a  "frame"  or  "chunk")  has  been 
reassembled. 

Version  Notes 

Introduced  in  QuickTime  4. 
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RTPRssmSetStreamHandler 


Assigns  a  stream  handler  to  the  output  of  the  base  reassembler. 

ComponentResult  RTPRssmSetStreamHandler  ( 

RTPReassembl er  rtpr, 

Componentlnstance  i nStreamHandl er  ); 


rtpr 

The  component  instance  of  the  base  reassembler. 


III-1524 
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RTPRssmSetTimeScale 


i nStreamHandl er 

The  component  instance  of  the  stream  handler  to  use. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  stream  handler  must  already  be  opened  and  initialized,  and  its  time  scale  must 
already  be  set. 

Special  Considerations 

Use  this  function  only  if  you  have  opened  and  initialized  a  stream  handler  yourself. 
The  base  reassembler  will  not  close  the  stream  handler  it  is  already  using. 

Version  Notes 

Introduced  in  QuickTime  4. 
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See  Also 

For  the  corresponding  get  function,  see  RTPRssmGetStreamHandl  er  (III— 1510). 


RTPRssmSetTimeScale 


Sets  the  time  scale  for  the  stream  handler  that  will  render  your  output. 

ComponentResul t  RTPRssmSetTimeScale  ( 

RTPReassembl er  rtpr, 

TimeScale  i nSHTimeScal e  ); 


rtpr 

The  component  instance  of  the  base  reassembler 
i nSHTi meScal e 

The  time  scale  for  the  stream  handler  to  use 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  time  scale  is  the  number  of  time  units  that  pass  in  one  second  for  the  media 
whose  sample  data  is  carried  in  this  stream.  The  stream  handler's  time  scale  must 
be  set  before  it  can  deliver  any  data  to  the  user. 

Special  Considerations 

This  function  is  normally  used  by  a  packet  reassembler  when  the  time  scale  to  use 
is  not  initially  known.  You  don't  need  to  call  this  function  if  you  specified  a  time 
scale  when  the  stream  handler  was  opened. 
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III-1525 


SampleNumToMediaTime 


Version  Notes 

Introduced  in  QuickTime  4. 
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See  Also 

For  the  corresponding  get  function,  see  RTPRssmGetTimeScal  e  (III— 1510). 


s 


SampleNumT  oMediaT  ime 

Finds  the  time  at  which  a  specified  sample  plays. 

void  SampleNumToMediaTime  ( 

Media  theMedia, 

long  1 ogi cal Sampl eNum , 

TimeValue  *sampleTime, 

TimeValue  *sampl eDurati on  ); 

theMedi a 

The  media  for  this  operation.  You  obtain  this  media  identifier  from  such 
functions  as  NewTrackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 

1 ogi cal Sampl eNum 

The  sample  number, 
sampl eT i me 

A  pointer  to  a  time  value.  The  function  updates  this  time  value  to  indicate  the 
starting  time  of  the  sample  specified  by  the  1  ogi  cal  Sampl  eNum  parameter.  This 
time  value  is  expressed  in  the  media's  time  scale.  Set  this  parameter  to  N I L  if  you 
don't  want  this  information. 

sampl eDurati on 

A  pointer  to  a  time  value.  The  Movie  Toolbox  returns  the  duration  of  the 
sample  specified  by  the  1  ogi  cal  Sampl  eNum  parameter.  This  time  value  is 
expressed  in  the  media's  time  scale.  Set  this  parameter  to  N I L  if  you  don't  want 
this  information. 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94). 
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ScaleMatrix 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Media  Samples"  (V-2742) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Medi a . sampl eNumToMedi aTi me( ) 


ScaleMatrix 


Modifies  the  contents  of  a  matrix  so  that  it  defines  a  scaling  operation. 


void  ScaleMatrix  ( 
Matri xRecord 
Fi  xed 
Fi  xed 
Fi  xed 
Fi  xed 


*m, 

seal eX , 
seal eY , 
aboutX , 
aboutY  ); 


m 

A  pointer  to  a  Matri  xRecord  (IV-2304)  structure.  The  Seal  eMatri  x  function 
updates  the  contents  of  this  matrix  so  that  the  matrix  describes  a  scaling 
operation;  that  is,  it  concatenates  the  respective  transformations  onto  whatever 
was  initially  in  the  matrix  structure.  You  specify  the  magnitude  of  the  scaling 
operation  with  the  s  c  a  1  e  X  and  s  c  a  1  e  Y  parameters  .You  specify  the  anchor  point 
with  the  aboutX  and  aboutY  parameters. 

seal eX 

The  scaling  factor  applied  to  x  coordinates, 
seal eY 

The  scaling  factor  applied  to  y  coordinates. 
aboutX 

The  x  coordinate  of  the  anchor  point. 
aboutY 

The  y  coordinate  of  the  anchor  point. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Matrices"  (V-2764) 
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SCAsyncIdle 


Related  Java  Methods 

qui cktime. std . image .Matrix. seal e( ) 


SCAsyncIdle 

Called  occasionally  while  performing  asynchronous  compression  with 
SCCompressSequenceFrameAsync  (III — 1538). 

ComponentResul t  SCAsyncIdle  ( Componentlnstance  ci ) ; 
ci 

Your  application's  connection  to  the  image-compression  component  being 
used  by  SCCompressSequenceFrameAsync  (III— 1538).  You  obtain  this  identifier 
from  OpenDef  aul  tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

See  Also 

See  SCCompressSequenceFrameAsync  (III — 1538). 

ScaleMovieSegment 

Changes  the  duration  of  a  segment  of  a  movie. 

OSErr  ScaleMovieSegment  ( 

Movie  theMovie, 

TimeVal ue  startTi me , 

TimeValue  oldDuration, 

TimeValue  newDuration  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovie  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  or 
NewMovi  eFromHandl  e  (11-1084). 
startTime 

The  start  of  the  segment.  The  oldDuration  parameter  specifies  the  segment's 
duration.  This  time  value  must  be  expressed  in  the  movie's  time  scale. 
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ol dDurati on 

The  original  duration  of  the  segment  in  the  source  movie.  This  time  value  must 
be  expressed  in  the  movie's  time  scale. 
newDurati on 

The  new  duration  of  the  segment.  This  time  value  must  be  expressed  in  the 
movie's  time  scale.  The  function  alters  the  segment  to  accommodate  the  new 
duration. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

The  Movie  Toolbox  scales  the  segment  to  accommodate  the  new  duration. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Low-Level  Movie  Editing  Functions"  (V-2749) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . seal eSegmentl ) 


ScaleT  rackSegment 


Changes  the  duration  of  a  segment  of  a  track. 

OSErr  ScaleTrackSegment  ( 

Track  theTrack, 

TimeValue  startTime, 

TimeValue  ol dDurati on , 

TimeValue  newDuration  ); 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

startTime 

The  start  of  the  segment.  The  ol  dDurati  on  parameter  specifies  the  segment's 
duration.  This  time  value  must  be  expressed  in  the  time  scale  of  the  movie  that 
contains  the  track. 
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ol dDurati on 

The  duration  of  the  segment.  This  time  value  must  be  expressed  in  the  time 
scale  of  the  movie  that  contains  the  track. 
newDurati on 

The  new  duration  of  the  segment.  This  time  value  must  be  expressed  in  the  time 
scale  of  the  movie  that  contains  the  track.  The  function  alters  the  segment  to 
accommodate  the  new  duration. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

This  function  does  not  cause  the  Movie  Toolbox  to  add  data  to  or  remove  data  from 
the  movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Editing  Tracks"  (V-2750) 

Related  Java  Methods 

qu i ckti me. std. mo vies. Track. seal eSegment ( ) 


SCCompressImage 


Compresses  an  image  that  is  stored  in  a  Pi  xMap  (IV-2332)  structure. 
ComponentResul t  SCCompressImage  ( 


Componentlnstance  ci  , 

Pi xMapHandl e  sre, 

const  Rect  *srcRect, 

ImageDescri pti onHandl e  *desc, 
Handle  *data  ); 


ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
dialog  component.  You  obtain  this  identifier  from  OpenDef  aul  tComponent 
(11-1131). 

sre 

A  handle  to  the  Pi  xMap  (IV-2332)  structure  to  be  compressed. 
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SCCompressPicture 


srcRect 

A  pointer  to  a  portion  of  the  Pi  xMap  (IV-2332)  structure  to  compress  as  a  Rect 
(IV-2399)  structure.  This  rectangle  must  be  in  the  pixel  map's  coordinate 
system.  If  you  want  to  compress  the  entire  pixel  map,  set  this  parameter  to  NIL. 

desc 

A  pointer  to  a  handle  to  an  ImageDescri  pti  on  (IV-2285)  structure.  The  standard 
dialog  component  creates  an  ImageDescri  pti  on  structure  when  it  compresses 
the  image,  and  returns  a  handle  to  that  structure  in  the  field  referred  to  by  this 
parameter.  The  component  sizes  that  handle  appropriately.  Your  application  is 
responsible  for  disposing  of  that  handle  when  you  are  done  with  it. 

data 

A  pointer  to  a  handle.  The  standard  dialog  component  returns  a  handle  to  the 
compressed  image  data  in  the  field  referred  to  by  this  parameter.  The 
component  sizes  that  handle  appropriately.  Your  application  is  responsible  for 
disposing  of  that  handle  when  you  are  done  with  it. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Compressing  Still  Images"  (V-2801) 

Related  Java  Methods 

qui cktime . std . qt components . SCSequence . compress  Frame! ) , 

qui cktime . std . qt components . ImageCompressi onDi al og . compress  Image! ) , 

qui cktime . std . image . ImageDescri pti on . from ImageCompressi onDi al og! ) 


SCCompressPicture 


Compresses  a  Pi  cture  (IV-2331)  structure  that  is  stored  by  a  handle. 

ComponentResul t  SCCompressPicture  ( 

Componentlnstance  ci  , 

PicHandle  srcPicture, 

PicHandle  dstPi  cture  ); 
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SCCompressPictureFile 


ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
dialog  component.  You  obtain  this  identifier  from  OpenDef  aul  tComponent 
(11-1131). 

srcPi cture 

A  handle  to  the  Pi  cture  (IV-2331)  structure  to  be  compressed. 
dstPi cture 

A  handle  to  the  compressed  Pi  cture  (IV-2331)  structure.  The  standard  dialog 
component  resizes  this  handle  to  accommodate  the  compressed  structure.  Your 
application  is  responsible  for  creating  and  disposing  of  this  handle  when  you 
are  done  with  it. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Compressing  Still  Images"  (V-2801) 

Related  Java  Methods 

qui ckti me . qd . Pi ct . f romlmageCompressi onDi al og( ) , 

qui ckti me . std . qt components . ImageCompressi onDi al og . compress  Pi cturet ) 


SCCompressPictureFile 


Compresses  a  Pi  cture  (IV-2331)  structure  that  is  stored  in  a  file. 

ComponentResul t  SCCompressPictureFile  ( 

Componentlnstance  ci  , 

short  srcRefNum, 

short  dstRef Num  ) ; 


Identifies  your  application's  connection  to  a  standard  image-compression 
dialog  component.  You  obtain  this  identifier  from  OpenDef  aul  tComponent 
(11-1131). 


srcRefNum 

A  reference  to  the  file  to  be  compressed. 
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dstRef Num 

A  reference  to  the  file  that  is  to  receive  the  compressed  data.  This  may  be  the 
same  as  the  source  file.  The  standard  dialog  component  places  the  compressed 
image  data  into  the  file  identified  by  this  reference.  Your  application  is 
responsible  for  this  file  after  the  compression  operation. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Compressing  Still  Images"  (V-2801) 

Related  Java  Methods 

qui cktime . std . qt components . ImageCompressi onDi al og . compress  Pi ctureFi 1 e( ) 


SCCompressSequenceBegin 


Initiates  a  sequence-compression  operation. 


Component  Res ul t  SCCompressSequenceBegi n 
Componentlnstance  ci  , 

PixMapHandle  src, 

const  Rect  *srcRect, 

ImageDescri pti onHandl e  *desc  ); 


( 


ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
component.  You  obtain  this  identifier  from  OpenDefaultComponent  (11-1131). 

src 

A  handle  to  the  Pi  xMap  (IV-2332)  structure  to  be  compressed.  This  pixel  map 
must  contain  the  first  image  in  the  sequence. 

srcRect 

A  pointer  to  a  portion  of  the  Pi  xMap  (IV-2332)  structure  to  compress  as  a  Rect 
(IV-2399)  structure.  This  rectangle  must  be  in  the  pixel  map's  coordinate 
system.  If  you  want  to  compress  the  entire  structure,  set  this  parameter  to  NIL. 

desc 

A  pointer  to  an  image  description  handle.  The  standard  dialog  component 
creates  an  image  description  structure  when  it  compresses  the  image,  and 
returns  a  handle  to  that  structure  in  the  field  referred  to  by  this  parameter.  The 
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SCCompressSequenceEnd 


component  sizes  the  handle  appropriately.  If  you  do  not  want  this  information, 
set  this  parameter  to  NIL. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Compressing  Image  Sequences"  (V-2802) 

Related  Java  Methods 

qui ckti me . std . qt components . ImageCompressi onDi al og . comp r ess Sequence Beg i n ( ) 


SCCompressSequenceEnd 


Ends  a  sequence-compression  operation. 

ComponentResul t  SCCompressSequenceEnd  ( 
Componentlnstance  ci  ); 


ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
component.  You  obtain  this  identifier  from  OpenDef  aul  tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  standard  dialog  component  disposes  of  any  memory  it  used  to  compress  the 
image  sequence,  including  the  data  and  image  description  buffers.  You  must  call 
this  function  once  for  each  sequence  you  start. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Compressing  Image  Sequences"  (V-2802) 


SCCompressSequenceFrame 


Continues  a  sequence-compression  operation. 
ComponentResul t  SCCompressSequenceFrame  ( 
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Componentlnstance 
Pi xMapHandl e 
const  Rect 
Handl e 
1  ong 
short 


ci  , 
src, 

*srcRect, 

*data , 

*dataSi ze , 
*notSyncFlag  ); 


ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
component.  You  obtain  this  identifier  from  OpenDefaultComponent  (11-1131). 


s 


A  handle  to  the  Pi  xMap  (IV-2332)  structure  to  be  compressed. 
srcRect 

A  pointer  to  a  portion  of  the  Pi  xMap  (IV-2332)  structure  to  compress  as  a  Rect 
(IV-2399)  structure.  This  rectangle  must  be  in  the  pixel  map's  coordinate 
system.  If  you  want  to  compress  the  entire  pixel  map,  set  this  parameter  to  NIL. 

data 

A  pointer  to  a  handle.  The  standard  dialog  component  returns  a  handle  to  the 
compressed  image  data  in  the  field  referred  to  by  this  parameter.  The 
component  sizes  that  handle  appropriately  for  the  sequence. 
dataSi ze 

A  pointer  to  a  long  integer.  The  standard  dialog  component  returns  a  value  that 
indicates  the  number  of  bytes  of  compressed  image  data  that  it  returns.  Note 
that  this  value  will  differ  from  the  size  of  the  handle  referred  to  by  the  data 
parameter,  because  the  handle  is  allocated  to  accommodate  the  largest  image  in 
the  sequence. 
notSyncFl ag 

A  pointer  to  a  short  integer  that  indicates  whether  the  compressed  frame  is  a 
key  frame.  If  the  frame  is  a  key  frame,  the  standard  dialog  component  sets  the 
field  referred  to  by  this  parameter  to  0;  otherwise,  the  component  sets  this  field 
to  medi  aSampl  eNotSync.  You  may  use  this  field  to  set  the  sampl  eFl  ags  parameter 
of  the  AddMedi  aSampl  e  (1-27)  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  must  call  this  function  once  for  each  frame  in  the  sequence,  including  the  first 
frame.  The  following  is  an  example  of  its  use: 

//  SCCompressSequenceFrame  coding  example 
//  See  “Discovering  QuickTime,”  page  246 
#define  kSampl eDurati on  240 
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SCCompressSequenceFrame 


//  video  frames 
#define  kNumVi deoFrames 
#define  kNoOffset 
#define  kMgrChoose 
#define  kSyncSample 
#define  kAddOneVi deoSampl e 
#define  kPixelDepth 

void  AddMyVi deoSampl esToMedia 
{ 

1  ong 

GWorl dPtr 
1  ong 
Handl e 
Ptr 

ImageDescriptionHandle 
CGraf Ptr 
GDHandl e 
OSErr 

Componentlnstance 
ComponentResul t 


last  240  *  l/600th  of  a  second 
29 
0 
0 
0 
1 

16 

(Media  media,  const  Rect  *rect) 

1  MaxCompressedSi ze ; 
pGWorld  =  NIL; 

1 CurSampl e ; 

hCompressedData  =  NIL; 
pCompressedData ; 
hlmageDesc  =  NIL; 
pOl dPort ; 
hghOl dDevi  ce ; 
nErr  =  noErr ; 
stdComponent  =  NIL; 
lErr  =  noErr; 


nErr  =  NewGWorldt&pGWorld, 

kPi xel Depth , 
rect , 

NIL, 

NIL, 

( GWorl  d FI  ags  )0 ) ; 


LockPixels(pGWorld->portPi xMap) ; 

nErr  =  GetMaxCompressionSize(pGWorld->portPixMap, 

rect , 

0,  //  let  ICM  choose  depth 

codec Normal  Qua  1 i ty , 
kAni mati onCodecType, 

( Comp  res so rComponen t ) any Codec , 

&1 MaxCompressedSi ze) ; 

hCompressedData  =  NewHandl e( 1 MaxCompressedSi ze) ; 
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MoveHHi ( h Compressed Data  ) ; 

HLock(hCompressedData) ; 

pCompressedData  =  StripAddress(*hCompressedData) ; 

hlmageDesc  =  ( ImageDescri pti onHandl e)NewHandl e(4) ; 

GetGWorl d(&p01 dPort ,  &hgh01 dDevi ce) ; 

SetGWorld(pGWorld,  NIL); 

nErr  =  OpenADef aul tComponentl StandardCompressi onType , 

Standard Comp res  si onSubType, 
stdComponent) ; 

lErr  =  SCCompressSequenceBeginlstdComponent, 

pGWorl d->portPixMap , 
rect , 

&hImageDesc) ; 

for  (lCurSample  =  1;  lCurSample  <  30;  1 CurSampl e++)  { 
short  syncFlag; 

EraseRectI rect) ; 

MyDrawAFramel rect ,  lCurSample); 

lErr  =  SCCompressSequenceFrame! stdComponent , 

pGWorl d->portPixMap , 
rect , 

&pComp res sed Data  ) , 
&(**hImageDesc).dataSize, 
&syncFl ag ) ; 


nErr  =  AddMedi aSampl e(medi a  , 

hCompressedData , 

0,  //  no  offset  in  data 

(**hImageDesc) .data  Size, 

60,  //  frame  duration  =  1/10  sec 

(SampleDescri pti onHandl elhlmageDesc, 

1,  //  one  sample 

syncFlag,  //  key  frame  or  not? 

NIL) ; 

} 

SetGWorl d( pOl dPort ,  hghOl dDevi ce) ; 

lErr  =  SCCompressSequenceEnd(stdComponent) ; 
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SCCompressSequenceFrameAsync 


if  ( 1  Err  !=  NIL) 

CloseComponent(stdComponent) ; 
if  (hlmageDesc  !=  NIL) 

DisposeHandle((Handle)hIniageDesc); 
if  ( hCompressedData  !=  NIL) 

DisposeHandlet  hCompressedData) ; 
if  (pGWorld  !=  NIL) 

DisposeGWorld(pGWorld) ; 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Compressing  Image  Sequences"  (V-2802) 

Related  Java  Methods 

qui ckti me . uti 1 . QTHandl eRef . f romSCSequencet ) 

See  Also 

For  an  asynchronous  version  of  this  function,  with  a  completion  callback,  see 
SCCompressSequenceFrameAsync  (III — 1538). 


SCCompressSequenceFrameAsync 


An  asynchronous  variant  of  SCCompressSequenceFrame  (III— 1534),  with  a  completion 
callback. 

ComponentResul t  SCCompressSequenceFrameAsync  ( 

Componentlnstance  ci  , 

PixMapHandle  src, 

const  Rect  *srcRect, 

Handle  *data, 

long  *dataSize, 

short  *notSyncFl ag , 

ICMCompl etionProcRecordPtr  asyncCompl etionProc) ; 


ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
component.  You  obtain  this  identifier  from  OpenDef  aul  tComponent  (11-1131). 

src 

A  handle  to  the  Pi  xMap  (IV-2332)  structure  to  be  compressed. 
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srcRect 

A  pointer  to  a  portion  of  the  Pi  xMap  (IV-2332)  structure  to  compress  as  a  Rect 
(IV-2399)  structure.  This  rectangle  must  be  in  the  pixel  map's  coordinate 
system.  If  you  want  to  compress  the  entire  pixel  map,  set  this  parameter  to  NIL. 

data 

A  pointer  to  a  handle.  The  standard  dialog  component  returns  a  handle  to  the 
compressed  image  data  in  the  field  referred  to  by  this  parameter.  The 
component  sizes  that  handle  appropriately  for  the  sequence. 

dataSi ze 

A  pointer  to  a  long  integer.  The  standard  dialog  component  returns  a  value  that 
indicates  the  number  of  bytes  of  compressed  image  data  that  it  returns.  Note 
that  this  value  will  differ  from  the  size  of  the  handle  referred  to  by  the  data 
parameter,  because  the  handle  is  allocated  to  accommodate  the  largest  image  in 
the  sequence. 
notSyncFl ag 

A  pointer  to  a  short  integer  that  indicates  whether  the  compressed  frame  is  a 
key  frame.  If  the  frame  is  a  key  frame,  the  standard  dialog  component  sets  the 
field  referred  to  by  this  parameter  to  0;  otherwise,  the  component  sets  this  field 
to  medi  aSampl  eNotSync.  You  may  use  this  field  to  set  the  sampl  eFl  ags  parameter 
of  the  AddMedi  aSampl  e  (1-27)  function. 
asyncCompl eti onProc 

A  pointer  to  an  ICMCompl  eti onProcRecord  (IV-2279)  structure.  If  you  pass  NIL, 
the  SCCompressSequenceFrameAsync  function  acts  like  SCCompressSequenceFrame 
(III— 1534). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

While  performing  asynchronous  compression  with  this  function,  you  should 
occasionally  call  SCAsyncIdl  e  (III— 1528).  This  gives  the  standard  compression 
component  an  opportunity  to  restart  its  compression  operation  if  it  needs  to  force  a 
key  frame. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

See  Also 

See  SCCompressSequenceFrame  (III — 1534). 
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SCDefaultPictFileSettings 


SCDefaultPictFileSettings 


Derives  default  compression  settings  for  a  Pi  ctu  re  (IV-2331)  structure  that  is  stored 
in  a  file. 

ComponentResul t  SCDefaultPictFileSettings  ( 

Componentlnstance  ci  , 

short  srcRef, 

short  moti on  ) ; 


ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
dialog  component.  You  obtain  this  identifier  from  OpenDef  aul  tComponent 
(11-1131). 

srcRef 

A  reference  to  the  file  to  be  analyzed, 
moti on 

Specifies  whether  the  image  is  part  of  a  sequence.  Set  this  parameter  to  TRUE  if 
the  image  is  part  of  a  sequence;  set  it  to  FALSE  if  you  are  working  with  a  single 
still  image. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Getting  Default  Settings  for  an  Image  or  a  Sequence" 
(V- 2800) 

Related  Java  Methods 

qui  ckti  me .  std .  qt  components  .  ImageCompressi  onDialog.defaultPictFileSettingsO 


SCDefaultPictHandleSettings 


Derives  default  compression  settings  for  a  Pi  ctu  re  (IV-2331)  structure  that  is  stored 
by  a  handle. 

ComponentResul t  SCDefaultPictHandleSettings  ( 

Componentlnstance  ci  , 

PicHandle  srcPicture, 

short  moti on  ) ; 
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ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
dialog  component.  You  obtain  this  identifier  from  OpenDefaul  tComponent 
(11-1131). 

srcPi cture 

A  handle  to  the  Picture  (IV-2331)  structure  to  be  analyzed, 
moti on 

Specifies  whether  the  image  is  part  of  a  sequence.  Set  this  parameter  to  TRUE  if 
the  image  is  part  of  a  sequence;  set  it  to  FALSE  if  you  are  working  with  a  single 
still  image. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Getting  Default  Settings  for  an  Image  or  a  Sequence" 
(Y-2S00) 

Related  Java  Methods 

qui cktime . std . qt components . ImageCompressi onDialog.defaultPi ctSetti ngs ( ) 


SCDefaultPixMapSettings 


Derives  default  compression  settings  for  an  image  that  is  stored  in  a  pixel  map. 

ComponentResul t  SCDefaultPixMapSettings  ( 

Componentlnstance  ci  , 

PixMapHandle  src, 

short  motion  ); 


Identifies  your  application's  connection  to  a  standard  image-compression 
dialog  component.  You  obtain  this  identifier  from  OpenDefaul  tComponent 
(11-1131). 


src 

A  handle  to  the  Pi  xMap  (IV-2332)  structure  to  be  analyzed. 
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moti on 

Specifies  whether  the  image  is  part  of  a  sequence.  Set  this  parameter  to  TRUE  if 
the  image  is  part  of  a  sequence;  set  it  to  FALSE  if  you  are  working  with  a  single 
still  image. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Getting  Default  Settings  for  an  Image  or  a  Sequence" 
(Y-2S00) 

Related  Java  Methods 

qui ckti me . std . qt components . ImageCompressi onDialog.defaul tPi xMapSetti ngs ( ) 


SCGetBestDeviceRect 


Determines  the  boundary  rectangle  that  surrounds  the  display  device  that  supports 
the  largest  color  or  grayscale  palette. 

ComponentResul t  SCGetBestDeviceRect  ( 

Componentlnstance  ci  , 

Rect  *r  ) ; 


ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
dialog  component.  You  obtain  this  identifier  from  OpenDef  aul  tComponent 
(11-1131). 

r 

A  pointer  to  a  Rect  (IV-2399)  structure.  The  function  returns  the  global 
coordinates  of  a  rectangle  that  surrounds  the  appropriate  display  device. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  standard  image-compression  dialog  component  uses  this  function  to  position 
rectangles  and  dialog  boxes  when  you  indicate  that  the  component  is  to  choose  the 
best  display  device.  It  subtracts  the  menu  bar  from  the  returned  rectangle  if  the  best 
device  is  also  the  main  display  device. 
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Special  Considerations 

In  general,  your  application  does  not  need  to  use  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui ckTi  meComponents  .  h 

Programming  summary:  "Positioning  Dialog  Boxes  and  Rectangles"  (V-2803) 


SCGetCompressFlags 


Gets  compression  flags  for  a  standard  image-compression  dialog  component. 

ComponentResul t  SCGetCompressFlags  ( 

Componentlnstance  ci  , 

long  *flags  ); 


ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
dialog  component.  You  obtain  this  identifier  from  OpenDefaul  tComponent 
(11-1131). 

fl  ags 

A  pointer  to  compression  flags  (see  below). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

scCompressFl aglgnoreldentical  Frames 
Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Related  Java  Methods 

qui cktime . std . qt components . ImageCompressi onDi al og . getCompressFl  ags ( ) 

See  Also 

For  the  corresponding  set  function,  see  SCSetCompress  Fl  ags  (III— 1557). 
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SCGetCompressionExtended 


Undocumented 


Component Res ul t  SCGetCompressi on  Ext ended 


Componentlnstance 

SCParams 

Poi  nt 

SCModal  Fi  1  terUPP 
SCModal HookUPP 
1  ong 

Stri ngPtr 


c  i  , 

*params , 
where , 
f  i  1 terProc , 
hookProc , 
refcon , 
customName  ) ; 


( 


ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
dialog  component.  You  obtain  this  identifier  from  OpenDef  aul  tComponent 
(11-1131). 

params 

A  pointer  to  an  SCParams  (IV-2420)  structure, 
where 

Undocumented 
f  i  1 terProc 

A  Universal  Procedure  Pointer  that  accesses  a  SCModal  Fi  1  terProc  (III— 2133) 
callback. 
hookProc 

A  Universal  Procedure  Pointer  that  accesses  a  SCModal  HookProc  (III— 2134) 
callback. 

refcon 

A  reference  constant  to  be  passed  to  your  callbacks.  Use  this  parameter  to  point 
to  a  data  structure  containing  any  information  your  callbacks  need. 
customName 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 
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SCGetlnfo 


Retrieves  configuration  information  from  the  standard  dialog  component. 

ComponentResul t  SCGetlnfo  ( 

Componentlnstance  ci  , 

OSType  infoType, 

void  *info  ); 


ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
dialog  component.  You  obtain  this  identifier  from  OpenDefaul  tComponent 
(11-1131). 

i nf oType 

A  constant  (see  below)  that  specifies  the  type  of  information  you  want  to 
retrieve. 

i  nf  o 

A  pointer  to  a  field  that  is  to  receive  the  information.  The  i  nf  oType  constant 
descriptions  (see  below)  include  information  about  this  field. 

function  result  See  "Error  Codes"  (IV-2663).  If  the  component  cannot  satisfy  your 
request,  it  returns  a  result  code  ofscTypeNotFoundErr.lt  returns  noErr 
if  there  is  no  error. 

infoType  Constants 

scSpati al Setti ngsType 

The  component's  spatial  compression  parameters  in  an  SCSpati  al  Setti  ngs 
(IV-2423)  structure. 
scTemporal Setti ngsType 

The  component's  temporal  compression  parameters  in  an  SCTemporal  Setti  ngs 
(IV-2427)  structure. 
scDataRateSetti ngsType 

Information  about  the  component's  compression  data  rate  in  an 
SCDataRateSetti  ngs  (IV-2417)  structure. 

scCol orTabl eType 

The  component's  color  table  as  a  pointer  to  a  CTabHandl  e,  which  references  a 
Col  orTabl  e  (IV-2210)  structure. 
scProgressProcType 

Apointertoa  ICMProgressProcRecord  (IV-2284)  structure.  Set  the  pointer  to  NIL 
to  clear  the  current  progress  function;  in  this  case,  the  standard  dialog 
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component  does  not  report  its  progress  to  the  user.  Set  the  pointer  to  -1  to  use 
the  component's  default  progress  function. 

scExtendedProcsType 

A  pointer  to  an  SCExtendedProcs  (IV-2418)  structure. 
scPreferenceFlagsType 

A  pointer  to  a  long  integer.  It  contains  constants  (see  below)  that  define 
preference  flags. 
scSettingsStateType 

A  pointer  to  a  handle  to  the  component's  complete  configuration.  Your 
application  is  responsible  for  disposing  of  the  handle  when  you  are  done  with 
it.  Set  the  pointer  to  N I L  to  reset  the  component  to  its  default  configuration. 

Your  application  is  not  concerned  with  the  content  of  the  configuration 
information  that  is  returned.  The  standard  dialog  component  saves  its 
configuration  in  a  format  that  it  understands.  This  request  affects  only  those 
settings  that  are  valid  across  system  restarts,  such  as  the  spatial  and  temporal 
compression  parameters  and  the  data-rate  settings.  When  you  retrieve  the 
settings,  the  standard  dialog  component  creates  an  appropriately-sized  handle 
and  places  its  current  configuration  information  into  the  handle.  When  you 
modify  the  settings,  you  supply  the  configuration  information  in  the  handle, 
and  the  component  copies  the  data  out  of  this  handle. 

scSequencelDType 

The  component's  current  image-compression  sequence  identifier  being  used  by 
the  component's  SCCompressSequenceFrame  (III— 1534)  function.  You  supply  a 
pointer  to  a  field  of  type  ImageSequence;  see  "Codec  Types"  (IV-2619).  The 
standard  dialog  component  returns  the  current  sequence  identifier  in  that  field. 

scWindowPositionType 

A  pointer  to  a  Point  (IV-2339)  structure.  If  you  are  retrieving  this  information, 
the  standard  dialog  component  places  the  coordinates  of  the  upper-left  comer 
of  the  dialog  box  into  this  structure;  if  you  are  changing  the  dialog  box's 
position,  place  the  new  coordinates  into  the  structure;  the  component  uses 
those  coordinates  to  position  the  dialog  box. 

Normally  you  should  not  need  to  use  this  request.  By  default,  the  standard 
dialog  component  centers  the  dialog  box  on  the  screen  that  is  best-suited  to 
display  your  test  image.  The  component  also  saves  the  last  window  position  for 
movable  modal  dialogs. 
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scCodecFl agsType 

A  pointer  to  a  field  of  type  CodecFlags  that  contains  flag  constants  (see below); 
see  "Codec  Types"  (IV-2619).  If  you  are  retrieving  the  flags,  the  standard  dialog 
component  places  the  current  flags  into  this  field.  If  you  are  setting  new  flag 
values,  place  your  desired  settings  into  the  field;  the  component  uses  these  new 
flag  settings. 

By  default,  the  standard  dialog  component  sets  all  flags  to  0  when  it  compresses 
still  images.  When  it  is  compressing  sequences,  the  component  sets  the 
codecFlagllpdatePrevious  and  codec  FI  agllpdatePrevi  ousComp  flags  to  1. 
Typically,  you  should  not  need  to  change  these  flag  settings. 

scPreferenceFlagsType  Constants 

scLi stEveryCodec 

Controls  the  contents  of  the  pop-up  menu  of  compressors.  If  you  set  this  flag  to 
1,  the  standard  image-compression  dialog  component  lists  every  compressor 
component  that  is  present  in  the  system.  Each  entry  in  the  list  contains  the  name 
of  a  compressor  component.  The  user  may  then  select  a  specific  component 
from  the  list.  If  you  set  this  flag  to  0,  the  list  contains  one  entry  for  each  type  of 
compressor  component  that  is  present  in  the  system.  Each  list  entry  contains  the 
name  of  a  compressor  type  (for  example,  a  list  entry  might  contain 
"Animation"  for  the  animation  compressor).  The  user  may  then  select  a  type  of 
compressor;  it  is  your  application's  responsibility  to  select  an  appropriate 
compressor  of  that  type. 

scAl 1 owZeroFrameRate 

Determines  whether  the  component  allows  the  user  to  specify  a  value  of  0  for 
the  frame  rate.  If  you  set  this  flag  to  1,  the  component  allows  the  user  to  specify 
either  0  or  nothing  for  the  frame  rate.  The  component  then  includes  a  "best 
rate"  entry  in  the  pop-up  menu.  If  the  user  specifies  0,  the  component  sets  the 
f  rameRate  field  in  the  SCTemporal  Setti  ngs  (IV-2427)  structure  to  0.  Your 
application  must  then  determine  the  best  frame  rate  for  the  movie.  If  you  set 
this  flag  to  0,  the  component  does  not  allow  the  user  to  enter  0  for  the  frame  rate. 
In  this  case,  the  user  must  select  a  specific  frame  rate. 

scAl 1 owZeroKeyFrameRate 

Similar  to  the  scAl  1  owZeroFrameRate  flag,  this  flag  determines  whether  the 
component  allows  the  user  to  specify  a  value  of  0  for  the  key  frame  rate.  If  you 
set  this  flag  to  1,  the  component  allows  the  user  to  specify  0  for  the  frame  rate. 
If  the  user  specifies  0,  the  component  sets  the  keyFrameRate  field  in  the 
SCTemporal  Setti  ngs  (IV-2427)  structure  to  0.  Your  application  must  then 
determine  the  best  key  frame  rate  for  the  movie.  If  you  set  this  flag  to  0,  the 
component  does  not  allow  the  user  to  specify  0  for  the  frame  rate.  In  this  case. 
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if  the  user  has  enabled  temporal  compression  by  checking  the  key  frame 
checkbox,  the  user  must  also  select  a  specific  key  frame  rate. 

scShowBestDepth 

Determines  whether  the  component  includes  a  "best  depth"  entry  in  the 
pop-up  menu  for  pixel  depth.  If  you  set  this  flag  to  1,  the  component  includes 
a  "best  depth"  entry  in  the  pop-up  menu.  If  the  user  selects  "best  depth,"  the 
component  sets  the  depth  to  0.  Your  application  must  then  determine  the  best 
pixel  depth  for  the  movie.  If  you  set  this  flag  to  0,  the  component  does  not 
include  a  "best  depth"  entry  in  the  pop-up  menu.  The  user  must  select  a  depth 
from  among  the  other  available  choices. 

sclIseMovabl  eModal 

Determines  whether  the  standard  compression  dialog  is  a  movable  or  a 
stationary  dialog.  Set  this  flag  to  1  to  create  a  movable  dialog.  In  this  case,  you 
should  provide  an  event  filter  function  to  handle  update  events;  use  the 
scExtendedProcsType  request  (see  above). 

scCodecFlagsType  Constants 

codec  FI  a  gllselmageB  uffer 

Controls  whether  the  decompressor  allocates  an  offscreen  buffer  for 
decompression.  If  your  application  sets  this  flag  to  1,  the  decompressor 
allocates  an  offscreen  buffer  the  size  of  the  compressed  image.  If  you  set  this 
flag  to  0,  the  decompressor  does  not  use  an  offscreen  image  buffer.  These  image 
buffers  are  useful  when  decompressing  sequences  that  were  created  using 
temporal  compression, 
codec  FI  a gUseScreen Buffer 

Controls  whether  the  decompressor  allocates  an  offscreen  destination  buffer 
during  decompression.  If  you  set  this  flag  to  1,  the  decompressor  allocates  an 
offscreen  buffer  the  size  of  the  destination  screen.  If  you  set  this  flag  to  0,  the 
decompressor  does  not  use  an  offscreen  screen  buffer.  Using  a  screen  buffer 
helps  to  reduce  tearing  that  may  result  when  decompressing  directly  to  the 
screen. 

codecFlagllpdatePrevious 

Controls  whether  the  compressor  updates  the  previous  image  buffer  during 
compression.  This  flag  is  only  used  with  sequences  that  are  being  temporally 
compressed.  If  you  set  this  flag  to  1,  the  compressor  copies  the  current  source 
image  into  the  previous  frame  buffer  at  the  end  of  the  frame  compression. 
codecFlagNoScreenUpdate 

Controls  whether  the  decompressor  updates  the  screen  image.  If  you  set  this 
flag  to  1,  the  decompressor  does  not  write  the  current  frame  to  the  screen,  but 
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does  write  the  frame  to  its  offscreen  image  buffer  (if  one  was  allocated).  If  you 
set  this  flag  to  0,  the  decompressor  writes  the  frame  to  the  screen. 

codec  FI  a g Was Compressed 

Indicates  to  the  compressor  that  the  image  to  be  compressed  has  been 
compressed  before.  This  information  may  be  useful  to  compressors  that  can 
compensate  for  the  image  degradation  that  may  otherwise  result  from  repeated 
compression  and  decompression  of  the  same  image.  Set  this  flag  to  1  to  indicate 
that  the  image  was  previously  compressed.  Set  this  flag  to  0  if  the  image  was 
not  previously  compressed. 

codec FI agDontOf f screen 

Controls  whether  the  decompressor  uses  the  offscreen  buffer  during  sequence 
decompression.  This  flag  is  only  used  with  sequences  that  have  been 
temporally  compressed.  If  this  flag  is  set  to  1,  the  decompressor  does  not  use 
the  offscreen  buffer  during  decompression.  Instead,  the  decompressor  returns 
an  error.  This  allows  your  application  to  refill  the  offscreen  buffer.  If  this  flag  is 
set  to  0,  the  decompressor  uses  the  offscreen  buffer  if  appropriate. 
codecFl  agUpdatePrevi  ousComp 

Controls  whether  the  compressor  updates  the  previous  image  buffer  with  the 
decompressed  image  data.  This  flag  is  only  used  with  temporal  compression 
and  is  similar  to  the  codecFl  agllpdatePrevi  ous  flag.  As  with  the 
codecFl  agllpdatePrevi  ous  flag,  if  you  set  this  flag  to  1,  the  compressor  updates 
the  previous  frame  buffer  at  the  end  of  the  frame  compression.  However,  this 
flag  causes  the  Image  Compression  Manager  to  update  the  frame  buffer  using 
an  image  obtained  by  decompressing  the  results  of  the  most  recent 
compression  operation,  rather  than  the  source  image. 

codecFl a g Force Key Frame 

Controls  whether  the  compressor  creates  a  key  frame  from  the  current  image. 
This  flag  is  only  used  with  temporal  compression.  If  you  set  this  flag  to  1,  the 
compressor  makes  the  current  image  a  key  frame.  If  you  set  this  flag  to  0,  the 
compressor  decides  based  on  other  criteria,  such  as  the  key  frame  rate,  whether 
to  create  a  key  frame  from  the  current  image. 

codecFl a gOnly Screen Update 

Controls  whether  the  decompressor  decompresses  the  current  frame.  If  you  set 
this  flag  to  1,  the  decompressor  writes  the  contents  of  its  offscreen  image  buffer 
to  the  screen,  but  does  decompress  the  current  frame.  If  you  set  this  flag  to  0, 
the  decompressor  decompresses  the  current  frame  and  writes  it  to  the  screen. 
You  can  set  this  flag  to  1  only  if  you  have  allocated  an  offscreen  image  buffer 
for  use  by  the  decompressor. 
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codecFl  agLi  veGrab 

Indicates  to  the  compressor  whether  the  current  sequence  results  from 
grabbing  live  video.  When  working  with  live  video,  compressors  operate  as 
quickly  as  possible  and  disable  some  additional  processing,  such  as 
compensation  for  previously  compressed  data.  Set  this  flag  to  1  when  you  are 
compressing  from  a  live  video  source;  the  compressor  then  operates  as  quickly 
as  it  can. 

codec  FI agllsedNewImageBuffer 

Indicates  to  your  application  that  the  decompressor  used  the  offscreen  image 
buffer  for  the  first  time  when  it  processed  this  frame.  If  this  flag  is  set  to  1,  the 
decompressor  used  the  image  buffer  for  this  frame  and  this  is  the  first  time  the 
decompressor  used  the  image  buffer  in  this  sequence.  If  this  flag  is  set  to  0,  the 
decompressor  did  not  use  the  image  buffer. 

codec  FI  a  gllsedl  mage  Buffer 

Indicates  to  your  application  that  the  decompressor  used  the  offscreen  image 
buffer  for  this  frame.  If  this  flag  is  set  to  1,  the  decompressor  used  the  image 
buffer.  If  this  flag  is  set  to  0,  the  decompressor  did  not  use  the  image  buffer. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Managing  the  Sound  Dialog"  (V-2895),  "Working  With 
Image  or  Sequence  Settings"  (V-2802) 

Related  Java  Methods 

qui ckti me . qd . Col orTabl e . f romCompressi onDi al og( ) 

qui  ckti  me .  std .  qt  components  .  ImageCompressi  onDialog.getlnfoSpatialSettingsO 
qui ckti me . std . qt components . ImageCompressi onDi al og . getlnfoTemporal Settings! ) 
qui ckti me . std . qt components . ImageCompressi onDialog.getlnfoDataRateSettingst) 
qui ckti me . std . qt components . ImageCompressi onDialog.getlnfoColorTable! ) 
qui ckti me . std . qt components . Comp  res si onDialog.getlnfoState! ) 
qui ckti me . std . qt components . Comp  res si onDi alog.getlnfo Preferences!) 
qui ckti me . std . qt components . SoundCompressi onDialog.getlnfoSampleRate! ) 
qui ckti me . std . qt components . SoundCompressi onDialog.getlnfoSampleSize! ) 
qui ckti me . std . qt components . SoundCompressi onDi alog.getlnfoChannel Count! ) 
qui ckti me . std . qt components . SoundCompressi onDi al og . getlnfoCompressi on ( ) 
qui ckti me . std . qt components . SoundCompressi onDi al og . getlnfoCompressi on  Li st ( ) 


See  Also 

For  the  corresponding  set  function,  see  SCSetlnfo  (III— 1558). 
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SCGetSettingsAsAtomContainer 


SCGetSettingsAsAtomContainer 


Places  the  current  configuration  from  the  standard  image-compression  component 
in  a  QT  atom  container. 

ComponentResul t  SCGetSettingsAsAtomContainer  ( 

Componentlnstance  ci  , 

QTAtomContai ner  *settings  ); 


ci 

The  standard  compression  component  instance, 
setti ngs 

The  address  where  the  newly-created  atom  container  should  be  stored. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  caller  is  responsible  for  disposing  of  the  returned  QT  atom  container. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Related  Java  Methods 

qui cktime . std .movi es . AtomContai ner . f romCompressi  onDi  al  og( ) 


SCGetSettingsAsText 


Undocumented 

ComponentResul t  SCGetSettingsAsText  ( 
Componentlnstance  ci  , 

Handle  *text  ); 


ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
dialog  component.  You  obtain  this  identifier  from  OpenDefaul  tComponent 
(11-1131). 

text 

A  pointer  to  a  handle  to  text. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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SCNewG  World 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


SCNewGWorld 


Creates  a  graphics  world  based  on  the  current  compression  settings. 


ComponentResul t  SCNewGWorld  ( 


Componentlnstance  ci  , 
GWorldPtr  *gwp, 

Rect  *rp, 

GWorldFlags  flags 


) : 


ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
dialog  component.  You  obtain  this  identifier  from  OpenDef  aul  tComponent 
(11-1131). 

gwp 

A  pointer  to  a  pointer  toaCGrafPort  (IV-2168)  structure  that  defines  a  graphics 
world.  The  standard  dialog  component  places  a  pointer  to  the  new  graphics 
world  into  the  field  referred  to  by  this  parameter.  If  the  component  cannot 
create  the  graphics  world,  it  sets  this  field  to  N I L. 

rp 

A  pointer  to  the  boundaries  of  the  graphics  world.  If  you  set  this  parameter  to 
N I L,  the  standard  dialog  component  uses  the  test  image's  boundary  rectangle. 
If  you  don't  specify  a  boundary  rectangle  and  there  is  no  test  image,  the 
component  does  not  create  the  graphics  world. 

fl  ags 

Contains  flags  (see  below)  that  determine  some  of  the  memory  characteristics 
of  the  new  graphics  world. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

pi xPurge 

Make  the  base  address  for  the  offscreen  pixel  image  purgeable. 
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SCPositionDialog 


noNewDevi ce 

Do  not  create  a  new  offscreen  GDevi  ce  (IV-2264)  structure;  instead,  use  either 
the  GDevi  ce  structure  you  specify  or  the  GDevi  ce  structure  for  a  video  card  on 
the  user's  system. 
useTempMem 

Create  the  base  address  for  an  offscreen  pixel  image  in  temporary  memory.  You 
generally  should  not  use  this  flag. 

keepLocal 

Create  a  pixel  image  in  main  memory  where  it  cannot  be  cached  to  a  graphics 
accelerator  card. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Creating  a  Compression  Graphics  World"  (V-2804) 

Related  Java  Methods 

qui cktime . std . qt components . ImageCompressi onDi al  og . newGWorl  d( ) , 
quicktime.qd.QDGraphics.QDGraphicsO 


SCPositionDialog 


Helps  position  a  dialog  box  on  the  screen. 

ComponentResul t  SCPositionDialog  ( 
Componentlnstance  ci  , 

short  id. 

Point  *where  ); 


ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
dialog  component.  You  obtain  this  identifier  from  OpenDefaul  tComponent 
(11-1131). 

i  d 

The  resource  number  of  a  '  DLOG '  resource.  The  function  positions  the  dialog 
box  that  corresponds  to  this  resource. 
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SCPositionRect 


where 

A  pointer  to  a  Point  (IV-2339)  structure  identifying  the  desired  location  of  the 
upper-left  corner  of  the  dialog  box  in  global  coordinates.  This  parameter  allows 
you  to  indicate  how  you  want  to  position  the  dialog  box  on  the  screen. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Positioning  Dialog  Boxes  and  Rectangles"  (V-2803) 


SCPositionRect 


Positions  a  rectangle  on  the  screen. 

ComponentResul t  SCPositionRect  ( 
Componentlnstance  ci  , 

Rect  *rp, 

Poi nt  *where  ) ; 


ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
dialog  component.  You  obtain  this  identifier  from  OpenDef aul  tComponent 
(11-1131). 

rp 

A  pointer  to  a  Rect  (IV-2399)  structure.  When  you  call  the  function,  this 
structure  should  contain  the  rectangle's  current  global  coordinates.  The 
function  adjusts  the  coordinates  in  the  structure  to  reflect  the  rectangle's  new 
position. 

where 

A  pointer  to  a  Point  (IV-2339)  structure  identifying  the  desired  location  of  the 
upper-left  corner  of  the  rectangle  in  global  coordinates.  This  parameter  allows 
your  application  to  position  the  rectangle  on  the  screen. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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SCRequestlmageSettings 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Positioning  Dialog  Boxes  and  Rectangles"  (V-2803) 


SCRequestlmageSettings 


Displays  the  standard  image  dialog  box  to  the  user  and  shows  default  settings  you 
have  established. 

ComponentResul t  SCRequestlmageSettings  ( 

Componentlnstance  ci  ); 


ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
dialog  component.  You  obtain  this  identifier  from  OpenDefaul  tComponent 
(11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Use  this  function  to  retrieve  the  user's  preferences  for  compressing  a  single  image; 
use  SCRequestSequenceSetti  ngs  (III— 1556)  when  you  are  working  with  an  image 
sequence.  Both  functions  manipulate  the  compression  settings  that  the  component 
stores  for  you. 

The  component  derives  the  current  settings  when  you  may  supply  an  image  to  the 
component  from  which  it  can  derive  default  settings.  If  you  have  not  set  any 
defaults,  but  you  do  supply  a  test  image  for  the  dialog,  the  component  examines  the 
test  image  and  derives  appropriate  default  values  based  upon  its  characteristics.  If 
you  have  not  set  any  defaults  and  do  not  supply  a  test  image,  the  component  uses 
its  own  default  values. 

Special  Considerations 

You  may  modify  the  settings  by  using  SCSetlnfo  (III— 1558).  You  may  customize  the 
dialog  boxes  by  specifying  a  modal-dialog  hook  function  or  a  custom  button.  You 
may  use  the  custom  button  to  invoke  an  ancillary  dialog  box  that  is  specific  to  your 
application. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Functions  R-Z 


III-1555 


SCRequestSequenceSettings 


Programming  Info 

C  interface  file:  QuickTimeComponents.h 

Programming  summary:  "Displaying  the  Standard  Image-Compression  Dialog 
Box"  (V-2801),  "Managing  the  Sound  Dialog"  (V-2895) 

Related  Java  Methods 

qui ckti me . uti 1 . QTHandl eRef . f romCompressi onDialogState(), 

qui ckti me . std . qt components . ImageCompressi onDialog.requestlmageSettingst ) , 

qui ckti me . std . qt components . Comp  res si onDialog.requestSettingst) 


See  Also 


See  SCRequestSequenceSetti ngs  (III — 1556). 


SCRequestSequenceSettings 


Displays  the  standard  sequence  dialog  box  to  the  user  and  shows  default  settings 
you  have  established. 

ComponentResul t  SCRequestSequenceSettings  ( 

Componentlnstance  ci  ); 


ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
dialog  component.  You  obtain  this  identifier  from  OpenDef  aul  tComponent 
(11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Use  SCRequestSequenceSettings  to  retrieve  the  user's  preferences  for  compressing 
an  image  sequence;  use  SCRequestlmageSetti  ngs  (III— 1555)  when  you  are  working 
with  a  single  image.  Both  functions  manipulate  the  compression  settings  that  the 
component  stores  for  you. 

The  component  derives  the  current  settings  when  you  may  supply  an  image  to  the 
component  from  which  it  can  derive  default  settings.  If  you  have  not  set  any 
defaults,  but  you  do  supply  a  test  image  for  the  dialog,  the  component  examines  the 
test  image  and  derives  appropriate  default  values  based  upon  its  characteristics.  If 
you  have  not  set  any  defaults  and  do  not  supply  a  test  image,  the  component  uses 
its  own  default  values. 

Special  Considerations 

You  may  modify  the  settings  by  using  SCSet  I  nf  o  (III— 1558).  You  may  customize  the 
dialog  boxes  by  specifying  a  modal-dialog  hook  function  or  a  custom  button.  You 
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SCSetCompressFlags 


may  use  the  custom  button  to  invoke  an  ancillary  dialog  box  that  is  specific  to  your 
application. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Displaying  the  Standard  Image-Compression  Dialog 
Box"  (V-2801) 

Related  Java  Methods 

qui cktime . std . qt components . ImageCompressi onDi al og . requestSequenceSetti ngs ( ) 


See  Also 


See  SCRequestlmageSetti  ngs  (III — 1555). 


SCSetCompressFlags 


Sets  compression  flags  for  a  standard  image-compression  dialog  component. 

ComponentResul t  SCSetCompressFlags  ( 

Componentlnstance  ci  , 

long  flags  ); 


ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
dialog  component.  You  obtain  this  identifier  from  OpenDefaul  tComponent 
(11-1131). 

fl  ags 

Flags  (see  below)  to  set. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

scCompressFl aglgnoreldentical  Frames 
Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Related  Java  Methods 

qui cktime . std . qt components . ImageCompressi onDi al og . setCompressFl  ags ( ) 
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SCSetlnfo 


See  Also 

For  the  corresponding  get  function,  see  SCGetCompress  FI  ags  (III— 1543). 


SCSetlnfo 


Modifies  the  standard  dialog  component's  configuration  information. 

ComponentResul t  SCSetlnfo  ( 

Componentlnstance  ci  , 

OSType  infoType, 

voi d  *1 nfo  )  ; 


ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
dialog  component.  You  obtain  this  identifier  from  OpenDef  aul  tComponent 
(11-1131). 

i nfoType 

A  constant  (see  below)  that  specifies  the  type  of  information  you  want  to  set. 

i  nfo 

A  pointer  to  a  field  that  contains  the  new  information.  The  i  nfoType  constant 
descriptions  (see  below)  include  information  about  this  field. 

function  result  See  "Error  Codes"  (IV-2663).  If  the  component  cannot  satisfy  your 
request,  it  returns  a  result  code  ofscTypeNotFoundEnn.  It  returns  noErr 
if  there  is  no  error. 

infoType  Constants 

scSpatialSettingsType 

The  component's  spatial  compression  parameters  inanSCSpatialSettings 
(IV-2423)  structure. 

scTemporal SettingsType 

The  component's  temporal  compression  parameters  in  an  SCTemporal  Setti  ngs 
(IV-2427)  structure. 

scDataRateSettingsType 

Information  about  the  component's  compression  data  rate  in  an 
SCDataRateSettings  (IV-2417)  structure. 
scCol orTabl eType 

The  component's  color  table  as  a  pointer  toaCTabHandle,  which  references  a 
Col  orTabl  e  (IV-2210)  structure. 
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scProgressProcType 

A  pointer  to  a  ICMProgressProc Record  (IV-2284)  structure.  Set  the  pointer  to  NI L 
to  clear  the  current  progress  function;  in  this  case,  the  standard  dialog 
component  does  not  report  its  progress  to  the  user.  Set  the  pointer  to  -1  to  use 
the  component's  default  progress  function, 
sc Extend edProcsType 

A  pointer  to  an  SC  Extended  P  rocs  (IV-2418)  structure. 
scPreferenceFlagsType 

A  pointer  to  a  long  integer.  It  contains  constants  (see  below)  that  define 
preference  flags. 
scSetti ngsStateType 

A  pointer  to  a  handle  to  the  component's  complete  configuration.  Your 
application  is  responsible  for  disposing  of  the  handle  when  you  are  done  with 
it.  Set  the  pointer  to  N I L  to  reset  the  component  to  its  default  configuration. 

Your  application  is  not  concerned  with  the  content  of  the  configuration 
information  that  is  returned.  The  standard  dialog  component  saves  its 
configuration  in  a  format  that  it  understands.  This  request  affects  only  those 
settings  that  are  valid  across  system  restarts,  such  as  the  spatial  and  temporal 
compression  parameters  and  the  data-rate  settings.  When  you  retrieve  the 
settings,  the  standard  dialog  component  creates  an  appropriately-sized  handle 
and  places  its  current  configuration  information  into  the  handle.  When  you 
modify  the  settings,  you  supply  the  configuration  information  in  the  handle, 
and  the  component  copies  the  data  out  of  this  handle. 
scSequencelDType 

The  component's  current  image-compression  sequence  identifier  being  used  by 
the  component's  SCCompressSequenceFrame  (III— 1534)  function.  You  supply  a 
pointer  to  a  field  of  type  ImageSequence;  see  "Codec  Types"  (IV-2619).  The 
standard  dialog  component  returns  the  current  sequence  identifier  in  that  field. 

scWi ndowPosi ti onType 

A  pointer  to  a  Point  (IV-2339)  structure.  If  you  are  retrieving  this  information, 
the  standard  dialog  component  places  the  coordinates  of  the  upper-left  corner 
of  the  dialog  box  into  this  structure;  if  you  are  changing  the  dialog  box's 
position,  place  the  new  coordinates  into  the  structure;  the  component  uses 
those  coordinates  to  position  the  dialog  box. 

Normally  you  should  not  need  to  use  this  request.  By  default,  the  standard 
dialog  component  centers  the  dialog  box  on  the  screen  that  is  best-suited  to 
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display  your  test  image.  The  component  also  saves  the  last  window  position  for 
movable  modal  dialogs. 

scCodecFl agsType 

A  pointer  to  a  field  of  type  CodecFlags  that  contains  flag  constants  (see  below); 
see  "Codec  Types"  (IV-2619).  If  you  are  retrieving  the  flags,  the  standard  dialog 
component  places  the  current  flags  into  this  field.  If  you  are  setting  new  flag 
values,  place  your  desired  settings  into  the  field;  the  component  uses  these  new 
flag  settings. 

scPreferenceFlagsType  Constants 

scLi stEveryCodec 

Controls  the  contents  of  the  pop-up  menu  of  compressors.  If  you  set  this  flag  to 
1,  the  standard  image-compression  dialog  component  lists  every  compressor 
component  that  is  present  in  the  system.  Each  entry  in  the  list  contains  the  name 
of  a  compressor  component.  The  user  may  then  select  a  specific  component 
from  the  list.  If  you  set  this  flag  to  0,  the  list  contains  one  entry  for  each  type  of 
compressor  component  that  is  present  in  the  system.  Each  list  entry  contains  the 
name  of  a  compressor  type  (for  example,  a  list  entry  might  contain 
"Animation"  for  the  animation  compressor).  The  user  may  then  select  a  type  of 
compressor;  it  is  your  application's  responsibility  to  select  an  appropriate 
compressor  of  that  type. 

scAl 1 owZeroFrameRate 

Determines  whether  the  component  allows  the  user  to  specify  a  value  of  0  for 
the  frame  rate.  If  you  set  this  flag  to  1,  the  component  allows  the  user  to  specify 
either  0  or  nothing  for  the  frame  rate.  The  component  then  includes  a  "best 
rate"  entry  in  the  pop-up  menu.  If  the  user  specifies  0,  the  component  sets  the 
f  rameRate  field  in  the  SCTemporal  Setti  ngs  (IV-2427)  structure  to  0.  Your 
application  must  then  determine  the  best  frame  rate  for  the  movie.  If  you  set 
this  flag  to  0,  the  component  does  not  allow  the  user  to  enter  0  for  the  frame  rate. 
In  this  case,  the  user  must  select  a  specific  frame  rate. 

scAl  1 owZero Key  Frame Rate 

Similar  to  the  scAl  1  owZeroFrameRate  flag,  this  flag  determines  whether  the 
component  allows  the  user  to  specify  a  value  of  0  for  the  key  frame  rate.  If  you 
set  this  flag  to  1,  the  component  allows  the  user  to  specify  0  for  the  frame  rate. 
If  the  user  specifies  0,  the  component  sets  the  keyFrameRate  field  in  the 
SCTemporal  Setti  ngs  (IV-2427)  structure  to  0.  Your  application  must  then 
determine  the  best  key  frame  rate  for  the  movie.  If  you  set  this  flag  to  0,  the 
component  does  not  allow  the  user  to  specify  0  for  the  frame  rate.  In  this  case, 
if  the  user  has  enabled  temporal  compression  by  checking  the  key  frame 
checkbox,  the  user  must  also  select  a  specific  key  frame  rate. 
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scShowBestDepth 

Determines  whether  the  component  includes  a  "best  depth"  entry  in  the 
pop-up  menu  for  pixel  depth.  If  you  set  this  flag  to  1,  the  component  includes 
a  "best  depth"  entry  in  the  pop-up  menu.  If  the  user  selects  "best  depth,"  the 
component  sets  the  depth  to  0.  Your  application  must  then  determine  the  best 
pixel  depth  for  the  movie.  If  you  set  this  flag  to  0,  the  component  does  not 
include  a  "best  depth"  entry  in  the  pop-up  menu.  The  user  must  select  a  depth 
from  among  the  other  available  choices. 
scUseMovabl eModal 

Determines  whether  the  standard  compression  dialog  is  a  movable  or  a 
stationary  dialog.  Set  this  flag  to  1  to  create  a  movable  dialog.  In  this  case,  you 
should  provide  an  event  filter  function  to  handle  update  events;  use  the 
scExtendedProcsType  request  (see  above). 

scCodecFlagsType  Constants 

codecFlagUselmageBuffer 

Controls  whether  the  decompressor  allocates  an  offscreen  buffer  for 
decompression.  If  your  application  sets  this  flag  to  1,  the  decompressor 
allocates  an  offscreen  buffer  the  size  of  the  compressed  image.  If  you  set  this 
flag  to  0,  the  decompressor  does  not  use  an  offscreen  image  buffer.  These  image 
buffers  are  useful  when  decompressing  sequences  that  were  created  using 
temporal  compression. 

codec  FI  agllseScreenBuf  fer 

Controls  whether  the  decompressor  allocates  an  offscreen  destination  buffer 
during  decompression.  If  you  set  this  flag  to  1,  the  decompressor  allocates  an 
offscreen  buffer  the  size  of  the  destination  screen.  If  you  set  this  flag  to  0,  the 
decompressor  does  not  use  an  offscreen  screen  buffer.  Using  a  screen  buffer 
helps  to  reduce  tearing  that  may  result  when  decompressing  directly  to  the 
screen. 

codecFl  agllpdatePrevi  ous 

Controls  whether  the  compressor  updates  the  previous  image  buffer  during 
compression.  This  flag  is  only  used  with  sequences  that  are  being  temporally 
compressed.  If  you  set  this  flag  to  1,  the  compressor  copies  the  current  source 
image  into  the  previous  frame  buffer  at  the  end  of  the  frame  compression. 

codec  FI  agNoScreenllpdate 

Controls  whether  the  decompressor  updates  the  screen  image.  If  you  set  this 
flag  to  1,  the  decompressor  does  not  write  the  current  frame  to  the  screen,  but 
does  write  the  frame  to  its  offscreen  image  buffer  (if  one  was  allocated).  If  you 
set  this  flag  to  0,  the  decompressor  writes  the  frame  to  the  screen. 
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codec  FI  a gWas Compressed 

Indicates  to  the  compressor  that  the  image  to  be  compressed  has  been 
compressed  before.  This  information  may  be  useful  to  compressors  that  can 
compensate  for  the  image  degradation  that  may  otherwise  result  from  repeated 
compression  and  decompression  of  the  same  image.  Set  this  flag  to  1  to  indicate 
that  the  image  was  previously  compressed.  Set  this  flag  to  0  if  the  image  was 
not  previously  compressed, 
codec  FI agDon tOff screen 

Controls  whether  the  decompressor  uses  the  offscreen  buffer  during  sequence 
decompression.  This  flag  is  only  used  with  sequences  that  have  been 
temporally  compressed.  If  this  flag  is  set  to  1,  the  decompressor  does  not  use 
the  offscreen  buffer  during  decompression.  Instead,  the  decompressor  returns 
an  error.  This  allows  your  application  to  refill  the  offscreen  buffer.  If  this  flag  is 
set  to  0,  the  decompressor  uses  the  offscreen  buffer  if  appropriate. 

codecFlagllpdatePrevi  o  us  Comp 

Controls  whether  the  compressor  updates  the  previous  image  buffer  with  the 
decompressed  image  data.  This  flag  is  only  used  with  temporal  compression 
and  is  similar  to  the  codecFl  agllpdatePrevi  ous  flag.  As  with  the 
codecFl  agllpdatePrevi  ous  flag,  if  you  set  this  flag  to  1,  the  compressor  updates 
the  previous  frame  buffer  at  the  end  of  the  frame  compression.  However,  this 
flag  causes  the  Image  Compression  Manager  to  update  the  frame  buffer  using 
an  image  obtained  by  decompressing  the  results  of  the  most  recent 
compression  operation,  rather  than  the  source  image. 
codecFl a g Force Key  Frame 

Controls  whether  the  compressor  creates  a  key  frame  from  the  current  image. 
This  flag  is  only  used  with  temporal  compression.  If  you  set  this  flag  to  1,  the 
compressor  makes  the  current  image  a  key  frame.  If  you  set  this  flag  to  0,  the 
compressor  decides  based  on  other  criteria,  such  as  the  key  frame  rate,  whether 
to  create  a  key  frame  from  the  current  image. 
codecFl  agOnlyScreenllpdate 

Controls  whether  the  decompressor  decompresses  the  current  frame.  If  you  set 
this  flag  to  1,  the  decompressor  writes  the  contents  of  its  offscreen  image  buffer 
to  the  screen,  but  does  decompress  the  current  frame.  If  you  set  this  flag  to  0, 
the  decompressor  decompresses  the  current  frame  and  writes  it  to  the  screen. 
You  can  set  this  flag  to  1  only  if  you  have  allocated  an  offscreen  image  buffer 
for  use  by  the  decompressor. 
codecFl  agLi  veGrab 

Indicates  to  the  compressor  whether  the  current  sequence  results  from 
grabbing  live  video.  When  working  with  live  video,  compressors  operate  as 
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quickly  as  possible  and  disable  some  additional  processing,  such  as 
compensation  for  previously  compressed  data.  Set  this  flag  to  1  when  you  are 
compressing  from  a  live  video  source;  the  compressor  then  operates  as  quickly 
as  it  can. 

codecFlagUsedNewImageBuffer 

Indicates  to  your  application  that  the  decompressor  used  the  offscreen  image 
buffer  for  the  first  time  when  it  processed  this  frame.  If  this  flag  is  set  to  1,  the 
decompressor  used  the  image  buffer  for  this  frame  and  this  is  the  first  time  the 
decompressor  used  the  image  buffer  in  this  sequence.  If  this  flag  is  set  to  0,  the 
decompressor  did  not  use  the  image  buffer. 

codecFlagllsedlmageBuffer 

Indicates  to  your  application  that  the  decompressor  used  the  offscreen  image 
buffer  for  this  frame.  If  this  flag  is  set  to  1,  the  decompressor  used  the  image 
buffer.  If  this  flag  is  set  to  0,  the  decompressor  did  not  use  the  image  buffer. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Managing  the  Sound  Dialog"  (V-2895),  "Working  With 
Image  or  Sequence  Settings"  (V-2802) 

Related  Java  Methods 

qui cktime . std . qt components . ImageCompressi onDialog.setlnfoSpatial Setti ngs ( ) 
qui cktime . std . qt components . ImageCompressi onDi al og . set  Inf oTemporal Setti ngs ( ) 
qui cktime . std . qt components . ImageCompressi onDi al og . set  Inf oDataRateSetti  ngs ( ) 
qui cktime . std . qt components . ImageCompressi onDialog.setlnfoColorTablel) 
qui cktime . std . qt components . Comp res  si onDi al og . set  Inf oStatel ) 
qui cktime . std . qt components . Comp res  si onDi al og . set  Inf oPreferences ( ) 
qui cktime . std . qt components . Sound Comp res  si onDi al og . set  Inf oSampl eRatel ) 
qui cktime . std . qt components . Sound Comp res  si onDi al og . set  Inf oSampl eSi ze( ) 
qui  cktime .  std  .  qt  components  .  Sound  Comp  res  si  onDialog.setlnfoChannelCountO 
qui cktime . std . qt components . Sound Comp res  si onDi al og . set  Inf oCompressi on ( ) 
qui cktime . std . qt components . Sound Comp res  si onDi al og . set  Inf oCompressi on  Li st( ) 


See  Also 

For  the  corresponding  get  function,  see  SCGetlnfo  (III— 1545). 
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SCSetSettingsFromAtomContainer 


Sets  the  standard  image-compression  component's  current  configuration  from  data 
in  a  QT  atom  container. 

ComponentResul t  SCSetSettingsFromAtomContainer  ( 

Componentlnstance  ci  , 

QTAtomContai ner  settings  ); 


ci 

Standard  compression  component  instance, 
setti ngs 

A  QT  atom  container  reference  to  the  settings. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  settings  QT  atom  container  may  contain  atoms  other  than  those  expected  by  the 
particular  component  type  or  may  be  missing  certain  atoms.  The  function  will  only 
use  settings  it  understands. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Related  Java  Methods 

qui  ckti  me .  std .  qt  components  .  Comp  res  si  onDialog.setlnfoStateO 


SCSetT  estlmagePictFile 


Sets  the  dialog  box's  test  image  from  a  Pi  cture  (IV-2331)  structure  that  is  stored  in 

a  picture  file. 

ComponentResul t  SCSetTestlmagePi ctFi 1 e  ( 

Componentlnstance  ci  , 

short  testFileRef, 

Rect  *testRect, 

short  testFl ags  ) ; 
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ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
dialog  component.  You  obtain  this  identifier  from  OpenDefaul  tComponent 
(11-1131). 

testFi 1 eRef 

Identifies  the  file  that  contains  the  new  test  image.  Your  application  is 
responsible  for  opening  this  file  before  calling  this  function.  You  must  also  close 
the  file  when  you  are  done  with  it.  You  must  clear  the  image  or  close  your 
connection  to  the  standard  image-compression  dialog  component  before  you 
close  the  file.  If  the  file  contains  a  large  image,  the  component  may  take  some 
time  to  display  the  standard  image-compression  dialog  box.  In  this  case,  the 
component  displays  the  watch  cursor  while  it  loads  the  test  image. 

testRect 

A  pointer  to  a  Rect  (IV-2399)  structure.  This  rectangle  specifies,  in  the 
coordinate  system  of  the  source  image,  the  area  of  interest  or  point  of  interest 
in  the  test  image.  The  area  of  interest  defines  a  portion  of  the  test  image  that  is 
to  be  shown  to  the  user  in  the  dialog  box.  Use  this  parameter  to  direct  the 
component  to  a  specific  portion  of  the  test  image.  The  component  uses  the  value 
of  the  testFlags  parameter  to  determine  how  it  transforms  large  images  before 
displaying  them  to  the  user. 
testFi ags 

Constants  (see  below)  that  specify  how  the  component  is  to  display  a  test  image 
that  is  larger  than  the  test  image  portion  of  the  dialog  box.  If  you  set  this 
parameter  to  0,  the  component  uses  a  default  method  of  its  own  choosing.  In  all 
cases,  the  component  centers  the  area  or  point  of  interest  in  the  test  image 
portion  of  the  dialog  box,  and  then  displays  some  part  of  the  test  image. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

testFlags  Constants 

scPreferCroppi ng 

The  component  should  crop  the  test  image  to  fit  the  test  image  portion  of  the 
dialog  box.  The  component  displays  the  part  of  the  image  that  fits  in  the  test 
image  portion  of  the  box.  If  the  image  is  smaller  than  the  space  allotted  in  the 
dialog  box,  the  component  does  not  alter  the  image  before  displaying  it;  the 
resulting  image  is  smaller  than  the  available  space. 

scPreferScal i ng 

The  component  should  scale  the  test  image  to  fit  the  test  image  portion  of  the 
dialog  box,  by  shrinking  it. 
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scPreferScali ngAndCroppi  ng 

The  component  should  both  scale  and  crop  the  test  image.  This  option  is  useful 
with  very  large  test  images.  The  component  first  shrinks  the  image  to 
approximately  the  size  of  the  test  image  portion  of  the  dialog  box,  then  trims 
the  image  so  that  it  fits  the  available  space. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Specifying  a  Test  Image"  (V-2803) 

Related  Java  Methods 

qui  ckti  me .  std .  qt  components  .  ImageCompressi  onDialog.setTestlmagePictFileO 


SCSetT  estlmagePictHandle 


Sets  the  dialog  box's  test  image  from  a  Pi  cture  (IV-2331)  structure  that  is  stored  in 
a  handle. 

ComponentResul t  SCSetTestlmagePictHandle  ( 

Componentlnstance  ci  , 

PicHandle  testPict, 

Rect  *testRect, 

short  testFl ags  ) ; 


ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
dialog  component.  You  obtain  this  identifier  from  OpenDef  aul  tComponent 
(11-1131). 

testPi ct 

Identifies  a  handle  that  contains  the  new  test  image.  Your  application  is 
responsible  for  disposing  of  this  handle  when  you  are  done  with  it.  You  must 
clear  the  image  or  close  your  connection  to  the  standard  image-compression 
dialog  component  before  you  dispose  of  this  handle  or  close  the  corresponding 
resource  file.  You  must  set  this  handle  as  nonpurgeable. 

testRect 

A  pointer  to  a  Rect  (IV-2399)  structure.  This  structure  specifies,  in  the 
coordinate  system  of  the  source  image,  the  area  of  interest  or  point  of  interest 
in  the  test  image.  The  area  of  interest  defines  a  portion  of  the  test  image  that  is 
to  be  shown  to  the  user  in  the  dialog  box.  Use  this  parameter  to  direct  the 
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component  to  a  specific  portion  of  the  test  image.  The  component  uses  the  value 
of  the  testFlags  parameter  to  determine  how  it  transforms  this  image  before 
displaying  it  to  the  user.  The  component  uses  the  testFl  ags  parameter  only 
when  the  test  image  is  larger  than  the  test  image  portion  of  the  dialog  box. 

testFl ags 

Constants  (see  below)  that  specify  how  the  component  is  to  display  a  test  image 
that  is  larger  than  the  test  image  portion  of  the  dialog  box.  If  you  set  this 
parameter  to  0,  the  component  uses  a  default  method  of  its  own  choosing.  In  all 
cases,  the  component  centers  the  area  or  point  of  interest  in  the  test  image 
portion  of  the  dialog  box,  and  then  displays  some  part  of  the  test  image. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

testFlags  Constants 

scPreferCroppi ng 

The  component  should  crop  the  test  image  to  fit  the  test  image  portion  of  the 
dialog  box.  The  component  displays  the  part  of  the  image  that  fits  in  the  test 
image  portion  of  the  box.  If  the  image  is  smaller  than  the  space  allotted  in  the 
dialog  box,  the  component  does  not  alter  the  image  before  displaying  it;  the 
resulting  image  is  smaller  than  the  available  space. 
scPreferScal i ng 

The  component  should  scale  the  test  image  to  fit  the  test  image  portion  of  the 
dialog  box,  by  shrinking  it. 

scPreferScal i ngAndCroppi  ng 

The  component  should  both  scale  and  crop  the  test  image.  This  option  is  useful 
with  very  large  test  images.  The  component  first  shrinks  the  image  to 
approximately  the  size  of  the  test  image  portion  of  the  dialog  box,  then  trims 
the  image  so  that  it  fits  the  available  space. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Specifying  a  Test  Image"  (V-2803) 

Related  Java  Methods 

qui cktime . std . qt components . ImageCompressi onDi al  og . setTestlmagePi  ct( ) 
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SCSetT  estlmagePixMap 


Sets  the  dialog  box's  test  image  from  a  Pi  cture  (IV-2331)  structure  that  is  stored  in 
a  PixMap  (IV-2332)  structure. 

ComponentResul t  SCSetTestlmagePixMap  ( 

Componentlnstance  ci  , 

PixMapHandle  testPixMap, 

Rect  *testRect, 

short  testFl ags  ) ; 


ci 

Identifies  your  application's  connection  to  a  standard  image-compression 
dialog  component.  You  obtain  this  identifier  from  OpenDef  aul  tComponent 
(11-1131). 

testPixMap 

A  handle  to  a  PixMap  (IV-2332)  structure  that  contains  the  new  test  image.  Your 
application  is  responsible  for  creating  this  structure  before  calling  the  function. 
You  must  also  dispose  of  the  structure  when  you  are  done  with  it.  You  must 
clear  the  image  or  close  your  connection  to  the  standard  image-compression 
dialog  component  before  you  dispose  of  the  structure. 

testRect 

A  pointer  to  a  Rect  (IV-2399)  structure.  This  rectangle  specifies,  in  the 
coordinate  system  of  the  source  image,  the  area  of  interest  or  point  of  interest 
in  the  test  image.  The  area  of  interest  defines  a  portion  of  the  test  image  that  is 
to  be  shown  to  the  user  in  the  dialog  box.  Use  this  parameter  to  direct  the 
component  to  a  specific  portion  of  the  test  image.  The  component  uses  the  value 
of  the  testFlags  parameter  to  determine  how  it  transforms  large  images  before 
displaying  them  to  the  user. 
testFl ags 

Constants  (see  below)  that  specify  how  the  component  is  to  display  a  test  image 
that  is  larger  than  the  test  image  portion  of  the  dialog  box.  If  you  set  this 
parameter  to  0,  the  component  uses  a  default  method  of  its  own  choosing.  In  all 
cases,  the  component  centers  the  area  or  point  of  interest  in  the  test  image 
portion  of  the  dialog  box,  and  then  displays  some  part  of  the  test  image. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

testFlags  Constants 

scPreferCroppi ng 

The  component  should  crop  the  test  image  to  fit  the  test  image  portion  of  the 
dialog  box.  The  component  displays  the  part  of  the  image  that  fits  in  the  test 
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image  portion  of  the  box.  If  the  image  is  smaller  than  the  space  allotted  in  the 
dialog  box,  the  component  does  not  alter  the  image  before  displaying  it;  the 
resulting  image  is  smaller  than  the  available  space. 

scPreferScal i ng 

The  component  should  scale  the  test  image  to  fit  the  test  image  portion  of  the 
dialog  box,  by  shrinking  it. 

scPreferScal i ngAndCroppi  ng 

The  component  should  both  scale  and  crop  the  test  image.  This  option  is  useful 
with  very  large  test  images.  The  component  first  shrinks  the  image  to 
approximately  the  size  of  the  test  image  portion  of  the  dialog  box,  then  trims 
the  image  so  that  it  fits  the  available  space. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui ckTi  meComponents  .  h 

Programming  summary:  "Specifying  a  Test  Image"  (V-2803) 

Related  Java  Methods 

qui  cktime .  std  .  qt  components  .  ImageCompressi  onDialog.setTestlmagePixMapO 


SelectMovieAlternates 


Instructs  the  Movie  Toolbox  to  select  appropriate  tracks  immediately. 

void  SelectMovieAlternates  ( 

Movie  theMovie  ); 


theMovi e 

A  movie  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e 
(11-1084). 

function  result  You  can  access  this  function's  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Alternate  Tracks"  (V-2738) 
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Related  Java  Methods 

quicktime.std.movies.Movie.selectAlternatest) 


Set  AutoT  rackAlternatesEnabled 


Enables  or  disables  automatic  track  selection  by  the  Movie  Toolbox. 

void  SetAutoTrackAlternatesEnabled  ( 

Movie  theMovie, 

Bool ean  enabl e  ) ; 


theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovieFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
enabl e 

Controls  automatic  track  selection.  Set  this  parameter  to  TRUE  to  enable 
automatic  track  selection.  Set  this  parameter  to  FALSE  to  disable  automatic  track 
selection. 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Alternate  Tracks"  (V-2738) 

Related  Java  Methods 

quicktime.std.movies.Movie.setAutoTrackAlternatesEnabledO 


SetComponentInstanceA5 


Obsolete. 

void  SetComponentInstanceA5  ( 

Component  Instance  a Component  Instance , 

1 ong  theA5  ) ; 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier.  Macintosh  Note:  Not  supported  by 

CarbonLib. 

Programming  Info 

C  interface  file:  Components  .  h 

See  Also 

For  the  corresponding  get  function,  see  GetComponentInstanceA5  (1-390). 


SetComponentlnstanceError 

Lets  a  component  pass  error  information  to  the  Component  Manager  other  than 
through  its  return  value. 

void  SetComponentlnstanceError  ( 

Component  Instance  a Component  Instance , 

OSErr  theError  ); 

a Component  Instance 

A  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef aul  tComponent  (11-1131).  The  Component 
Manager  also  provides  a  component  instance  to  your  component  as  the  first 
parameter  in  the  pa  rams  field  of  the  ComponentParameters  (IV-2216)  record. 

theError 

The  new  value  for  the  current  error.  The  Component  Manager  uses  this  value 
to  set  the  current  error  for  the  connection  specified  by  the  aComponentlnstance 
parameter. 

Discussion 

Although  your  component  usually  returns  error  information  as  its  function  result, 
your  component  can  choose  to  use  this  function  to  pass  error  information  to  the 
Component  Manager.  The  Component  Manager  uses  this  error  information  to  set 
the  current  error  value  for  the  appropriate  connection.  Applications  can  then 
retrieve  this  error  information  by  calling  GetComponentlnstanceError  (1-390). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 
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See  Also 

For  the  corresponding  get  function,  see  GetComponentlnstanceError  (1-390). 


SetComponentlnstanceStorage 

Lets  a  component  pass  the  Component  Manager  a  handle  to  the  memory  that  was 
allocated  for  the  connection  to  it. 

void  SetComponentlnstanceStorage  ( 

Component  Instance  a Component  Instance , 

Handl e  theStorage  ) ; 

a Component  Instance 

A  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131).  The  Component 
Manager  also  provides  a  component  instance  to  your  component  as  the  first 
parameter  in  the  params  field  of  the  ComponentParameters  (IV-2216)  record. 
theStorage 

A  handle  to  the  memory  that  your  component  has  allocated  for  the  connection. 
Your  component  must  allocate  this  memory  in  the  current  heap.  The 
Component  Manager  saves  this  handle  and  provides  it  to  your  component, 
along  with  other  parameters,  in  subsequent  requests  to  this  connection. 

Special  Considerations 

Your  component  should  dispose  of  any  allocated  memory  for  the  connection  only 
in  response  to  the  close  request.  Note  that  whenever  an  open  request  fails,  the 
Component  Manager  always  issues  the  close  request.  Furthermore,  the  value  stored 
by  this  function  is  always  passed  to  the  close  request,  so  it  must  be  valid  or  N I L.  If 
the  open  request  tries  to  dispose  of  its  allocated  memory  before  returning,  it  should 
call  this  function  again  with  a  N I L  handle  to  keep  the  Component  Manager  from 
passing  an  invalid  handle  to  the  close  request. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 

See  Also 

For  the  corresponding  get  function,  see  GetComponentlnstanceStorage  (1-391). 
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SetComponentRefcon 


Sets  the  reference  constant  for  a  component. 

void  SetComponentRefcon  ( 

Component  aComponent, 

long  theRefcon  ); 

aComponent 

A  component  instance.  Your  software  obtains  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef aul  tComponent  (11-1131).  The  Component 
Manager  also  provides  a  component  instance  to  your  component  as  the  first 
parameter  in  the  pa  rams  field  of  the  ComponentParameters  (IV-2216)  record. 

theRefcon 

The  reference  constant  value  that  you  want  to  set  for  your  component. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components  .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 

See  Also 

For  the  corresponding  get  function,  see  GetComponentRefcon  (1-394). 


SetCompressedPixMapInfo 


Stores  information  about  a  compressed  image  for  StdPi  x  (III— 1912). 


OSErr  SetCompressedPixMapInfo 
Pi xMapPtr 

ImageDescri pti onHandl e 
Ptr 
1  ong 

ICMDataProc Record Ptr 
ICMProgressProc Record Ptr 


pix, 
desc , 
data , 

buf f erSi ze , 
dataProc, 
progressProc  ); 


pi  x 

A  pointer  to  a  Pi  xMap  (IV-2332)  structure  that  holds  compressed  image  data. 

desc 

A  handle  to  the  ImageDescri  pti  on  (IV-2285)  structure  that  defines  the 
compressed  image. 
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SetCSequenceDataRateParams 


data 

A  pointer  to  the  buffer  for  the  compressed  image  data.  If  the  entire  compressed 
image  cannot  be  stored  at  this  location,  you  may  assign  a  data-loading  function 
(see  the  dataProc  parameter,  below).  This  pointer  must  contain  a  32-bit  clean 
address. 
bufferSi ze 

The  size  of  the  buffer  to  be  used  by  the  data-loading  function  specified  by  the 
dataProc  parameter.  If  there  is  no  data-loading  function  defined  for  this 
operation,  set  this  parameter  to  0. 

dataProc 

A  pointer  to  an  ICMDataProcRecord  (IV-2279)  structure.  If  there  is  not  enough 
memory  to  store  the  compressed  image,  the  decompressor  calls  anICMDataProc 
(III— 2090)  callback  that  you  provide,  which  loads  more  compressed  data.  If  you 
do  not  want  to  assign  a  data-loading  function,  set  this  parameter  to  NIL. 
progressProc 

A  pointer  to  an  ICMProgressProcRecord  (IV-2284)  structure.  During  the 
decompression  operation,  the  decompressor  may  occasionally  call  an 
ICMProgressProc  (III— 2093)  callback  that  you  provide,  in  order  to  report  its 
progress.  If  you  do  not  want  to  assign  a  progress  function,  set  this  parameter 
to  NIL.  If  you  pass  a  value  of  -1,  you  obtain  a  standard  progress  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  the  StdPix  Function"  (V-2797) 

See  Also 

For  the  corresponding  get  function,  see  GetCompressedPixMapInfo  (1-397). 


SetCSequenceDataRateParams 


Communicates  information  to  compressors  that  can  constrain  compressed  data  in  a 
particular  sequence  to  a  specific  data  rate. 

OSErr  SetCSequenceDataRateParams  ( 

ImageSequence  seqlD, 

DataRateParamsPtr  params  ); 
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SetCSequenceFlushProc 


seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi  n  (1-238). 
params 

A  pointer  to  a  DataRateParams  (IV-2231)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Constraining  Compressed  Data"  (V-2795) 

Related  Java  Methods 

qui ckti me . std . image . CSequence . set Data  Rate Pa  rams ( ) 

See  Also 

For  the  corresponding  get  function,  see  GetCSequenceDataRateParams  (1-403). 


SetCSequenceFlushProc 


Assigns  a  data-unloading  function  to  a  sequence. 

OSErr  SetCSequenceFlushProc  ( 

ImageSequence  seqlD, 

ICMF1 ushProcRecordPtr  flushProc, 

long  bufferSize  ); 

seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi  n  (1-238). 

f 1 ushProc 

A  pointer  to  an  ICMF1  ushProcRecord  (IV-2280)  structure.  If  there  is  not  enough 
memory  to  store  the  compressed  image,  the  compressor  calls  an  I  CM  FI  ushProc 
(III— 2091)  callback  that  you  provide,  which  unloads  some  of  the  compressed 
data.  If  you  have  not  provided  such  a  data-unloading  function,  set  this 
parameter  to  NIL.  In  this  case,  the  compressor  writes  the  entire  compressed 
image  into  the  memory  location  specified  by  the  data  parameter  to 
CompressSequenceFrame  (1-124). 
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SetCSequenceFrameNumber 


bufferSi ze 

The  size  of  the  buffer  to  be  used  by  the  data-unloading  function  specified  by  the 
flushProc  parameter.  If  you  have  not  specified  such  a  data-unloading  function, 
set  this  parameter  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Data-unloading  functions  allow  compressors  to  work  with  images  that  cannot  fit  in 
memory.  During  the  compression  operation,  the  compressor  calls  the 
data-unloading  function  whenever  it  has  accumulated  a  specified  amount  of 
compressed  data.  Your  data-unloading  function  then  writes  the  compressed  data  to 
some  other  device,  freeing  buffer  space  for  more  compressed  data.  The  compressor 
starts  using  the  data-unloading  function  with  the  next  image  in  the  sequence. 

Special  Considerations 

There  is  no  parameter  to  the  CompressSequenceBegin  (1-1 19)  function  that  allows  you 
to  assign  a  data-unloading  function  to  a  sequence. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Changing  Sequence-Compression  Parameters"  (V-2794) 


SetCSequenceFrameNumber 


Informs  the  compressor  in  use  for  the  specified  sequence  that  frames  are  being 
compressed  out  of  order. 

OSErr  SetCSequenceFrameNumber  ( 

ImageSequence  seqlD, 

1 ong  f rameNumber  ) ; 


seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi n  (1-238). 

f rameNumber 

The  frame  number  of  the  frame  that  is  being  compressed  out  of  sequence. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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SetCSequenceKeyFrameRate 


Discussion 

This  information  is  necessary  only  for  compressors  that  are  sequence-sensitive. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Related  Java  Methods 

qui cktime . std . i mage . CSequence . setFrameNumber( ) 

See  Also 

For  the  corresponding  get  function,  see  GetCSequenceFrameNumber  (1-404) . 


SetCSequenceKeyFrameRate 


Adjusts  the  key  frame  rate  for  the  current  sequence. 

OSErr  SetCSequenceKeyFrameRate  ( 

ImageSequence  seqlD, 

long  keyFrameRate  ); 

seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi  n  (1-238). 

keyFrameRate 

The  maximum  number  of  frames  allowed  between  key  frames.  Set  this 
parameter  to  1  to  specify  all  key  frames,  to  2  to  specify  every  other  frame  as  a 
key  frame,  to  3  to  specify  every  third  frame  as  a  key  frame,  and  so  forth.  The 
compressor  determines  the  optimum  placement  for  key  frames  based  upon  the 
amount  of  redundancy  between  adjacent  images  in  the  sequence. 
Consequently,  the  compressor  may  insert  key  frames  more  frequently  than  you 
have  requested.  However,  the  compressor  will  never  place  fewer  key  frames 
than  is  indicated  by  this  parameter.  If  you  set  this  parameter  to  0,  the  Image 
Compression  Manager  only  places  key  frames  in  the  compressed  sequence 
when  you  call  CompressSequenceFrame  (1-124),  setting  the 
codecFl  agForceKey  Frame  flag  in  the  fl  ags  parameter.  The  compressor  ignores 
this  parameter  if  you  have  not  requested  temporal  compression;  that  is,  you 
have  passed  0  for  the  temporal  Qual  i  ty  parameter  of  CompressSequenceBegi  n 
(1-119). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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SetCSequencePreferredPacketSize 


Discussion 

Key  frames  provide  points  from  which  a  temporally  compressed  sequence  may  be 
decompressed.  Use  this  parameter  to  control  the  frequency  at  which  the  compressor 
places  key  frames  into  the  compressed  sequence.  The  new  key  frame  rate  takes 
effect  with  the  next  image  in  the  sequence. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Changing  Sequence-Compression  Parameters"  (V-2794) 

Related  Java  Methods 

quicktime.std.image.CSequence . set Key FrameRatet ) 


See  Also 

For  the  corresponding  get  function,  see  GetCSequenceKeyFrameRate  (1-405). 


SetCSequencePreferredPacketSize 


Sets  the  preferred  packet  size  for  a  sequence. 

OSErr  SetCSequencePreferredPacketSi ze  ( 
ImageSequence  seqlD, 

long  preferredPacketSi zelnBytes  ); 


seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi n  (1-238). 

preferredPacketSi zelnBytes 

The  preferred  packet  size  in  bytes. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

This  function  was  added  in  QuickTime  2.5  to  support  video  conferencing 
applications  by  making  each  transmitted  packet  an  independently  decodable  chunk 
of  data. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Changing  Sequence-Compression  Parameters"  (V-2794) 

Related  Java  Methods 

quicktime.std.image.CSequence.setPreferredPacketSizet) 
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SetCSequencePrev 


Allows  the  application  to  set  the  pixel  map  and  boundary  rectangle  used  by  the 
previous  frame  in  temporal  compression. 

OSErr  SetCSequencePrev  ( 

ImageSequence  seqlD, 

PixMapHandle  prev, 

const  Rect  *prevRect  ); 

seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi  n  (1-238). 

prev 

A  handle  to  the  new  previous  image  buffer.  You  must  allocate  this  buffer  using 
the  same  pixel  depth  and  Col  orTabl  e  (IV-2210)  structure  as  the  source  image 
buffer  that  you  specified  with  the  src  parameter  when  you  called 
CompressSequenceBegi  n  (1-119).  The  compressor  uses  this  buffer  to  store  a 
previous  image  against  which  the  current  image  is  compared  when  performing 
temporal  compression.  The  compressor  manages  the  contents  of  this  buffer 
based  upon  several  considerations,  such  as  the  key  frame  rate  and  the  degree 
of  difference  between  compared  images.  The  current  image  is  stored  in  the 
buffer  referred  to  by  the  src  parameter  to  CompressSequenceBegi  n. 
prevRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  defines  the  portion  of  the  previous 
image  to  use  for  temporal  compression.  The  compressor  uses  this  portion  of  the 
previous  image  as  the  basis  of  comparison  with  the  current  image.  This 
rectangle  must  be  the  same  size  as  the  source  rectangle  you  specify  with  the 
srcRect  parameter  to  CompressSequenceBegi  n  (1-119).  To  get  the  boundary  of  a 
source  pixel  map,  set  this  parameter  to  N I L. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

When  you  start  compressing  a  sequence,  you  may  assign  a  previous  frame  buffer 
and  rectangle  with  the  prev  and  prevRect  parameters  to  CompressSequenceBegi  n 
(1-119).  If  you  specified  a  N I L  value  for  the  prev  parameter,  the  compressor  allocates 
an  offscreen  buffer  for  the  previous  frame.  In  either  case  you  may  use  this  function 
to  assign  a  new  previous  frame  buffer. 

Special  Considerations 

This  is  a  very  specialized  function;  your  application  should  not  need  to  call  it  under 
most  circumstances. 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Changing  Sequence-Compression  Parameters"  (V-2794) 

Related  Java  Methods 

quicktime.std.image.CSequence.setPrevO 


SetCSequenceQuality 


Adjusts  the  spatial  or  temporal  quality  for  the  current  sequence. 

OSErr  SetCSequenceQuality  ( 

ImageSequence  seqlD, 

CodecQ  spati al Qual i ty , 

CodecQ  temporal Qual i ty  ); 

seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi n  (1-238). 
spati al Qual i ty 

A  constant  (see  below)  that  specifies  the  desired  compressed  image  quality, 
temporal Qual i ty 

A  constant  (see  below)  that  specifies  the  desired  sequence  temporal  quality. 
This  parameter  governs  the  level  of  compression  you  desire  with  respect  to 
information  between  successive  frames  in  the  sequence.  Set  this  parameter  to  0 
to  prevent  the  compressor  from  applying  temporal  compression  to  the 
sequence. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

spatialQuality  and  temporalQuality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 

codecNormal Qual i ty 

Image  reproduction  of  normal  quality. 
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codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 
codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field, 
codec Los  si essQual i ty 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

Discussion 

You  originally  set  the  default  spatial  and  temporal  quality  values  for  a  sequence 
with  CompressSequenceBegi  n  (1-119).  The  new  quality  parameters  take  effect  with 
the  next  frame  in  the  sequence. 

Special  Considerations 

If  you  change  the  quality  settings  while  processing  an  image  sequence,  you  affect 
the  maximum  image  size  that  you  may  receive  during  sequence  compression. 
Consequently,  you  should  call  GetMaxCompressi  onSi  ze  (1-420)  after  you  change  the 
quality  settings.  If  the  maximum  size  has  increased,  you  should  reallocate  your 
image  buffers  to  accommodate  the  larger  image  size. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Changing  Sequence-Compression  Parameters"  (V-2794) 

Related  Java  Methods 

qui ckti me . std . image . CSequence . setQual i ty ( ) 


SetDefaultComponent 


Changes  the  search  order  for  registered  components. 

OSErr  SetDefaultComponent  ( 

Component  aComponent, 

short  flags  ); 

aComponent 

The  component  that  is  to  be  placed  at  the  front  of  the  search  chain.  Your 
software  obtains  this  reference  from  OpenComponent  (11-1130)  or 
OpenDef  aul  tComponent  (11-1131).  The  Component  Manager  also  provides  a 
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SetDefaultOutput  Volume 


component  instance  to  your  component  as  the  first  parameter  in  the  pa  rams 
field  of  the  ComponentParameters  (IV-2216)  record. 

fl  ags 

A  constant  (see  below)  that  controls  which  fields  of  the  ComponentDescri  pti  on 
(IV-2212)  structure  the  Component  Manager  examines  during  the  reorder 
operation.  Set  the  appropriate  flags  to  1  to  define  the  fields  that  are  examined. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constants 

defaul tComponentldenti  cal 

The  Component  Manager  places  the  specified  component  in  front  of  all  other 
components  that  have  the  same  component  description, 
defaul t Component Any Fl  ags 

The  Component  Manager  ignores  the  value  of  the  componentFl  ags  field  during 
the  reorder  operation. 

defaul t Component Any Manufacturer 

The  Component  Manager  ignores  the  value  of  the  componentManuf  acturer  field 
during  the  reorder  operation. 

defaul t Component Any SubType 

The  Component  Manager  ignores  the  value  of  the  componentSubType  field 
during  the  reorder  operation. 

Discussion 

You  specify  a  component  that  is  to  be  placed  at  the  front  of  the  search  chain,  along 
with  control  information  that  governs  the  reordering  operation.  The  order  of  the 
search  chain  influences  which  component  the  Component  Manager  selects  in 
response  to  an  application's  use  of  OpenDef  aul  tComponent  (11-1131)  and 
Fi ndNextComponent  (1-360). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components. h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 


SetDef  aultOutputV  olume 


Sets  the  default  volume  of  the  sound  output  device. 
OSErr  SetDefaul tOutputVol ume  ( 
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long  level  ); 

1  evel 

The  desired  default  volume  level.  The  values  you  can  specify  in  the  high  and 
low  words  of  the  level  parameter  range  from  0  (silence)  to  0x0100  (full  volume). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

You  can  call  this  function  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

For  the  corresponding  get  function,  see  GetDefaul  tOutputVol  ume  (1-408). 


SetDSequenceAccuracy 


Adjusts  the  decompression  accuracy  for  the  current  sequence. 

OSErr  SetDSequenceAccuracy  ( 

ImageSequence  seqlD, 

CodecQ  accuracy  ); 

seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi  n  (1-238). 
accuracy 

A  constant  (see  below)  that  specifies  the  accuracy  desired  in  the  decompressed 
image. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

accuracy  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 
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codecNormal Qua! i ty 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 

codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field, 
codec LosslessQuality 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

Discussion 

The  accuracy  parameter  governs  how  precisely  the  decompressor  decompresses  the 
image  data.  Some  decompressors  may  choose  to  ignore  some  image  data  to 
improve  decompression  speed.  A  new  accuracy  value  takes  effect  with  the  next 
frame  in  the  sequence. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Changing  Sequence-Decompression  Parameters" 
(V-2795) 

Related  Java  Methods 

quicktime.std.image.DSequence .  set Accu racy ( ) 


See  Also 

You  set  the  default  accuracy  value  for  a  sequence  with  the  accuracy  parameter  to 
DecompressSequenceBegi  n  (1-238). 


SetDSequenceDataProc 


Assigns  a  data-loading  function  to  a  sequence. 

OSErr  SetDSequenceDataProc  ( 

ImageSequence  seqlD, 

ICMDataProcRecordPtr  dataProc, 

1 ong  bufferSi ze  ) ; 
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SetDSequenceFlags 


seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi  n  (1-238). 
dataProc 

A  pointer  to  an  ICMDataProcRecord  (IV-2279)  structure.  If  the  data  stream  is  not 
all  in  memory  when  your  program  calls  DecompressSequenceFrame  (1-242),  the 
decompressor  calls  an  ICMDataProc  (III— 2090)  callback  that  you  provide,  which 
loads  more  compressed  data.  If  you  have  not  provided  such  a  data-loading 
function,  or  if  you  want  the  decompressor  to  stop  using  your  data-loading 
function,  set  this  parameter  to  NIL.  In  this  case,  the  entire  image  must  be  in 
memory  at  the  location  specified  by  the  data  parameter  to 
DecompressSequenceFrame. 

but ferSi ze 

The  size  of  the  buffer  to  be  used  by  the  data-loading  function  specified  by  the 
dataProc  parameter.  If  you  have  not  specified  a  data-loading  function,  set  this 
parameter  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Data-loading  functions  allow  decompressors  to  work  with  images  that  cannot  fit  in 
memory.  During  the  decompression  operation  the  decompressor  calls  the 
data-loading  function  whenever  it  has  exhausted  its  supply  of  compressed  data. 

Special  Considerations 

There  is  no  parameter  to  the  DecompressSequenceBegi  n  (1-238)  function  that  allows 
you  to  assign  a  data-loading  function  to  a  sequence. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Changing  Sequence-Decompression  Parameters" 
(V-2795) 

SetDSequenceFlags 


Sets  data  loading  flags. 

OSErr  SetDSequenceFlags  ( 
ImageSequence  seqlD, 

long  flags. 
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SetDSequenceMask 


1  ong 


f 1 agsMask  ) ; 


seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi n  (1-238). 

fl  ags 

Flags  (see  below)  for  data  loading, 
f  1  agsMask 

Use  this  field  to  preserve  the  state  of  any  flags  you  do  not  wish  to  alter.  If  a  flag 
(see  below)  is  set  in  this  field,  and  is  not  set  in  the  flags  parameter,  it  will  not 
be  changed  from  its  current  setting. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constant 

codec DSequenceSingleField 
Undocumented 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


SetDSequenceMask 


Assigns  a  clipping  region  to  a  sequence. 

OSErr  SetDSequenceMask  ( 

ImageSequence  seqlD, 

RgnHandl e  mask  ) ; 

seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi n  (1-238). 

mask 

A  handle  to  a  clipping  region  in  the  destination  coordinate  system.  If  specified, 
the  decompressor  applies  this  mask  to  the  destination  image.  If  you  want  to 
stop  masking,  set  this  parameter  to  NIL.  The  new  region  takes  effect  with  the 
next  frame  in  the  sequence. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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SetDSequenceMatrix 


Discussion 

The  decompressor  draws  only  that  portion  of  the  decompressed  image  that  lies 
within  the  specified  clipping  region.  You  should  not  dispose  of  this  region  until  the 
Image  Compression  Manager  is  finished  with  the  sequence,  or  until  you  set  the 
mask  either  to  N I L  or  to  a  different  region  by  calling  this  function  again. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Changing  Sequence-Decompression  Parameters" 
(V-2795) 

Related  Java  Methods 

qui ckti me . std . image . DSequence . setMask( ) 


SetDSequenceMatrix 


Assigns  a  mapping  matrix  to  a  sequence. 

OSErr  SetDSequenceMatrix  ( 

ImageSequence  seqlD, 

MatrixRecordPtr  matrix  ); 

seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi  n  (1-238). 
matri x 

A  Matrix  Re  cord  (IV-2304)  structure  that  specifies  how  to  transform  the  image 
during  decompression.  You  can  use  this  structure  to  translate  or  scale  the  image 
during  decompression.  To  set  the  matrix  to  identity,  pass  N I L  in  this  parameter. 
The  new  matrix  takes  effect  with  the  next  frame  in  the  sequence. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  decompressor  uses  the  matrix  to  create  special  effects  with  the  decompressed 
image,  such  as  translating  or  scaling  the  image. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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SetDSequenceMatte 


Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Changing  Sequence-Decompression  Parameters" 
(V-2795) 

Related  Java  Methods 

qu ickti me. app. image. ImagePresenter. set Matrix( ) , 
qui ckti me . app . i mage . QT Image Drawer . setMatrix( ) , 
qu ickti me. std.image.DSequence. set Matrix!) 

See  Also 

For  the  corresponding  get  function,  see  GetDSequenceMatrix  (1-410). 


SetDSequenceMatte 

Assigns  a  blend  matte  to  a  sequence. 

OSErr  SetDSequenceMatte  ( 

ImageSequence  seqlD, 

PixMapHandle  matte, 

const  Rect  *matteRect  ) ; 

seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi n  (1-238). 
matte 

A  handle  to  a  Pi  xMap  (IV-2332)  structure  that  contains  a  blend  matte.  You  can 
use  the  blend  matte  to  cause  the  decompressed  image  to  be  blended  into  the 
destination  pixel  map.  The  matte  can  be  defined  at  any  supported  pixel  depth; 
the  matte  depth  need  not  correspond  to  the  source  or  destination  depths. 
However,  the  matte  must  be  in  the  coordinate  system  of  the  source  image.  If 
you  want  to  turn  off  the  blend  matte,  set  this  parameter  to  NIL. 

matteRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  defines  the  boundary  rectangle  for 
the  matte.  The  decompressor  uses  only  that  portion  of  the  matte  that  lies  within 
the  specified  rectangle.  This  rectangle  must  be  the  same  size  as  the  source 
rectangle  you  specify  with  SetDSequenceSrcRect  (III— 1589)  or  with  the  srcRect 
parameter  to  DecompressSequenceBegi  n  (1-238).  To  use  the  matte's  PixMap 
(IV-2332)  structure  bounds  as  the  boundary  rectangle,  pass  N I L  in  this 
parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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SetDSequenceSrcRect 


Discussion 

The  decompressor  uses  the  matte  to  blend  the  decompressed  image  into  the 
destination  pixel  map.  The  new  matte  and  matte  boundary  rectangle  take  effect 
with  the  next  frame  in  the  sequence.  You  should  not  dispose  of  the  matte  until  the 
Image  Compression  Manager  has  finished  with  the  sequence. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Changing  Sequence-Decompression  Parameters" 
(V-2795) 

Related  Java  Methods 

qui ckti me . std . image . DSequence . setMatte( ) 


SetDSequenceSrcRect 


Defines  the  portion  of  an  image  to  decompress. 

OSErr  SetDSequenceSrcRect  ( 

ImageSequence  seqlD, 

const  Rect  *srcRect  ); 

seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi  n  (1-238). 
srcRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  defines  the  portion  of  the  image  to 
decompress.  This  rectangle  must  lie  within  the  boundary  rectangle  of  the 
compressed  image,  which  is  defined  by  (0,0)  and 

( (**desc)  .wi dth(**desc)  .height),  where  desc  refers  to  the  ImageDescription 
(IV-2285)  structure  you  supply  to  DecompressSequenceBegi  n  (1-238).  If  the 
srcRect  parameter  is  NIL,  the  rectangle  is  set  to  the  Rect  structure  in  the 
ImageDescri pti on. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  decompressor  acts  on  that  portion  of  the  compressed  image  that  lies  within  this 
rectangle.  A  new  source  rectangle  takes  effect  with  the  next  frame  in  the  sequence. 
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SetDSequenceTimeCode 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Changing  Sequence-Decompression  Parameters" 
(V-2795) 

Related  Java  Methods 

qu ickti me. std.image.DSequence.setSrc RectO 


SetDSequenceTimeCode 


Sets  the  timecode  value  for  a  frame  that  is  about  to  be  decompressed. 

OSErr  SetDSequenceTimeCode  ( 

ImageSequence  seqlD, 

void  *ti meCodeFormat , 

void  *ti meCodeTi me  ); 

seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi n  (1-238). 
ti meCodeFormat 

A  pointer  to  a  Ti  meCodeDef  (IV-2482)  structure.  You  provide  the  appropriate 
timecode  definition  information  for  the  next  frame  to  be  decompressed. 

ti meCodeT i me 

A  pointer  to  a  TimeCode  Record  (IV-2484)  structure.  You  provide  the  appropriate 
time  value  for  the  next  frame  in  the  current  sequence. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

QuickTime's  video  media  handler  uses  this  function  to  set  the  timecode  information 
for  a  movie.  When  a  movie  that  contains  timecode  information  starts  playing,  the 
media  handler  calls  this  function  as  it  processes  the  movie's  first  frame.  The  Image 
Compression  Manager  passes  the  timecode  information  straight  through  to  the 
image  decompressor  component.  That  is,  the  Image  Compression  Manager  does 
not  make  a  copy  of  any  of  this  timecode  information.  As  a  result,  you  must  make 
sure  that  the  data  referred  to  by  the  ti  meCodeFormat  and  ti  meCodeTi  me  parameters  is 
valid  until  the  next  decompression  operation  completes. 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Changing  Sequence-Decompression  Parameters" 
(V-2795) 

SetDSequenceT  ransf  erMode 


Sets  the  mode  used  when  drawing  a  decompressed  image. 

OSErr  SetDSequenceTransferMode  ( 

ImageSequence  seqlD, 

short  mode, 

const  RGBColor  *opColor  ); 

seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi  n  (1-238). 

mode 

A  constant  (see  below)  that  specifies  the  transfer  mode  to  be  used  when 
drawing  the  decompressed  image.  See  also  "Graphics  Transfer  Modes" 
(IV-2670). 

opCol or 

Contains  a  pointer  to  the  color  for  use  in  addPi  n,  subPi  n,  bl  end,  and  transparent 
operations.  The  Image  Compression  Manager  passes  this  color  to  QuickDraw 
as  appropriate.  If  NIL,  the  opcolor  is  left  unchanged. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

mode  Constants 

bl  end 

Replace  the  destination  with  a  blend  of  the  source  and  destination  colors. 
addPi  n 

Replace  the  destination  with  the  sum  of  the  source  and  destination,  up  to  a 
maximum  value. 
addOver 

Replace  the  destination  with  the  sum  of  the  source  and  destination,  but  if  the 
resulting  red,  green,  or  blue  value  exceeds  65536,  then  subtract  65536  from  it. 
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SetDSequenceTransferMode 


subPi n 

Replace  the  destination  with  the  difference  between  the  source  and  destination, 
but  not  less  than  a  minimum  value. 
adMax 

Compare  the  source  and  destination,  and  replace  the  destination  with  the 
greater  value  of  each  of  the  red,  green,  and  blue  components. 

subOver 

Replace  the  destination  with  the  difference  between  the  source  and  destination, 
but  if  the  resulting  red,  green,  or  blue  value  is  negative,  then  add  65536  to  it. 
adMi  n 

Compare  the  source  and  destination,  and  replace  the  destination  with  the  lesser 
value  of  each  of  the  red,  green,  and  blue  components, 
di therCopy 

Replace  the  destination  with  a  dither  mix  of  the  source  and  destination, 
transparent 

Replace  the  destination  with  the  source  if  the  source  is  not  equal  to  the 
background. 

Discussion 

For  any  given  sequence,  the  default  opCol  or  value  is  50  percent  gray  and  the  default 
mode  is  ditherCopy.  The  new  mode  takes  effect  with  the  next  frame  in  the 
sequence. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Changing  Sequence-Decompression  Parameters" 
(V-2795) 

Related  Java  Methods 

quicktime.std.image.DSequence.setGraphicsMode( ) , 
quicktime.std.image.DSequence.setTransferModeO 


See  Also 

The  Image  Compression  Manager  supports  the  same  transfer  modes  that  are 
supported  by  the  Mac  OS  CopyBi  ts  routine;  see  Inside  Macintosh:  Imaging  With 
QnickDraiv  (listed  in  the  bibliography). 
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SetldentityMatrix 

Sets  the  contents  of  a  matrix  so  that  it  performs  no  transformation. 

void  SetldentityMatrix  ( 

MatrixRecord  *matrix  ); 

matri x 

A  pointer  to  a  Matri  xRecord  (IV-2304)  structure.  The  function  updates  the 
contents  of  this  matrix  so  that  the  matrix  describes  the  identity  matrix. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Matrices"  (V-2764) 

Related  Java  Methods 

qui ckti me . std . image . Matrix. set  I  dent i ty ( ) 


SetlmageDescriptionCT  able 


Updates  the  custom  Col  orTabl  e  (IV-2210)  structure  for  an  image. 

OSErr  SetlmageDescriptionCTabl e  ( 

ImageDescri pti onHandl e  desc, 

CTabHandle  ctable  ); 


desc 

Contains  a  handle  to  the  appropriate  ImageDescri  pti  on  (IV-2285)  structure.  The 
function  updates  the  size  of  the  structure  to  accommodate  the  new  Col  orTabl  e 
(IV-2210)  structure  and  removes  the  old  color  table,  if  one  is  present. 

ctabl e 

A  handle  to  the  new  Col  orTabl  e  (IV-2210)  structure.  The  function  loads  this 
color  table  into  the  ImageDescri  pti  on  (IV-2285)  structure  referred  toby  the  desc 
parameter.  Set  this  parameter  to  NIL  to  remove  a  Col  orTabl  e  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  does  not  change  the  image  data,  just  the  color  table. 
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SetMediaDataHandler 


Special  Considerations 

This  function  is  rarely  used.  Typically,  you  supply  the  color  table  when  your 
application  compresses  an  image,  and  the  Image  Compression  Manager  stores  the 
Col  orTabl  e  (IV-2210)  structure  with  the  image. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Pixel  Maps"  (V-2789) 

Related  Java  Methods 

quicktime.std.image.ImageDescription.setCTableO 


See  Also 

For  the  corresponding  get  function,  see  GetlmageDescri  pti  onCTabl  e  (1-417). 


SetMediaDataHandler 


Assigns  a  data  handler  to  a  media. 

OSErr  SetMediaDataHandler  ( 

Medi  a 
short 

DataHandl er Component 
theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewTrackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 

i  ndex 

Identifies  the  data  reference  for  this  data  handler.  You  provide  the  index  value 
that  corresponds  to  the  data  reference.  You  must  set  this  parameter  to  1. 
dataHandl er 

The  data  handler  for  the  media.  This  identifier  is  a  component  instance  that 
specifies  a  connection  to  a  data  handler  component,  such  as  that  returned  by 
GetMedi  aDataHandl  er  (1-425).  If  the  data  handler  you  specify  cannot  work  with 
the  data  stored  in  the  media,  the  function  does  not  change  the  media's  data 
handler. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 


theMedi a , 
i ndex , 

dataHandl er  ) ; 
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SetMediaDataRef 


Discussion 

Your  application  should  normally  not  call  this  function.  The  Movie  Toolbox  assigns 
a  data  handler  to  each  media  when  you  load  a  movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Selecting  Media  Handlers"  (V-2754) 

Related  Java  Methods 

qui  cktime .  std  .movi  es  .medi  a.Media.setDataHandlerO 


See  Also 

For  the  corresponding  get  function,  see  GetMedi  aDataHandl  er  (1-425). 


SetMediaDataRef 


Changes  the  file  that  the  specified  media  identifies  as  the  location  for  its  data 
storage. 

OSErr  SetMediaDataRef  ( 

Media  theMedia, 

short  index. 

Handle  dataRef, 

OSType  dataRefType  ); 

theMedi a 

Specifies  the  media  for  this  operation.  Your  application  obtains  this  media 
identifier  from  such  functions  as  NewTrackMedi  a  (11-1120)  and  GetTrackMedi  a 
(1-535). 

i  ndex 

A  pointer  to  a  short  integer.  The  Movie  Toolbox  returns  the  index  value  that  is 
assigned  to  the  new  data  reference.  Your  application  can  use  this  index  to 
identify  the  reference  to  other  Movie  Toolbox  functions,  such  as 
GetMedi  aDataRef  (1-427).  As  with  all  data  reference  functions,  the  index  starts 
with  1.  If  the  Movie  Toolbox  cannot  add  the  data  reference  to  the  media,  it  sets 
the  returned  index  value  to  0. 

dataRef 

The  data  reference.  This  parameter  contains  a  handle  to  the  information  that 
identifies  the  file  that  contains  this  media's  data.  The  type  of  information  stored 
in  that  handle  depends  upon  the  value  of  the  dataRefType  parameter. 
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dataRefType 

The  type  of  data  reference.  If  the  data  reference  is  an  alias,  you  must  set  this 
parameter  to  rAl  i  asType. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

Don't  call  this  function  unless  you  have  a  really  good  reason.  However,  if  you  want 
to  resolve  your  own  missing  data  references,  or  you  are  developing  a 
special-purpose  kind  of  application,  this  function  can  be  quite  useful. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Related  Java  Methods 

qui ckti me . std .movi es .medi a . Medi a . set Data  Ref ( ) 


See  Also 

For  the  corresponding  get  function,  see  GetMedi  aDataRef  (1-427). 


SetMediaDataRef  Attributes 


Sets  a  data  reference's  attributes. 

OSErr  SetMedi aDataRef Attri butes  ( 

Media  theMedia, 

short  index, 

long  dataRef Attri butes  ); 

theMedi a 

Specifies  the  media  for  this  operation.  Your  application  obtains  this  media 
identifier  from  such  functions  as  NewTrackMedi  a  (11-1120)  and  GetTrackMedi  a 
(1-535). 

i  ndex 

The  index  value  that  corresponds  to  the  data  reference.  It  must  be  less  than  or 
equal  to  the  value  that  is  returned  by  GetMedi  aDataRefCount  (1-428). 

dataRef Attri butes 

A  flag  (see  below)  that  determines  whether  or  not  the  data  reference  is  the 
movie  default. 
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function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

dataRefAttributes  Constant 

kMovi eAnchorDataRef IsDefaul t 

The  data  reference  is  the  movie  default  data  reference. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Medi a . set Data  Ref Attri butes ( ) 


SetMediaDefaultDataReflndex 


Specifies  which  of  a  media's  data  references  is  to  be  accessed  during  an  editing 
session. 

OSErr  SetMediaDefaultDataReflndex  ( 

Media  theMedia, 

short  index  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 
i  ndex 

The  data  reference  to  access.  Values  of  the  i  ndex  parameter  range  from  1  to  the 
number  of  data  references  in  the  media.  You  can  determine  the  number  of  data 
references  by  calling  GetMedi  aDataRefCount  (1-428).  Once  set,  the  default  data 
reference  index  persists.  Set  this  parameter  to  0  to  revert  to  the  media's  default 
data  reference. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

This  function  allows  you  to  specify  the  index  of  the  data  reference  to  be  edited.  After 
calling  this  function,  you  can  start  editing  that  data  reference  by  calling 
BeginMedi  a  Ed i  ts  (1-56). 


Inside  QuickTime:  Functions  R-Z 


III-1597 


SetMediaHandler 


Version  Notes 

Before  QuickTime  2.0,  the  Movie  Toolbox  did  not  allow  the  creation  of  tracks  that 
had  data  in  several  files.  Therefore,  there  was  no  mechanism  for  controlling  which 
data  reference  was  affected  by  a  media  editing  session. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Adding  Samples  to  Media  Structures"  (V-2752) 

Related  Java  Methods 

qui ckti me . std .movi es .medi a . Medi a . setDefaul t Data  Ref Index( ) 


SetMediaHandler 


Assigns  a  specific  media  handler  to  a  track. 

OSErr  SetMediaHandler  ( 

Media  theMedia, 

Medi aHandl erComponent  mH  ); 

theMedi a 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

mH 

A  reference  to  a  media  handler  component.  You  obtain  this  reference  from 
GetMedi  aHandl  er. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1—494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

Your  application  should  not  need  to  call  this  function.  The  Movie  Toolbox  assigns 
a  media  handler  to  each  track  when  you  load  a  movie. 

Special  Considerations 

The  Movie  Toolbox  closes  the  track's  previous  media  handler  and  then  opens  the 
new  one.  It  is  your  responsibility  to  ensure  that  the  media  handler  you  specify  can 
handle  the  data  in  the  track. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Selecting  Media  Handlers"  (V-2754) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Medi a.setHandler() 


See  Also 

For  the  corresponding  get  function,  see  GetMediaHandler  (1-432). 


SetMedialnputMap 

Replaces  the  media's  existing  input  map  with  a  given  input  map. 

OSErr  SetMedialnputMap  ( 

Media  theMedia, 

QTAtomContai ner  inputMap  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 

i nputMap 

The  media  input  map  for  this  operation.  If  the  input  map  is  set  to  NIL,  the 
media's  input  map  is  reset  to  an  empty  input  map. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

Use  this  function  to  specify  the  media  you  want  to  set  so  you  can  modify  or  empty 
its  input  map.  It  makes  a  copy  of  the  input  map  passed  to  it.  The  following  sample 
code  illustrates  how  to  update  an  input  map,  using  this  function  and 
GetMedialnputMap  (1-435): 

//  SetMedialnputMap  coding  example 
QTAtomContai ner  inputMap; 

QTAtom  inputAtom; 

OSType  inputType; 

Media  aVideoMedia  =  GetTrackMedi a( a V i deoTrack) ; 

GetMedi alnputMap  ( a V i deoMedi a ,  &i nputMap) ; 
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QTInsertChildti nputMap ,  kParentAtomlsContai ner ,  kT rackModi fierlnput, 
addedlndex,  0,0,  nil,  &inputAtom) ; 

inputType  =  kTrackModi f i erTypeCl i p ; 

QTInsertChi 1 d  (inputMap,  inputAtom,  kTrackModi fi erType ,  1,  0, 
si zeof ( i nputType ) ,  &inputType,  nil); 

SetMedialnputMaptaVideoMedia,  inputMap) ; 

QTDi sposeAtomContai nerd  nputMap) ; 

Special  Considerations 

Use  QTNewAtomContai  ner  (11-1203)  to  create  an  empty  input  map. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Manipulating  Media  Input  Maps"  (V-2753) 

Related  Java  Methods 

quicktime.std.movies.media.Media.setlnputMapO 

See  Also 

For  the  corresponding  get  function,  see  Get  Med  i  a  I  nputMap  (I — 435). 


SetMediaLanguage 


Sets  a  media's  localized  language  or  region  code. 

void  SetMediaLanguage  ( 

Media  theMedia, 

short  1 anguage  ) ; 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewTrackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 

1 anguage 

The  media's  language  or  region  code. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 


III-1600 


Inside  QuickTime:  Functions  R-Z 


SetMediaPlayHints 


Discussion 

You  should  call  this  function  only  when  you  are  creating  a  new  media. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Alternate  Tracks"  (V-2738) 

Related  Java  Methods 

qui  cktime .  std  .movi  es  .medi  a  .  Medi  a.setLanguageO 


See  Also 

For  the  corresponding  get  function,  see  GetMediaLanguage  (1-436). 


SetMediaPlayHints 

Provides  information  to  the  Movie  Toolbox  that  can  influence  playback  of  a  single 
media. 

void  SetMediaPlayHints  ( 

Media  theMedia, 

long  flags, 

long  flagsMask  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 

fl  ags 

The  optimizations  that  can  be  used  with  this  media.  Each  bit  in  this  parameter 
corresponds  to  a  specific  optimization;  be  sure  to  set  unused  flags  to  0. 
fl agsMask 

Indicates  which  flags  in  the  fl  ags  parameter  are  to  be  considered  in  this 
operation.  For  eachbit  in  the  f  1  ags  parameter  that  you  want  the  Movie  Toolbox 
to  consider,  you  must  set  the  corresponding  bit  in  the  flagsMask  parameter  to  1 . 
Set  unused  flags  to  0.  This  allows  you  to  work  with  a  single  optimization 
without  altering  the  settings  of  other  flags. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 
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flags  Constants 

hi ntsScrubMode 

Indicates  that  the  Movie  Toolbox  can  prefer  to  display  key  frames  when  the 
movie  that  uses  this  media  is  repositioned.  This  optimization  is  used  only  when 
a  movie's  rate  is  set  to  0.  If  you  set  this  flag  to  1,  the  Movie  Toolbox  is  free  to 
display  the  nearest  key  frame  when  you  set  the  movie's  current  time;  the  Movie 
Toolbox  then  moves  to  the  appropriate  frame  as  time  permits.  If  you  set  this 
flag  to  0,  the  Movie  Toolbox  displays  the  frame  that  corresponds  to  the  new 
current  time,  even  if  that  frame  is  not  a  key  frame.  By  displaying  key  frames 
first,  the  Movie  Toolbox  can  display  data  from  temporally  compressed  movies 
much  more  quickly  in  response  to  changes  to  the  movie's  current  time.  This,  in 
turn,  can  improve  the  liveliness  of  a  movie  control.  For  example,  if  the  user  is 
positioning  in  a  stopped  movie,  the  Movie  Toolbox  can  display  a  key  frame  that 
corresponds  to  the  new  position  without  having  to  build  up  the  image 
offscreen.  In  this  manner,  the  user  gets  quicker  feedback  from  your  application. 

hintslIseSoundlnterp 

Turns  on  sound  interpolation;  that  is,  tells  the  Sound  Manager  to  use  sound 
interpolation  when  playing  back  sound.  In  certain  situations,  this  improves  the 
sound  quality  to  11  kHz. 
hi ntsAl low Interlace 

Tells  the  Image  Compression  Manager  to  use  the  interlace  option  for  image 
compressor  and  decompressor  components, 
hi ntsAl 1 owBl ackl i ni ng 

Instructs  the  Movie  Toolbox  to  use  blacklining  (displaying  every  other  line  of 
the  image)  when  playing  a  movie.  Blacklining  increases  the  speed  of  movie 
playback  while  decreasing  the  image  quality.  This  hint  is  ignored  if  the 
decompressor  for  the  movie  data  does  not  support  blacklining. 

hi ntsDontPurge 

Instructs  the  toolbox  not  to  dispose  of  movie  data  after  playing  it.  The  toolbox 
leaves  the  data  in  memory,  in  a  purgeable  handle.  This  can  enhance  the 
playback  of  small  movies  that  are  looping.  However,  it  may  consume  large 
amounts  of  memory  and  therefore  affect  the  performance  of  the  Memory 
Manager.  Use  this  hint  carefully, 
hi ntslnacti ve 

Tells  the  toolbox  that  the  movie  is  not  in  an  active  window.  This  can  allow  the 
toolbox  to  allocate  scarce  system  resources  more  efficiently.  The  movie 
controller  component  automatically  sets  this  hint  for  all  movies  it  manages. 
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hi ntsHi ghQual i ty 

Specifies  that  the  given  movie  or  media  should  render  the  highest  quality.  For 
example,  the  video  media  handler  should  turn  off  fast  dithering  and  use 
high-quality  dithering.  Because  rendering  at  the  highest  quality  takes  much 
more  time  and  memory  than  rendering  at  a  lesser  quality,  this  mode  is  usually 
not  appropriate  for  real-time  playback.  However,  since  this  mode  generates 
higher  quality  images,  it  is  useful  when  recompressing. 

Discussion 

This  function  accepts  a  flag  in  which  you  specify  optimizations  that  the  Movie 
Toolbox  can  use  during  movie  playback.  These  optimizations  apply  to  only  the 
specified  media. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Enhancing  Movie  Playback  Performance"  (V-2722) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Medi a . set  PI  ay Hi nts ( ) 


See  Also 

For  the  corresponding  get  function,  see  GetMedi aPl  ayHi  nts  (1-439). 


SetMediaPreferredChunkSize 

Specifies  a  maximum  chunk  size  for  a  media. 

OSErr  SetMediaPreferredChunkSize  ( 

Media  theMedia, 

long  maxChunkSize  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 
maxChunkSi ze 

The  maximum  chunk  size,  in  bytes. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 
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Discussion 

The  term  "chunk"  refers  to  the  collection  of  sample  data  that  is  added  to  a  movie 
when  you  call  AddMed  i  a  Sampl  e  (1-27).  When  QuickTime  loads  a  movie  for  playback, 
it  loads  the  data  a  chunk  at  a  time.  Consequently,  both  the  size  and  number  of 
chunks  in  a  movie  can  affect  playback  performance.  The  toolbox  tries  to  optimize 
playback  performance  by  consolidating  adjacent  sample  references  into  a  single 
chunk,  up  to  the  limit  you  prescribe  with  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Adding  Samples  to  Media  Structures"  (V-2752) 

Related  Java  Methods 

qu ickti me. std. mo vies. media. Media. setPreferredChunkSizet) 

See  Also 

For  the  corresponding  get  function,  see  GetMedi  aPreferredChunkSi  ze  (1-440). 

SetMediaPropertyAtom 

Sets  the  property  atom  container  of  a  media  handler. 

OSErr  SetMediaPropertyAtom  ( 

Media  theMedia, 

QTAtomContai ner  propertyAtom  ); 

theMedl a 

A  reference  to  the  media  handler  for  this  operation. 
propertyAtom 

Specifies  a  QT  atom  container  that  contains  the  property  atoms  for  the  track 
associated  with  the  media  handler. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

You  can  call  this  function  to  set  properties  for  the  track  associated  with  the  specified 
media  handler.  The  contents  of  the  QT  atom  container  are  defined  by  the  media 
handler.  Here  is  some  sample  code  that  uses  this  function  to  define  the  background 
color  for  a  sprite  track: 
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//  SetMedi aPropertyAtom  coding  example 
//  See  “Discovering  QuickTime,”  page  360 
if  ( bWi th Background  Pi cture)  { 

QTAtomContai ner  qtacTrackProperties; 

RGBColor  rgbcBackCol or ; 

rgbcBackCol  or .  red  =  Endi  anlll6_NtoB(0x8000) ; 
rgbcBackCol or . green  =  Endi anUl 6_N t o  B ( 0 ) ; 
rgbcBackCol  or .  bl  ue  =  Endi  anlll6_NtoB0(xffff ) ; 

//  create  a  new  atom  container  for  sprite  track  properties 
QTNewAtomContai ner(&qtacTrackProperties); 

//  add  an  atom  for  the  background  color  property 
QTInsertChi ldlqtacTrackProperties,  0, 

kSpri teTrackPropertyBackgroundCol or ,  1,  1,  sizeof ( RGBCol or) , 
&rgbcBackCol or ,  NIL); 

//  set  the  sprite  track’s  properties 

nErr  =  SetMedi aPropertyAtomlmedi a ,  qtacTrackProperties); 

QTDi sposeAtomContai ner( qtacTrackProperties); 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Media  Handler  Properties"  (V-2755) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Medi a . setPropertyAtoml ) 

See  Also 

For  the  corresponding  get  function,  see  GetMedi  aPropertyAtom  (1-440). 


SetMediaQuality 


Sets  a  media's  quality  level  value. 

void  SetMediaQuality  ( 

Media  theMedia, 
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short  qual i ty  ) ; 
theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetT rackMedi  a  (1-535). 

qual i ty 

The  media's  quality  value.  The  quality  value  indicates  the  pixel  depths  at  which 
the  media  can  be  played.  This  even  applies  to  sound  media.  The  low-order  6 
bits  of  the  quality  value  correspond  to  specific  pixel  depths.  If  a  bit  is  set  to  1, 
the  media  can  be  played  at  the  corresponding  depth.  More  than  one  of  these 
bits  may  be  set  to  1.  The  Movie  Toolbox  uses  this  quality  value  to  determine 
which  track  it  selects  to  play  on  a  given  Macintosh  computer.  You  should  set 
this  value  only  when  you  are  creating  a  new  media. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi es .  h 

Programming  summary:  "Working  With  Alternate  Tracks"  (V-2738) 

Related  Java  Methods 

qui cktime. std .movi es .medi a .Medi a . setQual i ty ( ) 


See  Also 

For  the  corresponding  get  function,  see  GetMedi  aQual  i  ty  (I — 441). 


SetMediaSampleDescription 


Changes  the  contents  of  a  particular  Sampl  eDescri  pti  on  (IV-2414)  structure  of  a 
specified  media. 

OSErr  SetMediaSampleDescription  ( 

Media  theMedia, 

long  index, 

Sampl eDescri pti onHandl e  descH  ); 

theMedi a 

The  media  for  this  operation.  You  obtain  this  media  identifier  from  such 
functions  as  NewTrackMedi  a  (11-1120)  and  GetTrackMedi  a  (1-535). 
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i  ndex 

The  index  of  the  SampleDescription  (IV-2414)  structure  to  be  changed.  This 
index  corresponds  to  the  SampleDescription  structure  itself,  not  the  samples  in 
the  media.  This  long  integer  must  be  between  1  and  the  largest 
Sampl  eDescri  pti  on  index. 
descH 

The  handle  to  the  Sampl  eDescri  pti  on  (IV-2414)  structure.  If  there  is  no 
description  for  the  specified  index,  the  function  returns  this  handle  unchanged. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Media  Samples"  (V-2742) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Medi a . set Sampl eDescri pti on ( ) 


See  Also 

For  the  corresponding  get  function,  see  GetMedi  aSampl  eDescri  pti  on  (1-445). 


SetMediaShadowSync 


Creates  an  association  between  the  indicated  frame  difference  sample  and  a 
specified  self-contained  sample  in  a  given  media. 

OSErr  SetMediaShadowSync  ( 

Media  theMedia, 

long  f rameDi ffSampl eNum, 

long  syncSampl eNum  ); 

theMedi a 

The  media  in  which  the  shadow  sync  is  to  be  created, 
f rameDi ffSampl eNum 

Specifies  a  frame  difference  sample.  The  sample  number  is  obtained  from 
Medi  aTimeToSampl  eNum  (11-913). 
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syncSampl eNum 

Specifies  a  shadow  sync  sample.  The  sample  number  is  obtained  from 
Medi  aT  1  meToSampl  eNum  (11-913). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Enhancing  Movie  Playback  Performance"  (V-2722) 

Related  Java  Methods 

qui ckti me . std .movi es .medi a . Medi a . setShadowSynct ) 


See  Also 

For  the  corresponding  get  function,  see  GetMedi  aShadowSync  (1-453). 


SetMediaTimeScale 

Sets  a  media's  time  scale. 

void  SetMediaTimeScale  ( 

Media  theMedia, 

TimeScale  timeScale  ); 

theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetT rackMedi  a  (1-535). 

ti meScal e 

The  media's  new  time  scale. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Media  Time"  (V-2735) 
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Related  Java  Methods 

qui cktime . std .movi es .medi a . Medi a . setTi meScal e( ) 

See  Also 

For  the  corresponding  get  function,  see  GetMedi  aT i  meScal  e  (1-455). 


SetMovieActive 


Activates  or  deactivates  a  movie. 

void  SetMovieActive  ( 

Movie  theMovie, 

Boolean  active  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

acti ve 

Activates  or  deactivates  the  movie.  Set  this  parameter  to  TRUE  to  activate  the 
movie;  set  this  parameter  to  FALSE  to  deactivate  the  movie. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Disabling  Movies  and  Tracks"  (V-2724) 

Related  Java  Methods 

qui cktime . std .movi es . Movi e . set Acti ve( ) 


See  Also 

For  the  corresponding  get  function,  see  GetMovi  eActive  (1-456). 


SetMovieActiveSegment 

Defines  a  movie's  active  segment, 
void  SetMovieActiveSegment  ( 
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Movie  theMovie, 

TimeVal ue  startTi me , 

TimeValue  duration  ); 

theMovi  e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
startTime 

A  time  value  specifying  the  starting  point  of  the  active  segment.  Set  this 
parameter  to  -1  to  make  the  entire  movie  active.  In  this  case,  the 
SetMovi  eActi  veSegment  function  ignores  the  durati  on  parameter. 

durati on 

A  time  value  that  specifies  the  duration  of  the  active  segment.  If  you  are  making 
the  entire  movie  active  (by  setting  the  sta  rtT i  me  parameter  to  -1),  the  Movie 
Toolbox  ignores  this  parameter. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

Your  application  defines  the  active  segment  by  specifying  the  starting  time  and 
duration  of  the  segment.  These  values  must  be  expressed  in  the  movie's  time 
coordinate  system.  By  default,  the  entire  movie  is  active. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Enhancing  Movie  Playback  Performance"  (V-2722) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . set Act i veSegment ( ) 


See  Also 

Your  application  can  retrieve  the  information  that  defines  a  movie's  active  segment 
by  calling  GetMovi  eActi  veSegment  (1-457). 


SetMovieAnchorDataRef 


Sets  a  movie's  anchor  data  reference  and  type. 


III-1610 


Inside  QuickTime:  Functions  R-Z 


SetMovieBox 


OSErr  SetMovieAnchorDataRef  ( 

Movie  theMovie, 

Handle  dataRef, 

OSType  dataRefType  ); 

theMovi e 

A  movie  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e 
(11-1084). 

dataRef 

A  handle  to  the  data  reference.  The  type  of  information  to  be  placed  in  the 
handle  depends  upon  the  data  reference  type  specified  by  dataRefType. 
dataRefType 

The  type  of  data  reference;  see  "Data  References"  (IV-2661). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 


Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


See  Also 

For  the  corresponding  get  function,  see  GetMovi  eAnchorDataRef  (1-458). 


SetMovieBox 


Sets  a  movie's  boundary  rectangle. 

void  SetMovieBox  ( 

Movie  theMovie, 

const  Rect  *boxRect  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

boxRect 

A  pointer  to  a  rectangle  that  contains  the  coordinates  of  the  new  boundary 
rectangle. 
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SetMovieClipRgn 


function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

The  Movie  Toolbox  changes  the  rectangle  by  modifying  the  translation  and  scale 
values  of  the  movie's  matrix  to  accommodate  the  new  boundary  rectangle. 

The  movie  box  might  not  have  its  upper-left  corner  set  at  (0,0)  in  its  display  window 
when  the  movie  is  first  loaded.  Consequently,  your  application  may  need  to  adjust 
the  position  of  the  movie  box  so  that  it  appears  in  the  appropriate  location  within 
your  application's  document  window.  If  you  don't  reset  the  movie  position,  the 
movie  might  not  be  visible  when  it  starts  playing.  The  following  sample  code 
demonstrates  how  to  do  this: 

//Zeroing  the  boundary  rectangle  with  SetMovieBox 
GetMovieBox  (movie,  &movieBox); 

OffsetRect  (&movieBox,  -movi eBox. 1  eft ,  -movieBox.top) ; 

SetMovieBox  (movie,  &movieBox); 

Special  Considerations 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es . h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

quicktime.std.movies.Movie.setBoundst ) , 
qui ckti me . std .movi es . Movi e . set Box ( ) 


See  Also 

For  the  corresponding  get  function,  see  GetMovi  eBox  (I — 460). 


SetMovieClipRgn 


Establishes  a  movie's  clipping  region. 

void  SetMovieClipRgn  ( 

Movie  theMovie, 

RgnHandl e  theCl ip  ) ; 


III-1612 
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SetMovieColorTable 


theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi eFromHandl e  (11-1084). 
theCl i p 

A  handle  to  the  movie's  clipping  region.  The  Movie  Toolbox  makes  a  copy  of 
this  region.  Your  application  must  dispose  of  the  region  referred  to  by  this 
parameter  when  you  are  done  with  it.  Set  this  parameter  to  N I L  to  disable 
clipping  for  the  movie. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

The  clipping  region  is  saved  with  the  movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . set Cl i pRgn( ) 


See  Also 

For  the  corresponding  get  function,  see  GetMovi  eCl  i  pRgn  (1-462). 


SetMo  vieColorT  able 


Associates  a  Col  orTabl  e  (IV-2210)  structure  with  a  movie. 

OSErr  SetMovieColorTable  ( 

Movie  theMovi e, 

CTabHandle  ctab  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  identifier  from  such 
functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
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III-1613 


SetMovieCoverProcs 


ctab 

A  handle  to  the  Col  orTabl  e  (IV-2210)  structure.  Set  this  parameter  to  N I L  to 
remove  the  movie's  Col  orTabl  e  structure. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

The  Col  orTabl  e  (IV-2210)  structure  you  supply  may  be  used  to  modify  the  palette 
of  indexed  display  devices  at  playback  time.  If  you  are  using  the  movie  controller, 
be  sure  to  set  the  mcFl  agsUseWi  ndowPal  ette  flag.  If  you  are  not  using  the  movie 
controller, you  should  retrieve  the  movie's  ColorTable  structure,  using 
GetMovi  eCol  orTabl  e  (1-463),  and  supply  it  to  the  Palette  Manager. 

Special  Considerations 

The  toolbox  makes  a  copy  of  the  ColorTable  structure,  so  it  is  your  responsibility  to 
dispose  of  the  structure  when  you  are  done  with  it.  If  the  movie  already  has  a  color 
table,  the  toolbox  uses  the  new  table  to  replace  the  old  one. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

quicktime.std.movies.Movie.setColorTableO 


See  Also 

For  the  corresponding  get  function,  see  GetMovi  eCol  orTabl  e  (1-463). 

CopyMovi  eSetti  ngs  (1-140)  copies  the  movie's  color  table,  along  with  other  settings 
information. 


SetMovieCoverProcs 


Sets  the  callbacks  invoked  when  a  movie  is  covered  or  uncovered. 


void  SetMovieCoverProcs 
Movi  e 

Movi eRgnCoverUPP 
Movi eRgnCoverUPP 
1  ong 


( 

theMovi e , 
uncoverProc , 
coverProc , 
refcon  ) ; 
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SetMovieCoverProcs 


theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
uncoverProc 

Points  to  a  Movi  eRgnCoverProc  (III— 2108)  callback.  This  function  is  called 
whenever  one  of  your  movie's  tracks  is  removed  from  the  screen  or  resized, 
revealing  a  previously  hidden  screen  region.  If  you  want  to  remove  this 
uncover  function,  set  this  parameter  to  NIL.  When  the  uncoverProc  parameter  is 
N I L  the  function  uses  the  default  uncover  function,  which  erases  the  uncovered 
area. 

coverProc 

Points  to  a  Movi  eRgnCoverProc  (III— 2108)  callback.  The  Movie  Toolbox  calls  this 
function  whenever  one  of  your  movies  covers  a  portion  of  the  screen.  If  you 
want  to  remove  the  cover  function,  set  this  parameter  to  NIL.  When  the 
uncoverProc  parameter  is  N I L  the  function  uses  the  default  cover  function, 
which  does  nothing, 
ref con 

Specifies  a  reference  constant.  Use  this  parameter  to  point  to  a  data  structure 
containing  any  information  your  callbacks  need. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

If  a  movie  with  semi-transparent  tracks  has  a  movie  uncover  procedure,  set  with 
this  function,  the  uncover  procedure  is  called  before  each  frame  to  fill  or  erase  the 
background. 

Version  Notes 

Before  QuickTime  1.6.1,  the  Movie  Toolbox  performed  the  erase,  which  limited  a 
cover  procedure-aware  application's  options. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Progress  and  Cover  Functions"  (V-2726) 

See  Also 

For  the  corresponding  get  function,  see  GetMovi  eCoverProcs  (1-464). 
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SetMovieDefaultDataRef 


SetMovieDefaultDataRef 


Sets  a  movie's  default  data  reference  and  type. 

OSErr  SetMovieDefaultDataRef  ( 

Movie  theMovie, 

Handle  dataRef, 

OSType  dataRefType  ); 

theMovi e 

A  movie  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e 
(11-1084). 
dataRef 

A  handle  to  the  data  reference.  The  type  of  information  to  be  placed  in  the 
handle  depends  upon  the  data  reference  type  specified  by  dataRefType. 
dataRefType 

The  type  of  data  reference;  see  "Data  References"  (IV-2661). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . setDefaul t Data  Ref ( ) 


See  Also 

For  the  corresponding  get  function,  see  GetMovi eDefaul  tDataRef  (1-467). 


SetMovieDisplayClipRgn 


Establishes  a  movie's  current  display  clipping  region. 

void  SetMovieDisplayClipRgn  ( 

Movie  theMovie, 

RgnHandl e  theCl ip  ) ; 
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SetMovieDrawingCompleteProc 


theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi eFromHandl e  (11-1084). 
theCl i p 

A  handle  to  the  movie's  display  clipping  region  as  a  MacRegi  on  (IV-2303) 
structure.  The  Movie  Toolbox  makes  a  copy  of  this  region.  Your  application 
must  dispose  of  the  region  referred  to  by  this  parameter  when  you  are  done 
with  it.  Set  this  parameter  to  N I L  to  disable  a  movie's  clipping  region. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

The  display  clipping  region  is  not  saved  with  the  movie.  You  can  access  error 
returns  from  this  function  through  GetMovi  esError  (I — 492)  and 
GetMovi  esSti  ckyError  (1-494).  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . setDi spl ay Cl i p  Rg  n ( ) 


See  Also 

For  the  corresponding  get  function,  see  GetMovi  eDi  spl  ayCl  i  pRgn  (1-469). 


SetMovieDrawingCompleteProc 


Assigns  a  drawing-complete  function  to  a  movie. 

void  SetMovieDrawingCompleteProc  ( 

Movie  theMovie, 

long  flags, 

Movi  eDrawi  ngCompl  etellPP  proc, 
long  refCon  ); 


theMovi e 

The  movie  for  this  operation. 
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SetMovieDrawingCompleteProc 


fl  ags 

Contains  flags  (see  below)  that  control  when  your  drawing  complete  function 
is  called. 

proc 

A  pointer  to  your  Movi  eDrawi  ngCompl  eteProc  (III— 2100)  callback.  Set  this 
parameter  to  N I L  if  you  want  to  remove  your  callback. 

refCon 

The  reference  constant  you  supplied  when  your  application  called  your 
callback.  Use  this  parameter  to  point  to  a  data  structure  containing  any 
information  your  callback  needs. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

flags  Constants 

movi eDrawi ngCallWhenChanged 

Specifies  that  the  toolbox  should  call  your  drawing-complete  function  only 
when  the  movie  has  changed, 
movi eDrawi ngCal 1 A1 ways 

Specifies  that  the  toolbox  should  call  your  drawing-complete  function  every 
time  your  application  calls  Movi  esTask  (11-973). 

Discussion 

The  Movie  Toolbox  calls  this  function  based  upon  guidelines  you  establish  when 
you  assign  the  function  to  the  movie. 

Special  Considerations 

Some  media  handlers  may  take  less  efficient  playback  paths  when  a 
drawing-complete  function  is  used,  so  it  should  be  used  only  when  absolutely 
necessary. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Progress  and  Cover  Functions"  (V-2726) 

Related  Java  Methods 

quicktime.std.movies.Movie.setDrawi ngCompl eteProct ) , 
qui ckti me . std .movi es . Movi  e . removeDrawi ngCompl eteProct ) 
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SetMovieGWorld 


SetMovieGWorld 


Establishes  a  movie's  display  coordinate  system  by  setting  the  graphics  world  for 
displaying  the  movie. 

void  SetMovieGWorld  ( 

Movie  theMovie, 

CGrafPtr  port, 

GDHandle  gdh  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

port 

Points  to  the  movie's  CGraf  Port  (IV-2168)  structure  or  graphics  world.  Set  this 
parameter  to  N I L  to  use  the  current  graphics  port, 
gdh 

A  handle  to  the  movie's  GDevi  ce  (IV-2264)  structure.  Set  this  parameter  to  N I L 
to  use  the  current  device.  If  the  port  parameter  specifies  a  graphics  world,  set 
this  parameter  to  N I L  to  use  that  graphics  world's  graphics  device. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Special  Considerations 

When  you  use  this  function,  the  Movie  Toolbox  remembers  the  current  background 
color  and  background  pattern.  These  are  used  for  erasing  in  the  default  movie 
uncover  function;  see  SetMovi  eCoverProcs  (III— 1614). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qui cktime . std .movi es . Movi e . setGWorl d( ) 


See  Also 

For  the  corresponding  get  function,  see  GetMovi  eGWorl  d  (1-471). 
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SetMovieLanguage 


SetMovieLanguage 


Specifies  a  movie's  localized  language  or  region  code. 

void  SetMovieLanguage  ( 

Movie  theMovie, 

1 ong  1  anguage  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

1 anguage 

The  movie's  language  or  region  code;  see  "Localization  Codes"  (IV-2673). 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

The  Movie  Toolbox  examines  the  movie's  alternate  groups  and  selects  and  enables 
appropriate  tracks.  If  the  Movie  Toolbox  cannot  find  an  appropriate  track,  it  does 
not  change  the  movie's  language. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Alternate  Tracks"  (V-2738) 

Related  Java  Methods 

quicktime.std.movies.Movie.setLanguageO 


SetMovieMasterClock 


Assigns  a  clock  component  to  a  movie. 

void  SetMovieMasterClock  ( 

Movie  theMovie, 

Component  cl ockMei ster , 

const  TimeRecord  *slaveZero  ); 
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SetMovieMasterTimeBase 


theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
cl ockMei ster 

The  clock  component  to  be  assigned  to  this  movie.  Your  application  can  obtain 
this  component  identifier  from  Fi  ndNextComponent  (1-360). 

si aveZero 

A  pointer  to  the  time,  in  the  clock's  time  scale,  that  corresponds  to  a  0  time  value 
for  the  movie.  This  parameter  allows  you  to  set  an  offset  between  the  clock 
component  and  the  time  base  of  the  movie.  Set  this  parameter  to  N I L  if  there  is 
no  offset. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

Don't  use  SetTi  meBaseMasterCl  ock  (III— 1649)  to  assign  a  clock  component  to  a 
movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Creating  and  Disposing  of  Time  Bases"  (V-2759) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . setMasterCl ock( ) 


SetMovieMasterTimeBase 


Assigns  a  master  time  base  to  a  movie. 

void  SetMovieMasterTimeBase  ( 

Movie  theMovie, 

TimeBase  tb, 

const  TimeRecord  *slaveZero  ); 
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SetMovieMatrix 


theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
tb 

The  master  time  base  to  be  assigned  to  this  movie.  Your  application  obtains  this 
time  base  identifier  from  NewT i meBase  (11-1119). 

si aveZero 

A  pointer  to  the  time,  in  the  time  scale  of  the  master  time  base,  that  corresponds 
to  a  0  time  value  for  the  movie.  This  parameter  allows  you  to  set  an  offset 
between  the  movie  and  the  master  time  base.  Set  this  parameter  to  N I L  if  there 
is  no  offset. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Creating  and  Disposing  of  Time  Bases"  (V-2759) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . setMasterTi meBase ( ) 


SetMovieMatrix 


Sets  a  movie's  transformation  matrix. 

void  SetMovieMatrix  ( 

Movie  theMovie, 

const  MatrixRecord  *matrix  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
matri x 

A  pointer  to  the  Matri  xRecord  (IV-2304)  structure  for  the  movie.  If  you  set  this 
parameter  to  NIL,  the  Movie  Toolbox  uses  the  identity  matrix. 
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SetMoviePlayHints 


function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

The  Movie  Toolbox  uses  a  movie's  matrix  to  map  a  movie  from  its  display 
coordinate  system  to  its  graphics  world. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . setMatrix( ) 


See  Also 

For  the  corresponding  get  function,  see  GetMovi  eMatri x  (1-478). 


SetMoviePlayHints 


Provides  information  to  the  Movie  Toolbox  that  can  influence  movie  playback. 

void  SetMoviePlayHints  ( 

Movie  theMovie, 
long  flags, 
long  flagsMask  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

fl  ags 

The  optimizations  that  can  be  used  with  this  movie.  Each  bit  in  the  flags 
parameter  corresponds  to  a  specific  optimization  (see  below).  Be  sure  to  set 
unused  flags  to  0. 
fl agsMask 

Indicates  which  flags  in  the  fl  ags  parameter  are  to  be  considered  in  this 
operation.  For  eachbit  in  the  f  1  ags  parameter  that  you  want  the  Movie  Toolbox 
to  consider,  you  must  set  the  corresponding  bit  in  the  flagsMask  parameter  to  1 . 


Inside  QuickTime:  Functions  R-Z 


III-1623 


SetMoviePlayHints 


Set  unused  flags  to  0.  This  allows  you  to  work  with  a  single  optimization 
without  altering  the  settings  of  other  flags. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

flags  Constants 

hi ntsScrubMode 

Indicates  that  the  Movie  Toolbox  can  prefer  to  display  key  frames  when  the 
movie  that  uses  this  media  is  repositioned.  This  optimization  is  used  only  when 
a  movie's  rate  is  set  to  0.  If  you  set  this  flag  to  1,  the  Movie  Toolbox  is  free  to 
display  the  nearest  key  frame  when  you  set  the  movie's  current  time;  the  Movie 
Toolbox  then  moves  to  the  appropriate  frame  as  time  permits.  If  you  set  this 
flag  to  0,  the  Movie  Toolbox  displays  the  frame  that  corresponds  to  the  new 
current  time,  even  if  that  frame  is  not  a  key  frame.  By  displaying  key  frames 
first,  the  Movie  Toolbox  can  display  data  from  temporally  compressed  movies 
much  more  quickly  in  response  to  changes  to  the  movie's  current  time.  This,  in 
turn,  can  improve  the  liveliness  of  a  movie  control.  For  example,  if  the  user  is 
positioning  in  a  stopped  movie,  the  Movie  Toolbox  can  display  a  key  frame  that 
corresponds  to  the  new  position  without  having  to  build  up  the  image 
offscreen.  In  this  manner,  the  user  gets  quicker  feedback  from  your  application. 

hintslIseSoundlnterp 

Turns  on  sound  interpolation;  that  is,  tells  the  Sound  Manager  to  use  sound 
interpolation  when  playing  back  sound.  In  certain  situations,  this  improves  the 
sound  quality  to  11  kHz. 
hi ntsAl low Interlace 

Tells  the  Image  Compression  Manager  to  use  the  interlace  option  for  image 
compressor  and  decompressor  components, 
hi ntsAl 1 owBl ackl i ni ng 

Instructs  the  Movie  Toolbox  to  use  blacklining  (displaying  every  other  line  of 
the  image)  when  playing  a  movie.  Blacklining  increases  the  speed  of  movie 
playback  while  decreasing  the  image  quality.  This  hint  is  ignored  if  the 
decompressor  for  the  movie  data  does  not  support  blacklining. 

hi ntsDontPurge 

Instructs  the  toolbox  not  to  dispose  of  movie  data  after  playing  it.  The  toolbox 
leaves  the  data  in  memory,  in  a  purgeable  handle.  This  can  enhance  the 
playback  of  small  movies  that  are  looping.  However,  it  may  consume  large 
amounts  of  memory  and  therefore  affect  the  performance  of  the  Memory 
Manager.  Use  this  hint  carefully. 
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hi nts Inacti ve 

Tells  the  toolbox  that  the  movie  is  not  in  an  active  window.  This  can  allow  the 
toolbox  to  allocate  scarce  system  resources  more  efficiently.  The  movie 
controller  component  automatically  sets  this  hint  for  all  movies  it  manages, 
hi ntsHi ghQual i ty 

Specifies  that  the  given  movie  or  media  should  render  the  highest  quality.  For 
example,  the  video  media  handler  should  turn  off  fast  dithering  and  use 
high-quality  dithering.  Because  rendering  at  the  highest  quality  takes  much 
more  time  and  memory  than  rendering  at  a  lesser  quality,  this  mode  is  usually 
not  appropriate  for  real-time  playback.  However,  since  this  mode  generates 
higher  quality  images,  it  is  useful  when  recompressing. 

Discussion 

This  function  accepts  a  flag  in  which  you  specify  optimizations  that  the  Movie 
Toolbox  can  use  during  movie  playback.  These  optimizations  apply  to  all  of  the 
media  structures  used  by  the  movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Enhancing  Movie  Playback  Performance"  (V-2722) 

Related  Java  Methods 

qui cktime . std .movi es . Movi e . set PI  ay Hi nts( ) 


SetMo  viePosterT  ime 


Sets  the  poster  time  for  the  movie. 

void  SetMoviePosterTime  ( 

Movie  theMovie, 

TimeValue  posterTime  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi eFromHandl e  (11-1084). 
posterTime 

The  starting  time  for  the  movie  frame  that  contains  the  poster  image,  expressed 
in  the  movie's  time  coordinate  system. 
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SetMoviePreferredRate 


function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

Since  a  movie  poster  is  a  still  frame,  it  is  defined  by  a  point  in  time  within  the  movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Movie  Posters  and  Movie  Previews"  (V-2718) 

Related  Java  Methods 

qui ckti me. std .movi es .Movi e. set Post erTi  met ) 


See  Also 

Your  application  can  retrieve  a  poster's  time  by  calling  GetMovi  ePosterT i  me  (1-485). 


SetMoviePreferredRate 


Specifies  a  movie's  default  playback  rate. 

void  SetMoviePreferredRate  ( 

Movie  theMovie, 

Fi  xed  rate  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

rate 

The  new  movie  rate  as  a  32-bit,  fixed-point  number.  Positive  integers  indicate 
forward  rates  and  negative  integers  indicate  reverse  rates. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Preferred  Movie  Settings"  (V-2721) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . s et Prefer red Rate( ) 


See  Also 

You  can  set  the  current  playback  rate  of  a  movie  by  calling  SetMovi  eRate  (III— 1631). 


SetMoviePref  erred  V  olume 


Sets  a  movie's  preferred  volume  setting. 

void  SetMoviePreferredVolume  ( 

Movie  theMovie, 
short  volume  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

vol ume 

The  preferred  volume  setting  of  the  movie.  The  volume  parameter  must 
contain  a  16-bit,  fixed-point  number  that  contains  the  movie's  default  volume. 
The  high-order  8  bits  contain  the  integer  part  of  the  value;  the  low-order  8  bits 
contain  the  fractional  part.  Volume  values  range  from  -1.0  to  1.0.  Negative 
values  play  no  sound  but  preserve  the  absolute  value  of  the  volume  setting. 
You  may  find  the  constants  shown  below  useful. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

volume  Constants 

k  Fu 1 1 Vol ume 

Sets  the  track  to  full  volume  (constant  value  is  1.0). 
kNoVol ume 

Sets  the  track  to  no  volume  (constant  value  is  0.0). 
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SetMoviePreviewMode 


Discussion 

A  movie's  tracks  may  have  their  own  volume  settings.  Use  SetTrackVol  ume 
(III— 1669)  to  set  the  volume  of  an  individual  track.  A  track's  volume  is  scaled  by  the 
movie's  volume  to  produce  the  track's  final  volume. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Preferred  Movie  Settings"  (V-2721) 

Related  Java  Methods 

quicktime.std.movies.Movie.setPreferredVol ume( ) 


See  Also 

For  the  corresponding  get  function,  see  GetMovi  ePreferredVol  ume  (1-486). 


SetMoviePreviewMode 


Places  a  movie  into  and  out  of  preview  mode. 

void  SetMoviePreviewMode  ( 

Movie  theMovie, 

Boolean  usePreview  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovieFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

usePrevi ew 

The  movie's  mode.  Set  this  parameter  to  TRUE  to  place  the  movie  into  preview 
mode.  Set  this  parameter  to  FALSE  to  place  the  movie  into  normal  playback 
mode. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

When  a  movie  is  in  preview  mode,  only  those  tracks  identified  as  preview  tracks 
are  serviced.  You  specify  how  a  track  is  used  by  calling  SetTrackUsage  (III— 1668). 

When  you  place  a  movie  into  preview  mode,  the  Movie  Toolbox  sets  the  active 
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movie  segment  to  be  the  preview  segment  of  the  movie.  When  you  take  a  movie  out 
of  preview  mode  and  place  it  back  in  normal  playback  mode,  the  toolbox  sets  the 
active  movie  segment  to  be  the  entire  movie.  For  information  about  working  with 
active  movie  segments,  see  PrerollMovie  (11-1142). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Movie  Posters  and  Movie  Previews"  (V-2718) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . setPrevI ewMode( ) 


See  Also 

For  the  corresponding  get  function,  see  GetMovi  ePrevi  ewMode  (1-487). 


SetMo  viePre  vie  wT  ime 


Defines  the  starting  time  and  duration  of  the  movie's  preview. 

void  SetMoviePreviewTime  ( 

Movie  theMovie, 

TimeValue  previewTime, 

TimeValue  previ ewDurati on  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi eFromHandl e  (11-1084). 

previewTime 

A  time  value  that  specifies  the  preview's  starting  time, 
previ ewDurati on 

A  time  value  that  specifies  the  preview's  duration. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Movie  Posters  and  Movie  Previews"  (V-2718) 

Related  Java  Methods 

quicktime.std.movies.Movie.setPrevi ewT i me( ) 


See  Also 

For  the  corresponding  get  function,  see  GetMovi  ePrevi  ewT i me  (1-487). 


SetMovieProgressProc 

Attaches  a  progress  function  to  a  movie. 

void  SetMovieProgressProc  ( 

Movie  theMovie, 

Movi eProgressUPP  p, 

1 ong  refcon  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

P 

Points  to  your  Movi  eProgressProc  (III— 2105)  callback.  To  remove  a  movie's 
progress  function,  set  this  parameter  to  NI L.  Set  this  parameter  to  -1  for  the 
Movie  Toolbox  to  provide  a  default  progress  function. 

refcon 

Specifies  a  reference  constant.  Use  this  parameter  to  point  to  a  data  structure 
containing  any  information  your  callback  needs. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

The  Movie  Toolbox  calls  your  function  only  during  long  operations.  It  ensures  that 
your  progress  function  is  called  regularly,  but  not  too  often. 

The  following  Movie  Toolbox  functions  use  progress  functions: 

ConvertFi  1  eToMovi  eFi  1  e  (1-129),  CutMovi  eSel  ecti  on  (1-166),  CopyMovi  eSel  ecti  on 
(1-139),  AddMovi  eSel  ecti  on  (1-38),  and  InsertMovi  eSegment  (11-762). 


III-1630 


Inside  QuickTime:  Functions  R-Z 


SetMoviePropertyAtom 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Progress  and  Cover  Functions"  (V-2726) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . set Progress Proc( ) 


See  Also 

For  the  corresponding  get  function,  see  GetMovi  eProgressProc  (1-488). 


SetMoviePropertyAtom 


Sets  a  movie's  property  atom. 

OSErr  SetMoviePropertyAtom  ( 

Movie  theMovie, 

QTAtomContai ner  propertyAtom  ); 

theMovi e 

A  movie  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e 
(11-1084). 
propertyAtom 

A  property  atom. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

See  Also 

For  the  corresponding  get  function,  see  GetMovi  ePropertyAtom  (1-489). 


SetMovieRate 


Sets  a  movie's  playback  rate. 


Inside  QuickTime:  Functions  R-Z 


III-1631 


SetMovieSelection 


void  SetMovieRate  ( 

Movie  theMovie, 

Fi  xed  rate  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

rate 

The  new  movie  rate  as  a  32-bit,  fixed-point  number.  Positive  integers  indicate 
forward  rates  and  negative  integers  indicate  reverse  rates. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  Time"  (V-2732) 

Related  Java  Methods 

qui cktime. std .movi es .Movi e . setRatet ) 


See  Also 

For  the  corresponding  get  function,  see  GetMovi  eRate  (I — 490). 


SetMovieSelection 


Sets  a  movie's  current  selection. 

void  SetMovieSelection  ( 

Movie  theMovie, 

Time Value  selectionTime, 

TimeValue  sel ecti onDurati on  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

sel ecti onT i me 

A  time  value  specifying  the  starting  point  of  the  current  selection. 
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sel ecti onDurati on 

A  time  value  that  specifies  the  duration  of  the  current  selection. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "High-Level  Movie  Editing  Functions"  (V-2746) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . set Sel ecti  on ( ) 

See  Also 

For  the  corresponding  get  function,  see  GetMovi  eSel  ecti  on  (1-491). 


SetMoviesErrorProc 


Performs  custom  error  notification. 

void  SetMoviesErrorProc  ( 

MoviesErrorllPP  errProc, 

long  ref con  ); 

errProc 

A  MoviesErrorProc  (III— 2109)  callback, 
ref con 

A  reference  constant  value.  The  Movie  Toolbox  passes  this  reference  constant 
to  your  Movi esErrorProc  (III— 2109)  callback  each  time  it  calls  it.  Use  this 
parameter  to  point  to  a  data  structure  containing  any  information  your  callback 
needs. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

Your  application  must  identify  its  custom  error-notification  function  to  the  Movie 
Toolbox.  Once  you  have  identified  an  error-notification  function,  the  Movie 
Toolbox  calls  your  function  each  time  the  current  error  value  is  to  be  set  to  a  nonzero 
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SetMovieTime 


value.  The  Movie  Toolbox  calls  your  error-notification  function  only  in  response  to 
errors  generated  by  the  Movie  Toolbox. 

Special  Considerations 

Error-notification  functions  can  be  especially  useful  when  you  are  debugging  your 
program.  The  Movie  Toolbox  manages  the  sticky  error  value. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Error  Functions"  (V-2712) 


SetMovieTime 


Changes  a  movie's  current  time. 

void  SetMovieTime  ( 

Movie  theMovie, 

const  TimeRecord  *newtime  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

newtime 

A  pointer  to  a  Ti meRecord  (IV-2486)  structure  containing  the  new  time. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

The  Movie  Toolbox  saves  the  movie's  current  time  when  you  save  the  movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  Time"  (V-2732) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . setTi met ) 
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See  Also 

For  the  corresponding  get  function,  see  GetMovieTime  (1-495). 


SetMovieTimeScale 

Establishes  a  movie's  time  scale. 

void  SetMovieTimeScale  ( 

Movie  theMovie, 

TimeScale  timeScale  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
ti meScal e 

The  movie's  new  time  scale. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  Time"  (V-2732) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . setTi meScal e( ) 

See  Also 

For  the  corresponding  get  function,  see  GetMovi  eT i  meScal  e  (1-496). 


SetMo  vieT  ime  V  alue 

Sets  a  movie's  time  value. 

void  SetMovi eTimeVal ue  ( 
Movie  theMovie, 

TimeValue  newtime  ); 
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SetMovie  VideoOutput 


theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
newtime 

The  new  time  value.  You  must  ensure  that  the  time  value  is  in  the  movie's  time 
scale. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  Time"  (V-2732) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . setTi meVal ue( ) 


SetMovieVideoOutput 


Indicates  to  the  ICM  the  video  output  component  being  used  with  a  given  movie. 

void  SetMovieVideoOutput  ( 

Movie  theMovie, 

Componentlnstance  vout  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

vout 

The  video  output  component.  Applications  obtain  this  reference  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131).  Call  the  function 
and  pass  N I L  in  this  parameter  as  soon  as  the  video  output  component  is  no 
longer  in  use. 

Discussion 

As  soon  as  you  turn  on  the  echo  port  on  any  video  output  component,  you  should 
make  this  call  so  the  ICM  keeps  track  of  the  video  output  in  use. 
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SetMovie  Volume 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


SetMovie  V  olume 


Sets  a  movie's  current  volume. 

void  SetMovi eVol  lime  ( 

Movie  theMovie, 
short  volume  ); 

theMovi  e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi eFromHandl e  (11-1084). 

vol ume 

The  current  volume  setting  of  the  movie  represented  as  a  16-bit,  fixed-point 
number.  The  high-order  8  bits  contain  the  integer  part  of  the  value;  the 
low-order  8  bits  contain  the  fractional  part.  Volume  values  range  from  -1.0  to 
1.0.  Negative  values  play  no  sound  but  preserve  the  absolute  value  of  the 
volume  setting.  You  can  use  the  constants  shown  below. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

volume  Constants 

kFul  1  Vol  ume 

Sets  the  track  to  full  volume  (constant  value  is  1.0). 
kNoVol ume 

Sets  the  track  to  no  volume  (constant  value  is  0.0). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Sound  Volume"  (V-2732) 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . setVol  ume( ) 
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SetPosterBox 


See  Also 

For  the  corresponding  get  function,  see  GetMovi  eVol  ume  (1-500). 


SetPosterBox 


Sets  a  poster's  boundary  rectangle. 

void  SetPosterBox  ( 

Movie  theMovie, 

const  Rect  *boxRect  ) ; 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 
boxRect 

A  pointer  to  a  Rect  (IV-2399)  structure.  The  Movie  Toolbox  sets  the  poster's 
boundary  rectangle  to  the  coordinates  specified  in  the  structure  referred  to  by 
this  parameter. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

You  define  the  poster's  image  by  specifying  a  time  in  the  movie,  using 
SetMoviePosterTime  (III— 1 625) .  You  specify  the  size  and  position  of  the  poster  image 
with  this  function.  If  you  don't  specify  a  boundary  rectangle  for  the  poster,  the 
Movie  Toolbox  uses  the  movie's  matrix  when  it  displays  the  poster. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Movie  Posters  and  Movie  Previews"  (V-2718) 

Related  Java  Methods 

qu ickti me. std. mo vies. Mo vie. SetPosterBox () 


See  Also 

For  the  corresponding  get  function,  see  GetPosterBox  (1-505). 
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SetQuickT  imePref  erence 

Sets  a  particular  preference  in  the  QuickTime  preferences. 

OSErr  SetQuickTimePreference  ( 

OSType  preferenceType , 

QTAtomContai ner  preferenceAtom  ); 

preferenceType 

The  type  of  preference  to  set  (see  below);  also  see  "Atom  ID  Codes"  (IV-2649). 
preferenceAtom 

A  QT  atom  containing  the  preference  information. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

preferenceType  Constants 

Connecti onSpeedPref sType 

The  connection  speed  currently  set  in  the  QuickTime  Preferences;  the  atom  type 
passed  in  preferenceAtom  is  'cspd'. 

Bandwi dthManagementPref sType 

The  user's  current  bandwidth  management  preference;  the  atom  type  passed 
in  preferenceAtom  is  'bwmg'. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

See  Also 

For  the  corresponding  get  function,  see  GetQui  ckT i  mePreference  (1-507). 


SetSequenceProgressProc 


Installs  a  progress  procedure  for  a  sequence. 

OSErr  SetSequenceProgressProc  ( 

ImageSequence  seqlD, 

ICMProgressProcRecord  *progressProc  ); 
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SetSoundOutputlnfo 


seqlD 

The  unique  sequence  identifier  assigned  by  CompressSequenceBegi  n  (1-119)  or 
DecompressSequenceBegi n  (1-238). 
progressProc 

A  pointer  to  an  ICMProgressProcRecord  (IV-2284)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  allows  you  to  set  an  ICMProgressProc  (III— 2093)  callback  for  a 
compression  or  decompression  sequence,  just  as  you  can  set  a  progress  procedure 
when  compressing  or  decompressing  a  still  image. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Sequences"  (V-2792) 

SetSoundOutputlnfo 

Sets  information  about  the  current  sound  environment. 

OSErr  SetSoundOutputlnfo  ( 

Component  outputDevi ce , 

OSType  selector, 

const  void  *infoPtr  ); 

outputDevi ce 

The  identifier  of  a  sound  output  component.  Your  software  obtains  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131).  To 
access  the  default  output  device,  pass  N I L. 
sel ector 

The  selector  for  the  information  you  want  to  set;  see  "Sound  Information 
Selectors"  (IV-2693). 
i nfoPtr 

A  pointer  to  the  sound  device  information  to  be  passed. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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SetSoundPreference 


Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

For  the  corresponding  get  function,  see  GetSoundOutputlnfo  (1-511). 


SetSoundPreference 

Stores  a  block  of  preferences  data  in  a  sound  resource  file. 

OSErr  SetSoundPreference  ( 

OSType  theType, 

Str255  name. 

Handle  settings  ); 

theType 

The  resource  type  of  the  preferences  resource. 

name 

The  resource  name  of  the  preferences  resource, 
setti ngs 

A  handle  to  the  data  to  be  set  in  the  preferences  resource. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

For  the  corresponding  get  function,  see  GetSoundPreference  (1-512). 


SetSpriteProperty 

Sets  the  specified  property  of  a  sprite. 

OSErr  SetSpriteProperty  ( 

Sprite  theSprite, 

long  propertyType , 

void  *propertyVal ue  ); 
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SetSpriteProperty 


theSpri te 

The  sprite  for  this  operation. 
propertyType 

The  property  you  want  to  modify  (see  below). 
propertyVal ue 

The  new  value  of  the  property.  Depending  on  the  property  type,  you  set  the 
propertyVal  ue  parameter  to  either  a  pointer  to  the  property  value  or  the 
property  value  itself,  cast  as  a  voi  d  pointer. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

propertyType  Constants 

kSpritePropertyMatrix 

The  propertyVal  ue  parameter  is  the  sprite's  MatrixRecord  (IV-2304)  structure. 
kSpritePropertylmageDescription 

The  propertyVal  ue  parameter  is  an  ImageDescri  pti  onHandl  e,  which  is  a  handle 
to  the  sprite's  ImageDescri  pti  on  (IV-2285)  structure. 

kSpritePropertylmageDataPtr 

The  propertyVal  ue  parameter  is  a  Ptr,  which  is  a  pointer  to  the  sprite's  image 
data. 

kSpriteProperty Visible 

The  propertyVal  ue  parameter  is  a  Bool  ean  that  is  TRUE  if  the  sprite  is  visible, 
FALSE  otherwise. 
kSpri teP rope rty Layer 

The  propertyVal  ue  parameter  is  the  sprite's  layer  number. 
kSpri teProperty Graphics Mode 

The  propertyVal  ue  parameter  is  the  sprite's  Modi  f  i  erT rackGraphi  csModeRecord 
(IV-2311). 

Discussion 

You  animate  a  sprite  by  modifying  its  properties,  using  this  function.  It  invalidates 
the  sprite's  sprite  world  as  needed.  Here  is  sample  code  that  uses  this  function  to 
modify  a  sprite's  properties: 

//  SetSpriteProperty  coding  example 
//  See  “Discovering  QuickTime,”  page  345 
#define  kNumSprites  4 

#define  kNumSpaceShi plmages  24 
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SetSpriteProperty 


Rect  gBounceBox; 

Sprite  gSprites[kNumSprites] ; 

Rect  gDestRects[kNumSprites] ; 

Point  gDel tas [kNumSpri tes] ; 

short  gCur rent  I mages [kNumSpri tes] ; 

Handle  gCompressedPi ctures [kNumSpaceShi pi mages] ; 

void  MyMoveSpri tes  (void) 

{ 

short  nlndex; 

MatrixRecord  matrix; 

SetIdentityMatrix(&matrix) ; 

//  for  each  sprite 

for  (nlndex  =  0;  nlndex  <  kNumSprites;  nlndex++)  { 

//  modify  the  sprite’s  matrix 

Offs et Rect (&gDest Rect s[nlndex],  gDeltas[nIndex].h, 
gDeltas[nIndex] . v) ; 

if  (( gDestRects [nlndex] . ri ght  >=  gBounceBox. right)  | 

( gDestRects [nlndex] . 1  eft  <=  gBounceBox. 1  eft) ) 
gDel tas [nlndex] . h  =  -gDeltas[nIndex] .h; 

if  (( gDestRects [nlndex] . bottom  >=  gBounceBox. bottom)  | 
(gDestRects[nIndex] .top  <=  gBounceBox. top) ) 
gDeltas[nIndex] .v  =  -gDeltas[nIndex] .v; 

matrix. matrix[2][0]  =  (( 1 ong )gDestRects [nlndex] . 1  eft  <<  16); 
matrix. matrix[2][l]  =  ( (1 ong)gDestRects[nIndex] .top  <<  16); 

SetSpri te Property (gSpri tes [nlndex] ,  kSpri tePropertyMatrix, 
&matrix) ; 

//  change  the  sprite’s  image 
gCurrentImages[nIndex]++; 

if  (gCurrentImages[nIndex]  >=  ( kNumSpaceShi plmages  * 

( nlndex+l ) ) ) 

gCurrentImages[nIndex]  =  0; 

SetSpri te Property (gSpri tes [nlndex] ,  kSpri te Property ImageDataPtr , 
*gCompressedPictures[gCurrentImages[nIndex]  /  ( nlndex+l ) ] ) ; 
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SetSpriteWorldClip 


} 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Creating  and  Manipulating  Sprites"  (V-2901) 

Related  Java  Methods 

quickti me. std. anim. Sprite.setMatrixt ) , 
qu ickti me. std. an im. Sprite. setlmageDescriptionO, 
qu i c kt i me. std. an im. Sprite. setl mage Da ta(), 
quickti me. std. an im. Sprite. setVisiblet ) , 
quickti me. std. anim. Sprite. set  Layer ( ) , 
qu ickti me. std. an im. Sprite. setGraphicsMode( ) , 
qu i c kt i me. std. anim. Sprite. setl mage Da taSizeO 

See  Also 

For  the  corresponding  get  function,  see  GetSpri  teProperty  (1-512). 


SetSpriteW  orldClip 

Sets  a  sprite  world's  clip  shape  to  the  specified  region. 

OSErr  SetSpriteWorldClip  ( 

SpriteWorld  theSpri teWorl d , 

RgnHandl e  cl  i  pRgn  ) ; 

theSpri teWorl d 

The  sprite  world  for  this  operation, 
cl i pRgn 

The  new  clip  shape  for  the  sprite  world.  The  clip  shape  should  be  specified  in 
the  sprite  world's  source  space,  the  coordinate  system  of  the  sprite  layer's 
graphics  world  before  the  sprite  world's  matrix  is  applied  to  it.  You  may  pass  a 
value  of  N I L  for  this  parameter  to  indicate  that  there  is  no  longer  a  clip  shape  for 
the  sprite  world.  This  means  that  the  whole  area  is  drawn. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1^494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 
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Discussion 

You  call  this  function  to  change  the  clip  shape  of  a  sprite  world.  The  specified  region 
is  owned  by  the  caller  and  is  not  copied  by  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  with  Sprite  Worlds"  (V-2900) 

Related  Java  Methods 

qui cktime . app . anim. SWComposi tor . setCl i p( ) , 
qui cktime . std . anim. Sprl teWorl d . setCl i p ( ) 


SetSpriteWorldFlags 

Sets  flags  that  govern  the  behavior  of  a  sprite  world. 

OSErr  SetSpriteWorldFlags  ( 

SpriteWorld  spriteWorld, 

long  flags, 

long  flagsMask  ); 

spri  teWorl  d 

The  sprite  world  for  this  operation, 
fl  ags 

Constants  (see  below)  that  govern  sprite  world  behavior, 
fl agsMask 

Indicates  which  flags  in  the  fl  ags  parameter  are  to  be  considered  in  this 
operation.  For  eachbit  in  the  f  1  ags  parameter  that  you  want  the  Movie  Toolbox 
to  consider,  set  the  corresponding  bit  in  the  fl  agsMask  parameter  to  1.  Set 
unused  flags  to  0.  This  allows  you  to  work  with  a  single  optimization  without 
altering  the  settings  of  other  flags. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

flags  Constants 

kScaleSpritesToScaleWorld 

Undocumented 
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kSpriteWorldHighQuality 

Undocumented 

kSpriteWorldDontAutoInvalidate 
Undocumented 
kSpri teWorl dlnvi si bl e 
Undocumented 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Related  Java  Methods 

quicktime.std.anirri.SpriteWorld.setFlagsO 


SetSpriteWorldGraphicsMode 

Sets  the  graphics  transfer  mode  for  a  sprite  world. 

OSErr  SetSpriteWorldGraphicsMode  ( 

SpriteWorld  theSpri teWorl d , 

long  mode, 

const  RGBColor  *opColor  ); 

theSpri teWorl d 

The  sprite  world  for  this  operation. 

mode 

A  long  integer;  see  "Graphics  Transfer  Modes"  (IV-2670). 
opCol or 

A  pointer  to  an  RGBCol  or  (IV-2403)  structure.  This  is  the  blend  value  for  blends 
and  the  transparent  color  for  transparent  operations.  The  toolbox  supplies  this 
value  to  QuickDraw  when  you  draw  in  addPi  n,  subPi  n,  bl  end,  transparent,  or 
graphi  cs ModeSt rai  ghtAl  phaBl  end  mode. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Movi  es  .  h 

Related  Java  Methods 

qui cktime . std . anim. Spri teWorl d . setGraphi csMode( ) 


SetSpriteWorldMatrix 


Sets  a  sprite  world's  matrix  to  the  specified  matrix. 

OSErr  SetSpriteWorldMatrix  ( 

SpriteWorld  theSpri  teWorl  d  , 

const  MatrixRecord  *matrix  ); 

theSpri teWorl d 

The  sprite  world  for  this  operation, 
matri x 

A  pointer  to  the  new  matrix  for  the  sprite  world.  Transformations  may  include 
translation,  scaling,  rotation,  skewing,  and  perspective.  You  may  pass  a  value 
of  N I L  to  set  the  sprite  world's  matrix  to  an  identity  matrix. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  with  Sprite  Worlds"  (V-2900) 

Related  Java  Methods 

qui cktime . std . anim. Spri teWorl d . setMatrix( ) 


SetSysBeepVolume 


Sets  the  sound  volume  of  the  system  beep. 

OSErr  SetSysBeepVolume  ( 
long  level  ); 
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1  evel 

The  volume  level  to  be  set.  The  value  may  range  from  0x0000  (silence)  to  0x0100 
(full  volume). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

For  the  corresponding  get  function,  see  GetSysBeepVol  ume  (1-514). 


SetTimeBaseFlags 


Sets  the  contents  of  the  control  flags  of  a  time  base. 

void  SetTimeBaseFlags  ( 

TimeBase  tb, 

1 ong  ti meBaseFl ags  ) ; 


tb 

The  time  base  for  this  operation.  Your  application  obtains  this  time  base 
identifier  from  NewTimeBase  (11-1119). 

ti meBaseFl ags 

The  control  flags  for  this  time  base  (see  below).  You  may  set  only  one  flag  to  1. 
Be  sure  to  set  unused  flags  to  0. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

timeBaseFlags  Constants 

1  oopT i meBase 

Indicates  whether  the  time  base  loops.  If  you  set  this  flag  to  1  and  the  rate  is 
positive,  the  time  base  loops  back  and  restarts  from  its  start  time  when  it 
reaches  its  stop  time.  If  you  set  this  flag  to  1  and  the  rate  is  negative,  the  time 
base  loops  to  its  stop  time.  If  you  set  the  flag  to  0,  the  movie  stops  when  it 
reaches  the  end. 
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pal i ndromeLoopTi meBase 

Indicates  whether  the  time  base  loops  in  a  palindrome  fashion.  Palindrome 
looping  causes  a  time  base  to  move  alternately  forward  and  backward.  Set  this 
flag  to  1  to  cause  the  time  base  to  loop  in  this  manner. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Time  Base  Values"  (V-2760) 

Related  Java  Methods 

qui cktime . std . cl ocks . Ti meBase . set  FI ags ( ) 


See  Also 

For  the  corresponding  get  function,  see  GetTimeBaseFlags  (1-515). 


SetTimeBaseMasterClock 


Assigns  a  clock  component  to  a  time  base. 

void  SetTimeBaseMasterClock  ( 

TimeBase  slave. 

Component  cl ockMei ster , 

const  TimeRecord  *slaveZero  ); 

slave 

The  time  base  for  this  operation.  Your  application  obtains  this  time  base 
identifier  from  NewTimeBase  (11-1119). 
cl ockMei ster 

The  clock  component  to  be  assigned  to  this  time  base.  Your  application  can 
obtain  this  component  identifier  from  Fi  ndNextComponent  (1-360). 

si aveZero 

A  pointer  to  the  time,  in  the  clock's  time  scale,  that  corresponds  to  a  0  time  value 
for  the  slave  time  base.  This  parameter  allows  you  to  set  an  offset  between  the 
time  base  and  the  clock  component.  Set  this  parameter  to  N I L  if  there  is  no  offset. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 
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SetTimeBaseMasterTimeBase 


Discussion 

A  time  base  derives  its  time  from  either  a  clock  component  or  from  another  time 
base.  Don't  use  this  function  to  assign  a  clock  to  a  movie's  time  base. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Creating  and  Disposing  of  Time  Bases"  (V-2759) 

Related  Java  Methods 

qu ickti me. std. clocks. Time Base. set MasterClockO 


See  Also 

For  the  corresponding  get  function,  see  GetTimeBaseMasterCl  ock  (1-516). 


SetTimeBaseMasterTimeBase 


Assigns  a  master  time  base  to  a  time  base. 

void  SetTimeBaseMasterTimeBase  ( 

TimeBase  slave, 

TimeBase  master, 

const  TimeRecord  *slaveZero  ); 

si  ave 

The  time  base  for  this  operation.  Your  application  obtains  this  time  base 
identifier  from  NewTimeBase  (11-1119). 

master 

The  master  time  base  to  be  assigned  to  this  time  base.  Your  application  obtains 
this  time  base  identifier  from  NewT i meBase  (11-1119). 
si  aveZero 

A  pointer  to  the  time,  in  the  time  scale  of  the  master  time  base,  that  corresponds 
to  a  0  time  value  for  the  slave  time  scale.  This  parameter  allows  you  to  set  an 
offset  between  the  time  base  and  the  master  time  base.  Set  this  parameter  to  N I L 
if  there  is  no  offset. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 
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SetTimeBaseRate 


Discussion 

A  time  base  derives  its  time  from  either  a  clock  component  or  another  time  base. 
Don't  use  this  function  to  assign  a  master  time  base  to  a  movie's  time  base. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Creating  and  Disposing  of  Time  Bases"  (V-2759) 

Related  Java  Methods 

qui cktime . std . cl ocks . TimeBase . setMasterT imeBase( ) 


See  Also 

For  the  corresponding  get  function,  see  GetT i  meBaseMasterT i meBase  (1-517). 


SetTimeBaseRate 


Sets  the  rate  of  a  time  base. 

void  SetTimeBaseRate  ( 
TimeBase  tb. 

Fixed  r  ); 


tb 

The  time  base  for  this  operation.  Your  application  obtains  this  time  base 
identifier  from  NewTimeBase  (11-1119). 

r 

The  rate  of  the  time  base. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

Rates  may  be  set  to  negative  values.  Negative  rates  cause  time  to  move  backward 
for  the  time  base. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Time  Base  Values"  (V-2760) 


Inside  QuickTime:  Functions  R-Z 
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SetTimeBaseStartTime 


Related  Java  Methods 

qu i c kt i me. std. clocks. Time Base. set RateO 

See  Also 

For  the  corresponding  get  function,  see  GetTimeBaseRate  (1-518). 


SetT  imeBaseStartT  ime 


Sets  the  start  time  of  a  time  base. 

void  SetTimeBaseStartTime  ( 
TimeBase  tb, 

const  TimeRecord  *tr  ); 


tb 

The  time  base  for  this  operation.  Your  application  obtains  this  time  base 
identifier  from  NewTimeBase  (11-1119). 

tr 

A  pointer  to  a  Ti  meRecord  (IV-2486)  structure  that  contains  the  start  time  value. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

The  start  time  defines  the  time  base's  minimum  time  value.  You  must  specify  the 
new  start  time  in  a  time  structure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Time  Base  Values"  (V-2760) 

Related  Java  Methods 

qu i c kt ime. std. clocks. Time Base. setStartTi me () 

See  Also 

For  the  corresponding  get  function,  see  GetTimeBaseStartTime  (1-518). 


SetTimeBaseStopTime 

Sets  the  stop  time  of  a  time  base. 
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SetTimeBaseTime 


void  SetTimeBaseStopTime  ( 
TimeBase  tb, 

const  TimeRecord  *tr  ); 


tb 

The  time  base  for  this  operation.  Your  application  obtains  this  time  base 
identifier  from  NewTimeBase  (11-1119). 
tr 

A  pointer  to  a  Ti  meRecord  (IV-2486)  structure  that  contains  the  stop  time  value. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

The  stop  time  defines  the  time  base's  maximum  time  value.  You  must  specify  the 
new  stop  time  in  a  time  structure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Time  Base  Values"  (V-2760) 

Related  Java  Methods 

qui ckti me . std . cl ocks . TimeBase . setStopTi me ( ) 

See  Also 

For  the  corresponding  get  function,  see  GetT i  meBaseStopT ime  (1-520). 


SetTimeBaseTime 


Sets  the  current  time  of  a  time  base. 

void  SetTimeBaseTime  ( 

TimeBase  tb, 

const  TimeRecord  *tr  ); 


The  time  base  for  this  operation.  Your  application  obtains  this  time  base 
identifier  from  NewTimeBase  (11-1119). 
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SetTimeBaseValue 


tr 

A  pointer  to  a  Ti  meRecord  (IV-2486)  structure  that  contains  the  current  time 
value. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi es .  h 

Programming  summary:  "Working  With  Time  Base  Values"  (V-2760) 

Related  Java  Methods 

qui cktime. std . cl ocks .TimeBase . setTimet ) 


See  Also 

For  the  corresponding  get  function,  see  GetTimeBaseTime  (1-521). 


SetTimeBaseValue 


Sets  the  current  time  of  a  time  base. 

void  SetTimeBaseValue  ( 

TimeBase  tb, 

T imeVal ue  t , 

TimeScale  s  ) ; 


tb 

The  time  base  for  this  operation.  Your  application  obtains  this  time  base 
identifier  from  NewTimeBase  (11-1119). 
t 

The  new  time  value. 

s 

The  time  scale  of  the  new  time  value. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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SetTimeBaseZero 


Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Time  Base  Values"  (V-2760) 

Related  Java  Methods 

qui cktime . std . cl ocks . TimeBase . setVal ue( ) 


SetTimeBaseZero 


Changes  the  offset  from  a  time  base  to  either  its  master  time  base  or  its  clock 
component. 

void  SetTimeBaseZero  ( 

TimeBase  tb, 

TimeRecord  *zero  ); 


tb 

The  time  base  for  this  operation.  Your  application  obtains  this  time  base 
identifier  from  NewTimeBase  (11-1119). 

zero 

A  pointer  to  the  time  that  corresponds  to  a  0  time  value  for  the  slave  time  scale. 
This  parameter  allows  you  to  set  an  offset  between  the  time  base  and  its  time 
source.  Set  this  parameter  to  N I L  if  there  is  no  offset. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

You  establish  the  initial  offset  when  you  assign  the  time  base  to  its  time  source. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Creating  and  Disposing  of  Time  Bases"  (V-2759) 

Related  Java  Methods 

qui cktime . std . cl ocks .TimeBase . set Zero ( ) 


Inside  QuickTime:  Functions  R-Z 
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SetTrackAlternate 


SetT  rackAlternate 


Adds  tracks  to,  or  remove  tracks  from,  alternate  groups. 

void  SetTrackAlternate  ( 

Track  theTrack, 

T rack  al ternateT  ) ; 

theT  rack 

The  track  and  group  for  this  operation.  Your  application  obtains  this  track 
identifier  from  such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack 
(1-497).  SetTrackAl  ternate  changes  this  track's  group  affiliation  based  on  the 
value  of  the  al  ternateT  parameter. 

al ternateT 

Controls  whether  the  function  adds  the  track  to  a  group  or  removes  it  from  a 
group.  If  this  parameter  contains  a  valid  track  identifier,  the  Movie  Toolbox 
adds  this  track  to  the  group  that  contains  the  track  specified  by  the  parameter 
theT  rack.  If  the  track  identified  by  this  parameter  already  belongs  to  a  group, 
the  Movie  Toolbox  combines  the  two  groups  into  a  single  group. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Alternate  Tracks"  (V-2738) 

Related  Java  Methods 

quickti me. std. mo vies. Track. setAlternateO 


See  Also 

For  the  corresponding  get  function,  see  GetT rackAl  ternate  (1-522). 


SetT  rackClipRgn 


Sets  the  clipping  region  of  a  track. 

void  SetTrackCl i pRgn  ( 

Track  theTrack, 

RgnHandl e  theCl ip  ) ; 
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SetTrackDimensions 


theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 
theCl i p 

A  handle  to  the  track's  clipping  region.  The  Movie  Toolbox  makes  a  copy  of  this 
region.  Your  application  must  dispose  of  the  region  referred  to  by  this 
parameter  when  you  are  done  with  it.  Set  this  parameter  to  N I L  to  disable 
clipping  for  the  track. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qui ckti me . std .movi es .Track. set Cl i pRgn( ) 


See  Also 

For  the  corresponding  get  function,  see  GetT rackCl  i  pRgn  (1-524). 


SetT  rackDimensions 


Establishes  a  track's  source  rectangle. 

void  SetTrackDimensions  ( 

Track  theTrack, 

Fixed  width. 

Fixed  height  ); 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT  rack  (11-1092)  and  GetMovi  eT  rack  (1-497). 

wi  dth 

A  fixed-point  number  that  specifies  the  width,  in  pixels,  of  the  track's  rectangle. 
This  value  corresponds  to  the  x  coordinate  of  the  lower-right  corner  of  the 
track's  rectangle. 
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SetTrackEnabled 


hei ght 

A  fixed-point  number  that  specifies  the  height,  in  pixels,  of  the  track's  rectangle. 
This  value  corresponds  to  the  y  coordinate  of  the  lower-right  corner  of  the 
track's  rectangle. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

If  you  change  the  dimensions  of  an  existing  track,  the  media  data  is  scaled  to  fit  into 
the  new  rectangle. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

quickti me. std. mo vies. Track. setDimensionsO 


See  Also 

For  the  corresponding  get  function,  see  GetT rackDi mensi  ons  (1-527). 


SetT  rackEnabled 

Enables  or  disables  a  track. 

void  SetTrackEnabled  ( 

Track  theTrack, 

Bool ean  i sEnabl ed  ) ; 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 
i sEnabl ed 

Enables  or  disables  the  track.  Set  this  parameter  to  TRUE  to  enable  the  track.  Set 
this  parameter  to  FALSE  to  disable  the  track. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 
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SetTrackGWorld 


Discussion 

The  Movie  Toolbox  services  only  enabled  tracks. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Disabling  Movies  and  Tracks"  (V-2724) 

Related  Java  Methods 

qui ckti me . std .movi es .Track. set Enabl ed( ) 


See  Also 

For  the  corresponding  get  function,  see  GetTrackEnabled  (1-531). 


SetTrackGWorld 


Forces  a  track  to  draw  into  a  particular  graphics  world,  which  maybe  different  from 
that  of  the  movie. 

void  SetTrackGWorld  ( 

T  rack 
CGraf Ptr 
GDHandl e 

T  rackT  ransf  erllPP 
1  ong 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

port 

Points  to  the  graphics  port  structure  or  graphics  world  to  which  to  draw  the 
track.  Set  this  parameter  to  N I L  to  use  the  movie's  graphics  port. 

gdh 

A  handle  to  the  movie's  graphics  device  structure.  Set  this  parameter  to  N I L  to 
use  the  current  device.  If  the  port  parameter  specifies  a  graphics  world,  set  this 
parameter  to  N I L  to  use  that  graphics  world's  graphics  device. 

proc 

A  pointer  to  your  T  rackT  ransf  erProc  (III— 2151)  callback.  Set  this  parameter  to 
N I L  if  you  want  to  remove  your  callback. 


theTrack, 
port , 
gdh , 
proc , 
refCon  ) ; 
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SetTrackLayer 


refCon 

A  value  to  pass  to  your  TrackTransferProc  callback.  Use  this  parameter  to  point 
to  a  data  structure  containing  any  information  your  callback  needs. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

After  this  function  draws  a  track,  it  calls  your  transfer  callback  to  copy  the  track  to 
the  actual  movie  graphics  world.  When  your  transfer  callback  is  called,  the  current 
graphics  world  is  set  to  the  correct  destination.  You  can  also  install  a  transfer 
callback  and  set  the  graphics  world  to  NIL.  In  this  case,  the  function  calls  your 
callback  only  as  a  notification  that  the  track  has  been  drawn;  no  transfer  needs  to 
take  place. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi es .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qu ickti me. std. mo vies. Track. set GWorldO 


SetTrackLayer 

Sets  a  track's  layer. 

void  SetTrackLayer  ( 

Track  theTrack, 

short  1 ayer  ) ; 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

1  ayer 

The  track's  layer  number.  Layers  are  numbered  from  -32,768  through  32,767. 
When  you  create  a  new  track,  the  Movie  Toolbox  sets  its  track  number  to  0. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qui ckti me . std .movi es . Track. set  Layer ( ) 


See  Also 

For  the  corresponding  get  function,  see  GetTrackLayer  (1-532). 


SetT  rackLoadSettings 


Specifies  a  portion  of  a  track  that  is  to  be  loaded  into  memory  whenever  it  is  played. 


void  SetTrackLoadSettings  ( 


T  rack 
T i meVal ue 
T i meVal ue 
1  ong 
1  ong 


theTrack, 
prel  oadTime, 
prel oadDurati on , 
prel  oadFl  ags , 
defaultHints  ); 


theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 
prel oadT i me 

The  starting  point  of  the  portion  of  the  track  to  be  preloaded.  Set  this  parameter 
to  -1  if  you  want  to  preload  the  entire  track  (in  this  case  the  function  ignores  the 
prel  oadDurati  on  parameter).  This  parameter  should  be  specified  using  the 
movie's  time  scale. 

prel oadDurati on 

The  amount  of  the  track  to  be  preloaded,  starting  from  the  time  specified  in  the 
preloadTime  parameter.  If  you  are  preloading  the  entire  track,  the  function 
ignores  this  parameter. 

prel  oadFl  ags 

Controls  when  the  toolbox  preloads  the  track.  The  function  supports  the 
following  flag  values: 
def aul t H i nts 

Specifies  playback  hints  for  the  track.  You  may  specify  any  of  the  supported 
hints  flags. 
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SetTrackMatrix 


function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

preloadFlags  Constants 

prel oadAl ways 

Specifies  that  the  toolbox  should  always  preload  this  track,  even  if  the  track  is 
disabled. 

preloadOnlylfEnabled 

Specifies  that  the  toolbox  should  preload  this  track  only  when  the  track  is 
enabled. 

Discussion 

This  function  allows  you  to  control  how  the  toolbox  preloads  the  tracks  in  your 
movie.  By  using  its  settings,  you  make  this  information  part  of  the  movie,  so  that  the 
preloading  takes  place  every  time  the  movie  is  opened,  without  an  application 
having  to  call  LoadT racklntoRam  (11-782).  Consequently,  you  should  use  this  feature 
carefully,  so  that  your  movies  don't  consume  large  amounts  of  memory  when 
opened. 

Special  Considerations 

The  toolbox  transfers  this  preload  information  when  you  call  CopyT rackSetti  ngs 
(1-141).  In  addition,  the  preload  information  is  preserved  when  you  save  or  flatten 
a  movie.  In  flattened  movies,  the  tracks  that  are  to  be  preloaded  are  stored  at  the 
start  of  the  movie,  rather  than  being  interleaved  with  the  rest  of  the  movie  data.  This 
improves  preload  performance. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi es .  h 

Programming  summary:  "Enhancing  Movie  Playback  Performance"  (V-2722) 

Related  Java  Methods 

qu ickti me. std. mo vies. Track. set LoadSettingsO 


See  Also 

For  the  corresponding  get  function,  see  GetT rackLoadSetti  ngs  (1-532). 


SetT  rackMatrix 

Establishes  a  track's  transformation  matrix, 
void  SetTrackMatrix  ( 
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Track  theTrack, 

const  MatrixRecord  *matrix  ); 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 
matri x 

A  pointer  to  a  Matri  xRecord  (IV-2304)  structure  that  contains  the  track's  new 
matrix.  If  you  set  this  parameter  to  NIL,  the  Movie  Toolbox  uses  the  identity 
matrix. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

Related  Java  Methods 

qui ckti me . std .movi es .Track. setMatrixC ) 


See  Also 

See  Setldenti  tyMatri x  (III — 1593). 


SetTrackMatte 


Sets  a  track's  matte. 

void  SetTrackMatte  ( 

Track  theTrack, 

PixMapHandle  theMatte  ); 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT  rack  (11-1092)  and  GetMovi  eT  rack  (1-497). 

theMatte 

A  handle  to  the  matte.  The  Movie  Toolbox  makes  a  copy  of  the  matte,  including 
its  Col  orTabl  e  (IV-2210)  structure  and  pixels.  Consequently,  your  application 
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SetTrackOffset 


must  dispose  of  the  matte  when  you  are  done  with  it.  Set  this  parameter  to  N I L 
to  remove  the  track's  matte. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

This  matte  defines  which  of  the  track's  pixels  are  displayed  in  a  movie.  You  must 
specify  the  matte  in  a  Pi  xMap  (IV-2332)  structure.  The  Movie  Toolbox  displays  the 
weighted  average  of  the  track  and  its  destination  based  on  the  corresponding  pixel 
in  the  matte. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  Spatial  Characteristics"  (V-2728) 

See  Also 

For  the  corresponding  get  function,  see  GetT rackMatte  (1-534). 


SetTrackOffset 


Modifies  the  duration  of  the  empty  space  that  lies  at  the  beginning  of  a  track,  thus 
changing  the  duration  of  the  entire  track. 

void  SetTrackOffset  ( 

Track  theTrack, 

TimeValue  movi eOffsetTime  ); 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1—497). 
movi eOffsetT  i  me 

The  track's  offset  from  the  start  of  the  movie,  and  must  be  expressed  in  the  time 
scale  of  the  movie  that  contains  the  track. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 
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Discussion 

All  of  the  tracks  in  a  movie  use  the  movie's  time  coordinate  system.  That  is,  the 
movie's  time  scale  defines  the  basic  time  unit  for  each  of  the  movie's  tracks.  Each 
track  begins  at  the  beginning  of  the  movie,  but  the  track's  data  might  not  begin  until 
some  time  value  other  than  0.  This  intervening  time  is  represented  by  blank  space. 
In  an  audio  track  the  blank  space  translates  to  silence;  in  a  video  track  the  blank 
space  generates  no  visual  image.  Each  track  has  its  own  duration.  This  duration 
need  not  correspond  to  the  duration  of  the  movie.  Movie  duration  always  equals  the 
maximum  duration  of  all  the  tracks. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Track  Time"  (V-2733) 

Related  Java  Methods 

qui ckti me . std .movi es . Track. setOf f set( ) 


See  Also 

For  the  corresponding  get  function,  see  GetTrackOffset  (1-539). 


SetT  rackRef  erence 


Modifies  an  existing  track  reference. 

OSErr  SetTrackReference  ( 

Track  theTrack, 

Track  refTrack, 

OSType  refType, 

long  index  ); 

theT  rack 

Identifies  the  track  for  this  operation.  Your  application  obtains  this  track 
identifier  from  such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack 
(1-497). 
refT  rack 

The  track  to  be  identified  in  the  track  reference.  The  toolbox  uses  this 
information  to  update  the  existing  track  reference. 

refType 

The  type  of  reference. 
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i  ndex 

The  index  value  of  the  reference  to  be  changed.  You  obtain  this  index  value 
when  you  create  the  track  reference. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

You  may  change  the  track  reference  so  that  it  identifies  a  different  track  in  the 
movie. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Track  References"  (V-2737) 

Related  Java  Methods 

qu ickti me. std. mo vies. Track. set Reference!) 


See  Also 

For  the  corresponding  get  function,  see  GetTrackReference  (1-541). 


SetTrackSoundLocalizationSettings 

Applies  3D  sound  effect  data  to  a  track. 

OSErr  SetTrackSoundLocal i zati onSetti ngs  ( 

Track  theTrack, 

Handl e  setti ngs  ) ; 

theT  rack 

Identifies  the  track  for  this  operation.  Your  application  obtains  this  track 
identifier  from  such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack 
(1-497). 
setti ngs 

A  handle  to  the  settings  you  want  to  apply,  in  the  format  of  an 
SSp  Local  i  zati  on  Data  (IV-2460)  record.  You  can  pass  a  NI L  handle  to  indicate 
that  no  3D  sound  effects  should  be  used  for  this  track.  This  function  makes  a 
copy  of  the  handle  passed,  so  the  caller  is  responsible  for  disposing  of  it. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
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(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

This  function  replaces  the  3D  sound  settings  for  the  specified  track  with  the  new 
SSpLocal  i  zati  onData  record  contained  in  the  setti  ngs  parameter.  The  effect  of  the 
new  3D  sound  setting  takes  place  immediately.  This  call  always  stores  the  new 
record  passed,  even  if  the  track  or  the  computer  is  not  capable  of  actually  meeting 
the  request.  When  the  movie  is  saved,  the  3D  sound  settings  are  saved  with  it. 

The  following  example  code  shows  how  to  set  the  static  3D  sound  setting  for  a  track 
using  this  function: 

//  SetTrackSoundLocal i zati onSetti ngs  coding  example 
void  SetTrackSoundLocal  i zati  ondrack  t) 

{ 

SSpLocal i zati onData  loc; 

Handle  h; 

OSErr  err; 

1 oc . cpuLoad  =  0 ; 

loc. medium  =  kSSpMedi um_Ai r ; 

1 oc . humi di ty  =  0 ; 

1 oc . roomSi ze  =  250 ; 

1 oc . roomRef 1 ecti vi ty  =  -5; 

1 oc . reverbAttenuati on  =  -5; 

1 oc . sourceMode  =  kSSpSourceMode_Local i zed ; 

1 oc . referenceDi stance  =  1; 

1 oc . coneAngl eCos  =  0; 

1 oc . coneAttenuati on  =  0; 

1 oc . currentLocati on . el evati on  =  0; 

1 oc . currentLocati on . azimuth  =  0; 

1 oc . currentLocati on . di stance  =  2; 

1 oc . currentLocati on . projecti onAngl e  =  0; 

1 oc . currentLocati on . sourceVel oci ty  =  0; 

1 oc . currentLocati on . 1 i stenerVel oci  ty  =  0; 

1 oc . reservedO  =  0 ; 

1 oc . reservedl  =  0 ; 

1 oc . reserved2  =  0 ; 

1 oc . reserved3  =  0 ; 

1 oc . vi rtual SourceCount  =  0; 
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err  =  PtrToHandt &1 oc ,  &h,  si zeof ( 1 oc) ) ; 

err  =  SetTrackSoundLocal i zati onSetti ngs ( t ,  h); 

Di sposeHandl e ( h ) ; 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Track  Sound"  (V-2740) 

Related  Java  Methods 

qui ckti me. std. mo vies. Track. setSound Local izationSettingst) 


See  Also 

For  the  corresponding  get  function,  see  GetT rackSoundLocal  i  zati  onSetti  ngs  (1-543). 


SetTrackUsage 


Specifies  whether  a  track  is  used  in  a  movie,  its  preview,  its  poster,  or  a  combination 
of  these. 

void  SetTrackUsage  ( 

Track  theTrack, 

1  ong  usage  ) ; 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 
usage 

Contains  flags  (see  below)  that  specify  how  the  track  is  to  be  used.  Be  sure  to  set 
unused  flags  to  0. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

usage  Constants 

trackUsagelnMovi e 

If  this  flag  is  set  to  1,  the  track  is  used  in  the  movie. 
trackUsagelnPreview 

If  this  flag  is  set  to  1,  the  track  is  used  in  the  preview. 


III-1668 


Inside  QuickTime:  Functions  R-Z 


S  etTrack  Volume 


trackUsagelnPoster 

If  this  flag  is  set  to  1,  the  track  is  used  in  the  poster. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Movie  Posters  and  Movie  Previews"  (V-2718) 

Related  Java  Methods 

qui ckti me . std .movi es . Track. set Us  age ( ) 


See  Also 

For  the  corresponding  get  function,  see  GetTrackLIsage  (1-545). 


SetT  rackV  olume 

Sets  a  track's  current  volume. 

void  SetTrackVol  lime  ( 

Track  theTrack, 
short  volume  ); 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 
vol ume 

The  current  volume  setting  of  the  track  represented  as  a  16-bit,  fixed-point 
number.  The  high-order  8  bits  contain  the  integer  part  of  the  value;  the 
low-order  8  bits  contain  the  fractional  part.  Volume  values  range  from  -1.0  to 
1.0.  Negative  values  play  no  sound  but  preserve  the  absolute  value  of  the 
volume  setting.  You  can  use  constants  (see  below)  for  full  volume  and  no 
volume. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

volume  Constants 

kFul  1  Vol  ume 

Sets  the  track  to  full  volume  (constant  value  is  1.0). 
kNoVol ume 

Sets  the  track  to  no  volume  (constant  value  is  0.0). 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi es .  h 

Programming  summary:  "Working  With  Sound  Volume"  (V-2732) 

Related  Java  Methods 

qu ickti me. std. mo vies. Track. setVol ume( ) 


See  Also 

For  the  corresponding  get  function,  see  GetT rackVol  ume  (1-547). 


Setup  AIFFHeader 


Sets  up  an  AIFF  or  AIFF-C  sound  file. 


OSErr  SetupAI FFHeader 
short 
short 

Unsi gnedFi xed 

short 

OSType 

unsigned  long 
unsigned  long 


( 

f Ref Num , 
numChannel  s , 
sampl eRate , 
sampl eSi ze , 
compressi onType , 
numBytes , 
numFrames  ) ; 


f Ref Num 

A  file  reference  number  of  a  file  that  is  open  for  writing. 
numChannel s 

The  number  of  channels  for  the  sound:  1  for  monaural  sound  and  2  for  stereo 
sound, 
sampl eRate 

The  rate  at  which  the  sound  was  recorded.  To  accommodate  sample  rates 
greater  than  32  kHz,  the  most  significant  bit  is  not  treated  as  a  sign  bit;  instead, 
that  bit  is  interpreted  as  having  the  value  32,768. 

sampl eSi ze 

The  sample  size  for  the  original  sound  in  bits  per  sample, 
compressi onType 

The  compression  type  for  the  sound,  such  as  '  NONE ',  '  MAC3 ',  '  MAC6 ',  or  other 
types.  See  "Sound  Formats"  (IV-2692). 
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numBytes 

The  number  of  bytes  of  sound  data  that  are  to  be  stored  in  the  Common  Chunk 
of  the  AIFF  or  AIFF-C  file.  If  recording  produces  an  odd  number  of  bytes  of 
sound  data,  you  must  add  a  pad  byte  to  make  the  total  number  of  bytes  even. 
numFrames 

The  number  of  sample  frames  for  the  sample  sound.  If  you  are  using  a 
compression  type  defined  by  Apple,  you  can  pass  0  in  this  field  and  the 
appropriate  value  for  this  field  will  be  computed  automatically. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  creates  an  AIFF  or  AIFF-C  file  header,  depending  on  the  parameters 
passed  to  it.  Uncompressed  sounds  (that  is,  the  compressi  onType  parameter  is 
'  NON E ' )  of  any  type  are  stored  in  AIFF  format.  Compressed  sounds  of  any  type  are 
stored  in  AIFF-C  format.  The  SetupAI  FFHeader  function  might  format  a  sound  file  as 
an  AIFF  file  even  if  the  File  Manager  file  type  of  a  file  is  '  A I FC ' .  The  Sound  Manager 
will  still  play  such  files  correctly. 

The  AIFF  header  information  is  written  starting  at  the  current  file  position  of  the  file 
specified  by  the  f  Ref  Num  parameter,  and  the  file  position  is  left  at  the  end  of  the 
header  upon  completion.  The  SetupAI  FFHeader  function  creates  a  Form  Chunk,  a 
Format  Version  Chunk,  a  Common  Chunk,  and  a  Sound  Data  chunk,  but  it  does  not 
put  any  sound  data  at  the  end  of  the  Sound  Data  Chunk. 

A  good  way  to  use  this  routine  is  to  create  a  file  that  you  want  to  store  a  sound  in, 
then  call  SetupAI  FFHeader  with  numBytes  set  to  0  to  position  the  file  to  be  ready  to 
write  the  audio  data.  Then  record  the  data  to  the  file,  set  the  file  position  to  the 
beginning  of  the  file,  and  call  SetupAI  FFHeader  again  with  numBytes  set  to  the  correct 
amount  of  sound  data  recorded.  The  file  created  in  this  way  can  be  passed  to 
SndStartFi  1  ePl  ay  (III— 1847)  to  play  the  sound. 

Special  Considerations 

Because  the  SetupAI  FFHeader  function  moves  memory,  you  should  not  call  it  at 
interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 
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SetupSndHeader 


Constructs  a  sound  resource  containing  sampled  sound  that  can  be  passed  to 
SndPlay  (III — 1842). 


OSErr  SetupSndHeader 
SndLi stHandl e 
short 

Unsi gnedFi xed 
short 
OSType 
short 

unsigned  long 
short 


( 

sndHandl e , 
numChannel s , 
sampl eRate , 
sampl eSi ze , 
compressi onType , 
baseNote , 
numBytes , 
*headerLen  ) ; 


sndHandl e 

A  handle  to  a  block  of  memory  that  is  at  least  large  enough  to  store  a 
SndLi  st  Resource  (IV-2447)  structure.  The  handle  is  not  resized  many  way  upon 
successful  completion  of  this  call.  This  function  simply  fills  the  relocatable 
block  specified  by  this  parameter  with  the  header  information  needed  for  a 
format  1  '  s  n  d  '  resource,  including  the  sound  resource  header,  the  list  of  sound 
commands,  and  a  sampled  sound  header.  It  is  your  application's  responsibility 
to  append  the  desired  sampled-sound  data. 

numChannel s 

The  number  of  channels  for  the  sound;  one  channel  is  equivalent  to  monaural 
sound  and  two  channels  are  equivalent  to  stereo  sound, 
sampl eRate 

The  rate  at  which  the  sound  was  recorded.  To  accommodate  sample  rates 
greater  than  32  kHz,  the  most  significant  bit  is  not  treated  as  a  sign  bit;  instead, 
that  bit  is  interpreted  as  having  the  value  32,768. 
sampl eSi ze 

The  sample  size  for  the  original  sound  (that  is,  bits  per  sample), 
compressi onType 

The  compression  type  for  the  sound,  such  as  '  NONE ',  '  MAC3 ',  '  MAC6 ',  or  other 
types.  See  "Sound  Formats"  (IV-2692). 
baseNote 

The  base  frequency  for  the  sound,  expressed  as  a  MIDI  note  value. 
numBytes 

The  number  of  bytes  of  audio  data  that  are  to  be  stored  in  the  handle.  This  value 
is  not  necessarily  the  same  as  the  number  of  samples  in  the  sound. 
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headerLen 

On  return,  the  size  (in  bytes)  of  the  '  s  n  d  '  resource  header  that  is  created.  In  no 
case  will  this  length  exceed  100  bytes.  This  field  allows  you  to  put  the  audio 
data  right  after  the  header  in  the  relocatable  block  specified  by  the  sndHandle 
parameter.  The  value  returned  depends  on  the  type  of  sound  header  created. 
Uncompressed  sound  with  a  single  8-bit  channel  goes  into  aSoundHeader 
(IV-2452)  structure.  Other  uncompressed  sound  goes  into  an  ExtSoundHeader 
(IV-2255)  structure.  Compressed  sound  goes  into  a  CmpSoundHeader  (IV-2176) 
structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  creates  a  format  1  '  snd  '  resource  for  a  sampled  sound.  The  resource 
contains  a  sound  resource  header  that  links  the  sound  to  the  sampled  synthesizer, 
a  single  sound  command  (a  bufferCmd  command  to  play  the  accompanying  data), 
and  a  sampled  sound  header.  You  can  use  this  function  to  construct  a 
SndListResource  (IV-2447)  structure  that  can  bepassedto  SndPlay  (III— 1 842)  or 
stored  as  an  '  snd  '  resource.  After  calling  this  function,  your  application  should 
place  the  sampled-sound  data  directly  after  the  sampled  sound  header  so  that,  in 
essence,  the  sampled  sound  header's  final  field  contains  the  sound  data. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

Related  Java  Methods 

qui ckti me. sound. SndHandle. SndHandl e( ) , 
qui ckti me. sound. SndHandle. setupHeader() 


SetUserDataltem 


Sets  an  item  in  a  user  data  list. 


OSErr  SetUserDataltem  ( 


UserData 
voi  d 
1  ong 
OSType 
1  ong 


theUserData , 
*data , 
size, 
udType , 
index  ); 
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theUserData 

The  user  data  list  for  this  operation.  You  obtain  this  item  reference  by  calling 
GetMovi  ellserData  (1-499),  GetTrackUserData  (1-546),  or  GetMedi  aUserData 
(1-456). 

data 

A  pointer  to  the  data  item  to  be  set  in  a  user  data  list. 

si  ze 

The  size  of  the  information  pointed  to  by  the  data  parameter. 
udType 

The  type  value  assigned  to  the  new  item, 
i  ndex 

The  item's  index  value.  This  parameter  must  specify  an  item  in  the  user  data 
list  identified  by  theUserData.  An  index  value  of  0  or  1  implies  the  first  item, 
which  is  created  if  it  doesn't  already  exist. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Movie  User  Data"  (V-2743) 

Related  Java  Methods 

qu i ckti me. std. mo vies. media. User Data. set Da taltemO 


See  Also 

For  the  corresponding  get  function,  see  GetUserData  Item  (1-548). 


SFGetFilePreview 


Displays  a  file  preview  in  an  Open  dialog  box  using  a  standard  file  reply  structure. 


void  SFGetFilePreview  ( 
Poi  nt 

ConstStr255Param 

FileFilterUPP 

short 

ConstSFTypeFistPtr 

DlgHookUPP 


where , 
prompt , 
f  i  1  eFi  1  ter 
numTypes , 
typeLi  st , 
dl gHook , 


III-1674 


Inside  QuickTime:  Functions  R-Z 


SFGetFilePreview 


SFReply  *reply  ); 

where 

The  location  of  the  upper-left  comer  of  the  dialog  box  in  global  coordinates.  If 
you  set  this  to  ( - 1  - 1 ),  the  Movie  Toolbox  centers  the  dialog  box  on  the  main 
screen.  If  you  set  it  to  ( -  2  -2 ),  the  Movie  Toolbox  centers  the  dialog  box  on  the 
screen  that  has  the  best  display  characteristics. 

prompt 

This  parameter  is  ignored;  it  is  included  for  historical  reasons  only, 
fi  1  eFi  1  ter 

Points  to  a  Fi  1  eFi  1  terProc  (III— 2082)  callback  that  filters  the  files  that  are 
displayed  to  the  user  in  the  dialog  box.  This  is  an  optional  callback  provided  by 
your  application;  if  you  don't  want  to  supply  a  filter  function,  set  this  parameter 
to  NIL.  The  function  uses  this  parameter  along  with  the  numTypes  and  type  Li  st 
parameters  to  determine  which  files  appear  in  the  dialog  box. 
numTypes 

The  number  of  file  types  in  the  array  specified  by  the  type  Li  st  parameter  (a 
number  between  1  and  4).  Set  this  parameter  to  -1  to  display  all  files. 

typeLi  st 

An  array  of  file  types  to  be  displayed  to  the  user.  This  function  only  displays 
files  whose  type  matches  an  entry  in  this  array  (unless  you  set  the  numTypes 
parameter  to  -1;  in  this  case,  the  function  displays  all  files  to  the  user), 
dl gHook 

A  pointer  to  an  Dl  gHookProc  (III— 2079)  callback.  Use  this  parameter  to  support  a 
custom  dialog  box  function  you  have  supplied.  If  you  are  not  supplying  a 
custom  dialog  box  callback,  set  this  parameter  to  NIL. 
reply 

A  pointer  to  an  SFReply  (IV-2431)  structure  that  is  to  receive  information  about 
the  user's  selection. 

Discussion 

This  function  presents  an  Open  dialog  box  to  the  user  and  allows  the  user  to  view 
file  previews  during  the  dialog.  It  automatically  converts  files  to  movies  if  your 
application  requests  movies.  If  a  file  could  be  converted  into  a  movie  file  using  a 
movie  import  component,  then  the  file  is  shown  in  the  Standard  File  dialog  box. 

Special  Considerations 

This  is  the  preferred  function  for  displaying  a  file  preview. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Functions  R-Z 


III-1675 


SFPG  etFilePrevie  w 


Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Displaying  File  Previews"  (V-2758) 


SFPGetFilePreview 


Displays  file  previews  in  an  Open  dialog  box  using  a  standard  file  reply  structure. 

void  SFPGetFilePreview  ( 

Poi  nt 

ConstStr255Param 
Fi  1  eFi  1  terUPP 
short 

ConstSFTypeListPtr 
DlgHookUPP 
SFReply 
short 

Modal Fi 1 terUPP 
where 

The  location  of  the  upper-left  corner  of  the  dialog  box  in  global  coordinates.  If 
you  set  this  to  ( - 1  - 1 ) ,  the  Movie  Toolbox  centers  the  dialog  box  on  the  main 
screen.  If  you  set  it  to  ( -  2  -  2 ) ,  the  Movie  Toolbox  centers  the  dialog  box  on  the 
screen  that  has  the  best  display  characteristics. 

prompt 

This  parameter  is  ignored;  it  is  included  for  historical  reasons  only, 
fi  1  eFi  1  ter 

Points  to  a  FileFilterProc  (III— 2082)  callback  that  filters  the  files  that  are 
displayed  to  the  user  in  the  dialog  box.  This  is  an  optional  callback  provided  by 
your  application;  if  you  don't  want  to  supply  a  filter  function,  set  this  parameter 
to  NIL.  The  function  uses  this  parameter  along  with  the  numTypes  and  typeLi  st 
parameters  to  determine  which  files  appear  in  the  dialog  box. 
numTypes 

The  number  of  file  types  in  the  array  specified  by  the  typeLi  st  parameter  (a 
number  between  1  and  4).  Set  this  parameter  to  -1  to  display  all  files. 

typeLi  st 

An  array  of  file  types  to  be  displayed  to  the  user.  SFGetFi  1  ePrevi  ew  only 
displays  files  whose  type  matches  an  entry  in  this  array  (unless  you  set  the 
numTypes  parameter  to  -1;  in  this  case,  the  function  displays  all  files  to  the  user). 


where , 
prompt , 
f  i  1  eFi  1  ter , 
numTypes , 
typeLi  st , 
dl gHook , 
*reply , 
dlglD, 

f i 1 terProc  ) ; 


III-1676 


Inside  QuickTime:  Functions  R-Z 


SGAddExtendedFrameReference 


dl gHook 

A  pointer  to  an  Dl  gHookProc  (III— 2079)  callback.  Use  this  parameter  to  support  a 
custom  dialog  box  function  you  have  supplied.  The  dialog  template's  resource 
type  must  be  set  to  '  D LOG ' ;  you  must  also  supply  an  item  list  in  a  ’  D I T L ' 
resource.  You  specify  the  dialog  template's  resource  ID  with  the  dl  gID 
parameter.  If  you  are  not  supplying  a  custom  dialog  box  callback,  set  this 
parameter  to  NIL. 
reply 

A  pointer  to  an  SFReply  (IV-2431)  structure  that  is  to  receive  information  about 
the  user's  selection. 
dlglD 

The  resource  ID  of  your  custom  dialog  template.  Use  this  parameter  to  specify 
a  custom  dialog  template  resource  that  has  a  resource  type  that  differs  from  the 
standard  value.  Set  this  parameter  to  0  to  use  the  standard  template, 
f i 1 terProc 

A  pointer  to  your  Modal  Fi  1  terProc  (III— 2098)  callback.  This  callback  gives  you 
greater  control  over  the  interface  presented  to  the  user. 

Discussion 

This  function  presents  an  Open  dialog  box  to  the  user  and  allows  the  user  to  view 
file  previews  during  the  dialog.  It  differs  from  SFGetFi  1  ePrevi  ew  (III— 1674)  in  that 
you  can  provide  a  custom  dialog  box  with  any  resource  type  and  you  can  specify  a 
modal-dialog  filter  function  that  allows  you  to  gain  greater  control  over  the  user 
interface.  This  function  automatically  converts  files  to  movies  if  your  application 
requests  movies.  If  a  file  could  be  converted  into  a  movie  file  using  a  movie  import 
component,  then  the  file  is  shown  in  the  Standard  File  dialog  box. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Displaying  File  Previews"  (V-2758) 


SGAddExtendedFrameReference 


Stores  extended  sample  references  for  a  channel  component. 

ComponentResul t  SGAddExtendedFrameReference  ( 
SeqGrabComponent  s, 

SeqGrabExtendedFramelnfoPtr  framelnfo  ); 


Inside  QuickTime:  Functions  R-Z 


III-1677 


SGAddExtendedMovieData 


s 

An  instance  of  the  sequence  grabber  component  connected  to  your  channel 
component.  The  sequence  grabber  component  provides  this  value  through 
SGIni tChannel  (III — 1751). 
f ramelnfo 

Apointer  to  a  SeqGrabExtendedFramelnfo  (IV-2429)  structure.  Your  component 
must  place  the  appropriate  information  into  this  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  differs  from  SGAddFrameReference  (III— 1681)  in  that  it  uses  a 
SeqGrabExtendedFramelnfo  (IV-2429)  structure  instead  of  a  SeqGrabFramelnfo 
(IV-2430)  structure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Utility  Functions  for  Sequence  Grabber  Channel 
Components"  (V-2833) 

See  Also 

See  SGAddFrameReference  (III — 1681). 


SGAddExtendedMovieData 


Adds  data  to  a  movie  without  writing  data  to  a  movie  file. 


ComponentResul t  SGAddExtendedMovieData  ( 


SeqGrabComponent 

SGChannel 

Ptr 

1  ong 

wi  de 

1  ong 

TimeVal ue 

short 

SGOutput 


s , 
c , 

P. 

1  en , 

*offset , 
chRefCon , 
time , 

wri teType , 

*whi chOutput  ); 


III-1678 
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SGAddExtendedMovieData 


An  instance  of  the  sequence  grabber  component  connected  to  your  channel 
component.  The  sequence  grabber  component  provides  this  value  through 
SGIni tChannel  (III — 1751). 
c 

Identifies  the  connection  to  your  channel. 

P 

The  location  of  the  data  to  be  added  to  the  movie. 

1  en 

The  number  of  bytes  of  data  to  be  added  to  the  movie, 
offset 

A  pointer  to  a  wide  integer  that  receives  the  offset  to  the  new  data  in  the  movie. 
If  the  movie  is  in  memory,  the  returned  offset  reflects  the  location  the  data  will 
have  in  the  movie  on  a  permanent  storage  device. 

chRefCon 

The  reference  constant  for  your  channel. 

ti  me 

The  time  at  which  the  frame  was  captured,  expressed  in  the  time  scale 
associated  with  your  channel, 
wri teType 

A  constant  (see  below)  that  determines  the  type  of  write  operation  to  be  used, 
whi chOutput 

The  use  of  whi  chOutput  depends  on  the  value  passed  in  the  wri  teType 
parameter.  If  wri  teType  is  seqGrabWri  teAppend  or  seqGrabWri teReserve,  the 
whichOutput  parameter  is  a  return  value  specifying  the  sequence  grabber  output 
to  which  data  was  written  or  in  which  space  was  reserved.  IfwriteTypeis 
seqGrabWri  teFi  1 1 ,  the  whichOutput  parameter  is  an  input  value  indicating 
which  sequence  grabber  output  the  data  should  be  written  to. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

writeType  Constants 

seqGrabWri teAppend 

Append  new  data  to  the  end  of  the  file.  The  sequence  grabber  sets  the  field 
referenced  by  the  offset  parameter  to  reflect  the  location  at  which  data  is 
added. 


Inside  QuickTime:  Functions  R-Z 


III-1679 


SGAddFrame 


seqGrabW rite Reserve 

Do  not  write  data  to  the  output  file,  but  reserve  space  in  that  file  for  the  amount 
of  data  specified  by  the  1  en  parameter.  The  sequence  grabber  sets  the  field 
referenced  by  the  offset  parameter  to  the  location  of  the  reserved  space. 
seqGrabWri t  e  F 1 1 1 

Write  the  data  to  the  location  specified  by  the  field  referenced  by  the  offset 
parameter.  The  sequence  grabber  sets  that  field  to  the  location  of  the  byte 
following  the  last  previously  written  byte.  Use  this  option  to  fill  space  reserved 
when  the  wri  teType  parameter  was  set  to  seqGrabWri teReserve. 

Discussion 

This  function  differs  from  SGAddMovieData  (III— 1682)  in  two  respects:  the  offset 
parameter  allows  a  64-bit  value,  and  the  whichOutput  parameter  does  not  exist  in 
SGAddMovi eData. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Utility  Functions  for  Sequence  Grabber  Channel 
Components"  (V-2833) 


SGAddFrame 


Provides  default  values  for  your  add-frame  function. 


ComponentResul t  SGAddFrame 
SGChannel 
short 
TimeVal ue 
TimeScale 

const  SGCompressInfo 


c , 

bufferNum , 
atT i me , 
seal e , 

*ci  ) ; 


The  reference  that  identifies  the  channel  for  this  operation.  The  sequence 
grabber  component  provides  this  value  to  your  add-frame  function. 
bufferNum 

Identifies  the  buffer.  The  sequence  grabber  component  provides  this  value  to 
your  add-frame  function. 


III-1680 
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SGAddFrameReference 


atT i me 

The  time  at  which  the  frame  was  captured,  in  the  time  scale  specified  by  the 
scale  parameter.  The  sequence  grabber  component  provides  this  value  to  your 
add-frame  function.  Your  add-frame  function  can  change  this  value  before 
calling  this  function.  You  can  determine  the  duration  of  a  frame  by  subtracting 
its  capture  time  from  the  capture  time  of  the  next  frame  in  the  sequence, 
scale 

The  time  scale  of  the  movie.  The  sequence  grabber  component  provides  this 
value  to  your  add-frame  function. 

ci 

A  pointer  to  a  SGCompressInfo  (IV-2432)  structure.  This  structure  contains 
information  describing  the  compression  characteristics  of  the  image  to  be 
added  to  the  movie. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  should  call  this  function  only  from  your  add-frame  function.  If  you  call  it  at  any 
other  time,  results  are  unpredictable. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


SGAddFrameReference 


Stores  sample  references  for  a  channel  component. 

ComponentResul t  SGAddFrameReference  ( 
SeqGrabComponent  s, 

SeqGrabFramelnfoPtr  framelnfo  ); 


An  instance  of  the  sequence  grabber  component  connected  to  your  channel 
component.  The  sequence  grabber  component  provides  this  value  through 
SGInitChannel  (III — 1751). 
framelnfo 

A  pointer  to  a  SeqGrabFramelnfo  (IV-2430)  structure.  Your  component  must 
completely  specify  the  reference  by  placing  the  appropriate  information  into 
the  record  referred  to  by  this  parameter. 


Inside  QuickTime:  Functions  R-Z 


III-1681 


SGAddMovieData 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Utility  Functions  for  Sequence  Grabber  Channel 
Components"  (V-2833) 


SGAddMovieData 


Lets  a  channel  component  add  data  to  a  movie. 


ComponentResul t  SGAddMovieData  ( 


SeqGrabComponent 

SGChannel 

Ptr 

1  ong 

1  ong 

1  ong 

TimeVal ue 
short 


s , 
c , 

P. 

1  en , 

*offset , 
chRefCon , 
time , 

wri teType  ) ; 


An  instance  of  the  sequence  grabber  component  connected  to  your  channel 
component.  The  sequence  grabber  component  provides  this  value  through 
SGIni tChannel  (III — 1751). 

c 

Identifies  the  connection  to  your  channel. 

P 

The  location  of  the  data  to  be  added  to  the  movie. 

1  en 

Indicates  the  number  of  bytes  of  data  to  be  added  to  the  movie, 
offset 

A  pointer  to  a  field  that  is  to  receive  the  offset  to  the  new  data  in  the  movie.  The 
sequence  grabber  component  returns  an  offset  that  is  correct  in  the  context  of 
the  movie  resource,  even  if  the  movie  is  currently  stored  in  memory.  That  is,  if 
the  movie  is  in  memory,  the  returned  offset  reflects  the  location  that  the  data 
will  have  in  a  movie  on  a  permanent  storage  device,  such  as  a  disk. 


III-1682 
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SGAddOutputDataRefToMedia 


chRefCon 

Your  channel's  reference  constant. 

ti  me 

The  time  at  which  your  channel  captured  the  frame.  This  time  value  is 
expressed  in  your  channel's  time  scale. 

wri  teType 

A  constant  (see  below)  that  determines  the  type  of  write  operation  to  be  used. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

writeType  Constants 

seqGrabWri teAppend 

Append  new  data  to  the  end  of  the  file.  The  sequence  grabber  sets  the  field 
referenced  by  the  offset  parameter  to  reflect  the  location  at  which  data  is 
added. 

seqGrabWri te Reserve 

Do  not  write  data  to  the  output  file,  but  reserve  space  in  that  file  for  the  amount 
of  data  specified  by  the  1  en  parameter.  The  sequence  grabber  sets  the  field 
referenced  by  the  offset  parameter  to  the  location  of  the  reserved  space. 

seqGrabWri teFi 1 1 

Write  the  data  to  the  location  specified  by  the  field  referenced  by  the  offset 
parameter.  The  sequence  grabber  sets  that  field  to  the  location  of  the  byte 
following  the  last  previously  written  byte.  Use  this  option  to  fill  space  reserved 
when  the  wri  teType  parameter  was  set  to  seqGrabWri  teReserve. 

Discussion 

This  function  combines  the  services  provided  by  SGWri  teMovi  eData  (III— 1824)  and 
SGAddFrameReference  (III— 1681).  Your  channel  component  should  not  write  data 
directly  to  the  movie  file;  use  this  function  instead. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Utility  Functions  for  Sequence  Grabber  Channel 
Components"  (V-2833) 


SGAddOutputDataRefToMedia 


Manages  capture  sessions  that  involve  multiple  data  references. 


Inside  QuickTime:  Functions  R-Z 


III-1683 


SGAlignChannelRect 


Component Res ul t  SGAddOutput Data  Ref ToMedi a 
SeqGrabComponent  s, 

SGOutput  sgOut, 

Media  theMedia, 

Sampl eDescri pti onHandl e  desc  ); 


( 


s 

An  instance  of  the  sequence  grabber  component  connected  to  your  channel 
component.  The  sequence  grabber  component  provides  this  value  through 
SGIni tChannel  (III — 1751). 
sgOut 

A  pointer  to  the  current  sequence  grabber  output. 
theMedi a 

The  media  for  this  operation.  Your  application  obtains  this  media  identifier 
from  such  functions  as  NewT rackMedi  a  (11-1120)  and  GetT rackMedi  a  (1-535). 

desc 

A  handle  to  a  Sampl  eDescri  pti  on  (IV-2414)  structure  that  contains  an  index, 
which  is  assigned  to  the  data  by  this  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  usually  called  from  the  SGWri  teSampl  es  (III— 1825)  function  of  a 
sequence  grabber  channel  component.  You  pass  to  it  a  sequence  grabber  output 
along  with  a  media  and  Sampl  eDescri  pti  on  (IV-2414)  structure,  and  it  adds  the  data 
reference  to  the  data  reference  list  of  the  specified  media.  It  also  updates  the  data 
reference  index  field  of  the  Sampl  eDescri  pti  on  structure  to  refer  to  the  data 
reference. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Utility  Functions  for  Sequence  Grabber  Channel 
Components"  (V-2833) 


SGAlignChannelRect 

Determines  whether  or  not  a  channel  prefers  to  draw  at  a  particular  screen  location. 

ComponentResul t  SGAlignChannelRect  ( 

SGChannel  c, 


III-1684 


Inside  QuickTime:  Functions  R-Z 


SGAppendDeviceListToMenu 


Rect  *r  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

r 

A  pointer  to  a  Rect  (IV-2399)  structure.  On  entry,  this  structure  contains 
coordinates  at  which  the  sequence  grabber  would  like  to  draw  your  captured 
video  image.  If  your  component  can  draw  more  efficiently  or  at  a  higher  frame 
rate  at  a  different  location,  update  the  contents  of  this  structure  to  reflect  where 
you  would  prefer  to  draw.  The  rectangle  will  be  passed  in  with  global,  not  local, 
coordinates. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  called  by  a  sequence  grabber  to  determine  whether  or  not  a  channel 
prefers  to  draw  at  a  particular  screen  location. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuration  Functions  for  Video  Channel 
Components"  (V-2828) 


SG  AppendDeviceListT  oMenu 


Places  a  list  of  device  names  into  a  specified  menu. 

ComponentResul t  SGAppendDeviceListToMenu  ( 
SeqGrabComponent  s, 

SGDeviceList  list, 

MenuHandle  mh  ); 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaul  t  Component  (11-1131) 
or  OpenComponent  (11-1130). 

1  i  st 

Defines  a  pointer  to  a  device  list  structure  pointer.  The  sequence  grabber 
appends  the  name  of  each  device  in  the  list  to  the  menu  specified  by  the  mh 
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III-1685 


SGChangedSource 


parameter.  If  the  sgDevi  ceNameFl  a  g Devi  ceUnavai  1  abl  e  flag  is  set  to  1  for  a  device 
in  the  list,  the  sequence  grabber  disables  the  menu  item  corresponding  to  that 
device. 

mh 

A  handle  to  the  menu  to  which  the  device  names  are  to  be  appended. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Working  With  Channel  Devices"  (V-2818) 


SGChangedSource 


Informs  the  sequence  grabber  that  a  component  is  now  using  a  different  device. 

ComponentResul t  SGChangedSource  ( 

SeqGrabComponent  s, 

SGChannel  c  ) ; 


s 

An  instance  of  the  sequence  grabber  component  connected  to  your  channel 
component.  The  sequence  grabber  component  provides  this  value  through 
SGIni tChannel  (III — 1751). 

c 

Identifies  the  connection  to  your  channel. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Utility  Functions  for  Sequence  Grabber  Channel 
Components"  (V-2833) 


SGChannelGetCodecSettings 

Gets  the  codec  settings  for  a  sequence  grabber  channel. 


III-1686 
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SGChannelGetDataSourceName 


ComponentResul t  SGChannel GetCodecSetti ngs  ( 
SGChannel  c. 

Handle  *settings  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 
setti ngs 

A  pointer  to  a  handle  that  the  codec  should  resize  and  fill  in  with  the  current 
internal  settings.  These  settings  are  codec-defined  and  usually  opaque.  Don't 
dispose  of  this  handle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

See  Also 

For  the  corresponding  set  function,  see  SGChannel  SetCodecSetti  ngs  (III— 1689).  The 
equivalent  function  for  sound  is  SoundComponentGetlnfo  (III— 1849)  with  the 
si  Decompress!  onParams  selector. 


SGChannelGetDataSourceName 


Returns  the  data  source  name  for  a  track. 

ComponentResul t  SGChannelGetDataSourceName  ( 
SGChannel  c, 

Str255  name, 

ScriptCode  *scriptTag  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

name 

A  string  that  is  to  receive  the  source  identification  information.  Set  this 
parameter  to  N I L  if  you  do  not  want  to  retrieve  the  name. 
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III-1687 


SGChannelGetRequestedDataRate 


scri ptTag 

A  field  that  is  to  receive  the  source  information's  language  code;  see 
"Localization  Codes"  (IV-2673).  Set  this  parameter  to  N I L  if  you  do  not  want 
this  information. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  allows  you  to  get  the  source  information  specified  with 
SGChannel  SetDataSourceName  (III — 1690). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Utility  Functions  for  Sequence  Grabber  Channel 
Components"  (V-2833) 

Related  Java  Methods 

qu  i  c  kti  me.  std.sg.  SGChannel.  get  Da  taSourceNamet) 


See  Also 

For  the  corresponding  set  function,  see  SGChannel  SetDataSourceName  (III— 1690). 


SGChannelGetRequestedDataRate 


Returns  the  current  maximum  data  rate  requested  for  a  channel. 

ComponentResul t  SGChannelGetRequestedDataRate  ( 

SGChannel  c, 

long  *bytesPerSecond  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 
bytesPerSecond 

Points  to  a  field  that  is  to  receive  the  maximum  data  rate  requested  by  the 
sequence  grabber  component.  This  field  is  set  to  0  if  the  sequence  grabber  has 
not  set  any  restrictions. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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S  G  ChannelPutPicture 


Discussion 

This  function  allows  the  sequence  grabber  component  to  retrieve  the  current 
maximum  data  rate  value  from  your  channel  component. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Utility  Functions  for  Sequence  Grabber  Channel 
Components"  (V-2833) 

See  Also 

For  the  corresponding  set  function,  see  SGChannel  SetRequestedDataRate  (III— 1691). 


SGChannelPutPicture 

Undocumented 

ComponentResul t  SGChannelPutPicture  ( 

SGChannel  c  ); 

c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 


SGChannelSetCodecSettings 


Sets  the  codec  settings  for  a  sequence  grabber  channel. 

ComponentResul t  SGChannelSetCodecSettings  ( 
SGChannel  c. 

Handle  settings  ); 
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III-1689 


SGChannelSetDataSourceName 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 
setti ngs 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

See  Also 

For  the  corresponding  get  function,  see  SGChannel  GetCodecSetti  ngs  (III— 1686). 


SGChannelSetDataSourceName 


Sets  the  data  source  name  for  a  track. 

ComponentResul t  SGChannelSetDataSourceName  ( 
SGChannel  c, 

ConstStr255Param  name, 

ScriptCode  scriptTag  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 

name 

A  string  that  contains  the  source  identification  information.  The  source 
information  identifies  the  source  of  the  video  data  (for  example,  a  videotape 
name). 

scri ptTag 

The  language  of  the  source  identification  information;  see  "Localization  Codes" 
(IV-2673). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  allows  you  to  set  the  source  information  for  a  sequence  grabber 
channel.  You  must  set  this  information  before  you  start  digitizing.  The  sequence 
grabber  channel  stores  this  information  in  a  timecode  track  in  the  movie  created 
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SGChannelSetRequestedDataRate 


after  the  capture  is  complete.  If  the  video  digitizer  does  not  provide  timecode 
information,  the  sequence  grabber  does  not  save  this  information. 

Special  Considerations 

This  function  is  currently  supported  only  by  video  channels. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Utility  Functions  for  Sequence  Grabber  Channel 
Components"  (V-2833) 

Related  Java  Methods 

quicktime.std.sg.SGChannel.setDataSourceNameO 


See  Also 

For  the  corresponding  get  function,  see  SGChannel  GetDataSourceName  (III— 1687). 


SGChannelSetRequestedDataRate 


Specifies  the  maximum  requested  data  rate  for  a  channel. 

ComponentResul t  SGChannelSetRequestedDataRate  ( 
SGChannel  c, 

long  bytesPerSecond  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

bytesPerSecond 

The  maximum  data  rate  requested  by  the  sequence  grabber  component,  in 
bytes  per  second.  The  sequence  grabber  component  sets  this  parameter  to  0  to 
remove  any  data-rate  restrictions. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  allows  the  sequence  grabber  component  to  specify  the  maximum  rate 
at  which  it  would  like  to  receive  data  from  your  channel  component.  The  data  rate 
supplied  by  the  sequence  grabber  component  represents  a  requested  data  rate;  your 
component  may  not  be  able  to  observe  that  rate  under  all  conditions. 
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SGCompressFrame 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Utility  Functions  for  Sequence  Grabber  Channel 
Components"  (V-2833) 

See  Also 

For  the  corresponding  get  function,  see  SGChannel  GetRequestedDataRate  (III— 1688). 


SGCompressFrame 


Provides  the  default  behavior  for  your  compress  function. 

ComponentResul t  SGCompressFrame  ( 

SGChannel  c, 

short  bufferNum  ) ; 


c 

The  reference  that  identifies  the  channel  for  this  operation.  The  sequence 
grabber  provides  this  value  to  your  compress  function. 

bufferNum 

The  buffer.  The  sequence  grabber  provides  this  value  to  your  compress 
function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

You  should  call  this  function  only  from  your  compress  function.  If  you  call  it  at  any 
other  time,  results  are  unpredictable. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 


SGCompressFrameComplete 


Provides  the  default  behavior  for  your  compress-complete  function. 

ComponentResul t  SGCompressFrameComplete  ( 

SGChannel  c, 


III-1692 
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SGDisplayCompress 


short 
Bool ean 

SGCompressInfo 


bufferNum, 
*done , 

*ci  ) ; 


c 

The  reference  that  identifies  the  channel  for  this  operation.  The  sequence 
grabber  component  provides  this  value  to  your  compress-complete  function. 
bufferNum 

Identifies  the  buffer.  The  sequence  grabber  component  provides  this  value  to 
your  compress-complete  function. 

done 

A  pointer  to  a  Bool  ean  value.  The  function  sets  this  Bool  ean  value  to  TRUE  if  the 
compression  is  complete,  or  FALSE  if  the  operation  is  incomplete.  The  sequence 
grabber  component  provides  this  pointer  to  your  compress-complete  function, 
ci 

A  pointer  to  a  SGCompressInfo  (IV-2432)  structure.  If  the  compression  is 
complete,  the  function  completely  formats  this  structure  with  information  that 
is  appropriate  to  the  frame  just  compressed.  The  sequence  grabber  component 
provides  this  pointer  to  your  compress-complete  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

You  should  call  this  function  only  from  your  compress-complete  function.  If  you 
call  it  at  any  other  time,  results  are  unpredictable. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


SGDisplayCompress 


Provides  the  default  behavior  for  your  display -compress  function. 
ComponentResul t  SGDisplayCompress  ( 


SGChannel  c, 

Ptr  dataPtr, 

ImageDescri pti onHandl e  desc, 
MatrixRecord  *mp, 

RgnHandle  clipRgn  ); 
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III-1693 


SGDisplayFrame 


c 

Identifies  the  channel  for  this  operation.  The  sequence  grabber  provides  this 
value  to  your  display-compress  function. 
dataPtr 

A  pointer  to  the  compressed  image  data.  The  sequence  grabber  provides  this 
pointer  to  your  display-compress  function. 

desc 

A  handle  to  the  ImageDescri  pti  on  (IV-2285)  structure  to  use  for  the 
decompression  operation.  The  sequence  grabber  provides  this  handle  to  your 
display-compress  function, 
mp 

A  pointer  to  a  Matri  xRecord  (IV-2304)  structure.  This  structure  contains  the 
transformation  matrix  to  use  when  displaying  the  image.  If  there  is  no  matrix 
for  the  operation,  set  this  parameter  to  NIL. 
cl i pRgn 

A  handle  to  a  MacRegi  on  (IV-2303)  structure  that  defines  the  clipping  region  for 
the  destination  image.  This  region  is  defined  in  the  destination  coordinate 
system.  If  there  is  no  clipping  region,  set  this  parameter  to  NIL. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

You  should  call  this  function  only  from  your  display -compress  function.  If  you  call 
it  at  any  other  time,  results  are  unpredictable. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


SGDisplayFrame 


Provides  the  default  behavior  for  your  display  function. 

ComponentResul t  SGDisplayFrame  ( 

SGChannel  c, 

short  bufferNum, 

const  MatrixRecord  *mp, 

RgnHandl e  cl i pRgn  ) ; 


III-1694 
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SGDisposeChannel 


c 

The  reference  that  identifies  the  channel  for  this  operation.  The  sequence 
grabber  component  provides  this  value  to  your  display  function, 
buf f erNum 

Identifies  the  buffer.  The  sequence  grabber  component  provides  this  value  to 
your  display  function. 

mp 

A  pointer  to  a  Matri  xRecord  (IV-2304)  structure  for  the  display  operation.  If 
there  is  no  matrix  for  the  operation,  set  this  parameter  to  NIL. 
cl  i  pRgn 

A  handle  to  aMac  Region  (IV-2303)  structure  that  defines  the  clipping  region  for 
the  destination  image.  This  region  is  defined  in  the  destination  coordinate 
system.  If  there  is  no  clipping  region,  set  this  parameter  to  N I L. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

You  should  call  this  function  only  from  your  display  function.  If  you  call  it  at  any 
other  time,  results  are  unpredictable. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


SGDisposeChannel 


Removes  a  channel  from  a  sequence  grabber  component. 

ComponentResul t  SGDisposeChannel  ( 

SeqGrabComponent  s, 

SGChannel  c  ); 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDef  aul  tComponent  (11-1131) 
or  OpenComponent  (11-1130). 

The  reference  that  identifies  the  channel  you  want  to  close.  You  obtain  this 
reference  from  SGNewChannel  (III— 1753). 
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SGDisposeDeviceList 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuring  Sequence  Grabber  Components"  (V-2809) 

Related  Java  Methods 

quicktime.std.sg.SequenceGrabber.disposeChannel ( ) 


SGDisposeDeviceList 


Disposes  of  a  device  list. 

ComponentResul t  SGDisposeDeviceList  ( 
SeqGrabComponent  s, 

SGDevi ceLi st  list); 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 

list 

A  pointer  to  a  pointer  to  an  SGDevi  ceLi  stRecord  (IV-2433)  structure.  The 
sequence  grabber  disposes  of  the  memory  used  by  this  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Working  With  Channel  Devices"  (V-2818) 


SGDisposeOutput 


Disposes  of  an  existing  sequence  grabber  output. 

ComponentResul t  SGDisposeOutput  ( 
SeqGrabComponent  s, 

SGOutput  sgOut  )  ; 
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SGGetAdditionalSoundRates 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaul  t  Component  (11-1131) 
or  OpenComponent  (11-1130). 
sgOut 

Identifies  the  sequence  grabber  output  for  this  operation.  You  obtain  this 
identifier  by  calling  SGNewOutput  (III— 1757). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Use  this  function  to  dispose  of  an  existing  output.  If  any  sequence  grabber  channels 
are  using  this  output,  the  sequence  grabber  component  assigns  them  to  an 
undefined  output. 

Special  Considerations 

You  cannot  dispose  of  an  output  when  the  sequence  grabber  component  is  in  record 
mode. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Outputs"  (V-2814) 

Related  Java  Methods 

qui  cktime .  std  .  sg  .  SequenceGrabber  .disposedutputO 


See  Also 

See  SGNewOutput  (III— 1757). 


SGGetAdditionalSoundRates 


Returns  the  additional  sound  sample  rates  added  to  a  specified  sequence  grabber 
sound  channel. 

ComponentResul t  SGGetAdditionalSoundRates  ( 

SGChannel  c. 

Handle  *rates  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

rates 

A  pointer  to  the  handle  where  the  list  of  additional  sample  rates  should  be 
returned.  If  no  additional  sample  rates  have  been  set,  this  function  sets  the  rates 
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SGGetAlignmentProc 


handle  to  NIL.  The  caller  of  this  routine  is  responsible  for  disposing  of  the 
returned  handle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Utility  Functions  for  Sequence  Grabber  Channel 
Components"  (V-2833) 

See  Also 

For  the  corresponding  set  function,  see  SGSetAddi  ti  onal SoundRates  (III— 1774). 


SGGetAlignmentProc 


Obtains  information  about  the  best  screen  positions  for  a  sequence  grabber's  video 
image  in  terms  of  appearance  and  maximum  performance. 

ComponentResul t  SGGetAlignmentProc  ( 

SeqGrabComponent  s, 

ICMA1 i gnmentProcRecordPtr  al i gnmentProc  ); 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  fromOpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 

al i gnmentProc 

A  pointer  to  an  ICMA1  i  gnmentProcRecord  (IV-2278)  structure.  The  sequence 
grabber  places  its  alignment  information  into  this  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Configuring  Sequence  Grabber  Components"  (V-2809) 
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SGGetBufferlnfo 


SGGetBufferlnfo 


Obtains  information  about  a  buffer  that  has  been  passed  to  a  callback  function. 


ComponentResul t  SGGetBufferlnfo  ( 


SGChannel 

short 

Pi xMapHandl e 
Rect 

GWorl  dPtr 
Rect 


c , 

bufferNum, 

*buf f erPM , 

*buf ferRect , 
*compressBuf f er , 
*compressBuf ferRect  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 
bufferNum 

Identifies  the  buffer.  The  sequence  grabber  component  provides  this  value  to 
your  callback  function, 
buf f erPM 

A  pointer  to  a  location  that  is  to  receive  a  handle  to  the  Pi  xMap  (IV-2332) 
structure  that  contains  the  image.  Note  that  this  structure  may  be  offscreen.  Do 
not  dispose  of  this  structure.  If  you  do  not  want  this  information,  set  this 
parameter  to  NIL. 

buf ferRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  is  to  receive  the  dimensions  of  the 
image's  boundary  rectangle.  If  you  do  not  want  this  information,  set  this 
parameter  to  NIL. 
compressBuf fer 

A  pointer  to  a  location  that  is  to  receive  a  pointer  to  the  filter  buffer  for  the 
image.  The  sequence  grabber  component  returns  this  information  only  if  your 
application  has  assigned  a  filter  buffer  to  this  video  channel.  You  assign  a  filter 
buffer  by  calling  SGSetCompressBuf  fer  (III— 1784).  Do  not  dispose  of  this  buffer. 
compressBuf ferRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  is  to  receive  the  dimensions  of  the 
filter  buffer  for  the  image.  The  sequence  grabber  component  returns  this 
information  only  if  your  application  has  assigned  a  filter  buffer  to  this  video 
channel.  You  assign  a  filter  buffer  by  calling  SGSetCompressBuffer  (III— 1784).  If 
you  have  not  assigned  a  filter  buffer,  the  sequence  grabber  component  returns 
an  empty  rectangle.  If  you  do  not  want  this  information,  set  this  parameter  to 
NIL. 
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SGGetChannelBounds 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


SGGetChannelBounds 


Determines  a  channel's  display  boundary  rectangle. 

ComponentResul t  SGGetChannelBounds  ( 

SGChannel  c, 

Rect  *bounds  ) ; 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 

bounds 

A  pointer  to  a  Rect  (IV-2399)  structure  that  is  to  receive  information  about  your 
channel's  display  boundary  rectangle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Configuration  Functions  for  Video  Channel 
Components"  (V-2828),  "Working  With  Channel  Characteristics"  (V-2815) 

Related  Java  Methods 

quicktime.std.sg.VisualChannel .getBoundst ) 


See  Also 

For  the  corresponding  set  function,  see  SGSetChannel  Bounds  (III— 1774). 


SGGetChannelClip 

Retrieves  a  channel's  clipping  region. 
ComponentResul t  SGGetChannelClip  ( 


III-1700 
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SGGetChannelDeviceList 


SGChannel  c, 

RgnHandle  *theClip  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 
theCl i p 

A  pointer  to  a  handle  that  is  to  receive  a  MacRegi  on  (IV-2303)  structure  that 
defines  the  clipping  region.  The  application  is  responsible  for  disposing  of  this 
handle.  If  there  is  no  clipping  region,  set  this  handle  to  N I L. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

Note  that  some  devices  may  not  support  clipping. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuration  Functions  for  All  Channel  Components" 
(V-2826),  "Working  With  Channel  Characteristics"  (V-2815) 

Related  Java  Methods 

qui cktime . qd . Regi on . f romVi deoChannel(), 
qui ckti me . std . sg . Vi sual Channel . getCl i p( ) 


See  Also 

For  the  corresponding  set  function,  see  SGSetChannel  Cl  i  p  (III— 1775). 


SGGetChannelDeviceList 


Retrieves  a  list  of  the  devices  that  are  valid  for  a  specified  channel. 

ComponentResul t  SGGetChannelDeviceList  ( 

SGChannel  c, 

long  sel  ecti  onFl  ags  , 

SGDeviceList  *list  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 


Inside  QuickTime:  Functions  R-Z 
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SGGetChannellnfo 


sel  ecti  onFl  ags 

Flags  (see  below)  that  control  the  data  you  are  to  return  for  each  device. 

list 

A  pointer  to  an  SGDevi ceLi  stRecord  (IV-2433)  structure.  The  channel  creates 
this  structure  and  returns  a  pointer  to  it  in  the  field  referred  to  by  this 
parameter.  Applications  use  SGDi  sposeDevi  ceLi  st  (III— 1696)  to  dispose  of  the 
memory  used  by  the  list. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

selectionFlags  Constants 

sg Devi ceLi stWithlcons 

If  you  set  this  flag  to  1,  the  sequence  grabber  returns  an  icon  for  each  device  in 
the  list,  in  the  icon  field.  If  you  set  this  flag  to  0,  the  sequence  grabber  sets  the 
i  con  field  to  0. 

sg Devi ceLi stDontCheckAvai lability 

If  you  set  this  flag  to  1,  the  sequence  grabber  does  not  check  the  availability  of 
each  device.  Otherwise,  the  sequence  grabber  checks  each  device's  availability, 
and  sets  the  sgDevi  ceNameFl  agDevi  ceUnavai  1  a bl  e  flag  appropriately  in  each 
SGDevi  ceName  (IV-2434)  structure  that  is  returned.  Note  that  checking  device 
availability  slows  this  function.  In  general,  however,  you  should  check 
availability  if  you  plan  to  present  a  list  of  devices  to  the  user.  Otherwise,  the 
user  may  select  a  device  that  is  unavailable. 

Discussion 

This  function  can  be  useful  for  retrieving  the  name  of  the  current  device.  Retrieve 
the  device  list  and  use  the  sel  ectedlndex  field  to  determine  which  device  is 
currently  in  use. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Managing  Channel  Devices"  (V-2828),  "Working  With 
Channel  Devices"  (V-2818) 


SGGetChannellnfo 

Determines  how  a  channel's  data  is  represented  to  the  user:  as  visual  data  or  audio 
data,  or  both. 

ComponentResul t  SGGetChannellnfo  ( 
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SGGetChannelMatrix 


SGChannel  c, 

1 ong  *channel Info  ) ; 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 
channel  Info 

A  pointer  to  a  long  integer  that  is  to  receive  channel  information  flags  (see 
below).  You  may  set  more  than  one  flag  to  1.  Set  unused  flags  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

channellnfo  Constants 

seqGrabHasBounds 

If  you  set  this  flag  to  1,  the  channel  has  a  visual  representation.  The  sequence 
grabber  component  may  call  your  SGSetChannel  Bounds  (III— 1774)  function. 

seqGrabHasVol ume 

If  you  set  this  flag  to  1,  the  channel  has  an  audio  representation.  The  sequence 
grabber  component  may  call  your  SGSetChannel  Vol  ume  (III— 1 783)  function. 
seqGrabHasDi screteSampl  es 

If  you  set  this  flag  to  1,  the  sequence  grabber  component  may  use 
SGSetChannel  MaxFrames  (III— 1777)  to  limit  the  number  of  frames  processed  in  a 
record  operation  or  the  rate  at  which  those  frames  are  processed.  If  your 
channel's  data  is  not  organized  into  frames,  set  this  flag  to  0. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Configuration  Functions  for  All  Channel  Components" 
(V-2826),  "Working  With  Channel  Characteristics"  (V-2815) 


SGGetChannelMatrix 


Retrieves  a  channel's  display  transformation  matrix. 

ComponentResul t  SGGetChannelMatrix  ( 

SGChannel  c, 

MatrixRecord  *m  ); 
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III-1703 


SGGetChannelMaxFrames 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 
m 

A  pointer  to  a  Matri  xRecord  (IV-2304)  structure.  Place  your  current  matrix 
values  into  this  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuration  Functions  for  All  Channel  Components" 
(V-2826),  "Working  With  Channel  Characteristics"  (V-2815) 

Related  Java  Methods 

quicktime.std.sg.VisualChannel .getMatrix( ) 


See  Also 

For  the  corresponding  set  function,  see  SGSetChannel  Matrix  (III— 1776). 


SGGetChannelMaxFrames 


Determines  the  number  of  frames  left  to  be  captured  from  a  specified  channel. 

ComponentResul t  SGGetChannelMaxFrames  ( 

SGChannel  c, 

1 ong  *f rameCount  ) ; 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III— 1753)  or  SGNewChannel  FromComponent  (III— 1756). 
f rameCount 

A  pointer  to  a  long  integer  that  is  to  receive  a  value  specifying  the  number  of 
frames  left  to  be  captured  during  the  preview  or  record  operation.  If  the 
returned  value  is  -1,  the  sequence  grabber  channel  component  captures  as 
many  frames  as  it  can. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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SGGetChannelPlayFlags 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuration  Functions  for  All  Channel  Components" 
(V-2826),  "Working  With  Channel  Characteristics"  (V-2815) 

See  Also 

For  the  corresponding  set  function,  see  SGSetChannel  MaxFrames  (III— 1777). 


S  G  GetChannelPlay  Flags 


Retrieves  the  playback  control  flags  that  you  set  with  SGSetChannel  PI  ayFlags 
(III— 1779). 

ComponentResul  t  SGGetChannelPlayFlags  ( 

SGChannel  c, 

long  *playFlags  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

pi  ayFl  ags 

A  pointer  to  a  long  integer  that  is  to  receive  flags  (see  below)  that  influence 
channel  playback.  Set  unused  flags  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

playFlags  Constants 

channel  PI ayNormal 

Your  channel  component  uses  its  default  playback  methodology, 
channel  PI  ayFast 

Your  channel  component  sacrifices  playback  quality  to  achieve  the  specified 
playback  rate. 

channel  PI  ay Hi ghQual i ty 

Your  channel  component  plays  the  channel's  data  at  the  highest  possible 
quality.  This  option  sacrifices  playback  rate  for  the  sake  of  image  quality.  It  may 
reduce  the  amount  of  processor  time  available  to  other  programs  in  the 
computer.  This  option  should  not  affect  the  quality  of  the  recorded  data, 
however. 

channel  PI ayAl 1  Data 

Your  channel  component  tries  to  play  all  of  the  data  it  captures,  even  the  data 
that  is  stored  in  offscreen  buffers.  This  option  is  useful  when  you  want  to  be 
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III-1705 


SGGetChannelSampleDescription 


sure  that  the  user  sees  as  much  of  the  captured  data  as  possible.  The  sequence 
grabber  component  sets  this  flag  to  1  to  play  all  the  captured  data.  The  sequence 
grabber  component  may  combine  this  flag  with  any  of  the  other  values  for  the 
pi  ay  FI  ags  parameter. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuration  Functions  for  All  Channel  Components" 

(V-2826),  "Working  With  Channel  Characteristics"  (V-2815) 

Related  Java  Methods 

quicktime.std.sg.SGChannel.getPlayFlagsO 


See  Also 

For  the  corresponding  set  function,  see  SGSetChannel  PI  ayFl  ags  (III— 1779). 


SGGetChannelSampleDescription 


Retrieves  a  channel's  sample  description  structure. 

ComponentResul t  SGGetChannelSampleDescription  ( 
SGChannel  c, 

Hand! e  sampl eDesc  ) ; 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 
sampl eDesc 

A  handle  that  is  to  receive  the  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  channel  returns  a  structure  that  is  appropriate  to  the  type  of  data  being 
captured.  For  video  channels,  the  channel  component  returns  an  ImageDescription 
(IV-2285)  structure;  for  sound  channels,  it  receives  a  SoundDescri  pti  on  (IV-2449) 
structure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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SGGetChannelSettings 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuration  Functions  for  All  Channel  Components" 
(V-2826),  "Working  With  Channel  Characteristics"  (V-2815) 


SGGetChannelSettings 


Retrieves  the  current  settings  of  a  channel  used  by  the  sequence  grabber. 

ComponentResul t  SGGetChannelSettings  ( 

SeqGrabComponent  s, 

SGChannel  c, 

UserData  *ud, 

long  flags  ); 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaul  t  Component  (11-1131) 
or  OpenComponent  (11-1130). 

c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 
ud 

On  return,  a  pointer  to  a  UserData  Record  (IV-2496)  structure  that  contains  the 
configuration  information. 

fl  ags 

Reserved  for  Apple.  Set  this  parameter  to  0. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Settings"  (V-2812) 

Related  Java  Methods 

qui cktime . std .movi es .medi a. UserData. f romSGChannel ( ) , 
qui ckti me . std . sg . SGChannel . get Sett i ngs ( ) 

See  Also 

For  the  corresponding  set  function,  see  SGSetChannel  Setti  ngs  (III— 1781). 
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SGGetChannelTimeBase 


SGGetChannelTimeBase 


Retrieves  a  reference  to  the  time  base  that  is  being  used  by  a  sequence  grabber 
channel. 

ComponentResul t  SGGetChannelTimeBase  ( 

SGChannel  c, 

TimeBase  *tb  ) ; 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 

tb 

A  pointer  to  a  time  base  identifier,  such  as  that  returned  by  NewT i  meBase 
(11-1119). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


SGGetChannelTimeScale 


Lets  the  sequence  grabber  retrieve  a  channel's  time  scale. 

ComponentResul t  SGGetChannelTimeScale  ( 

SGChannel  c, 

TimeScale  *scale  ) ; 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 

seal  e 

A  pointer  to  a  time  scale.  Your  channel  component  places  information  about  its 
time  scale  into  this  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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Discussion 

The  time  scale  you  return  typically  corresponds  to  the  time  scale  of  the  media  that 
has  been  created  by  your  channel.  Applications  may  use  this  time  scale  in  their  data 
functions. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuration  Functions  for  All  Channel  Components" 
(V-2826),  "Working  With  Channel  Characteristics"  (V-2815) 


SGGetChannelUsage 


Determines  how  the  sequence  grabber  component  is  using  a  channel. 

ComponentResul t  SGGetChannelUsage  ( 

SGChannel  c, 

long  *usage  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

usage 

A  pointer  to  a  location  that  is  to  receive  flags  (see  below)  that  specify  how  your 
channel  is  to  be  used.  You  may  set  more  than  one  of  these  flags  to  1.  Set  unused 
flags  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

usage  Constants 

seqGrabRecord 

This  flag  is  set  to  1  if  your  channel  is  being  used  for  recording. 
seqGrabPrevi ew 

This  flag  is  set  to  1  if  your  channel  is  being  used  for  previewing. 
seqGrabPl ay Du ri ng Record 

This  flag  is  set  to  1  if  your  channel  plays  its  captured  data  during  a  record 
operation. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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III-1709 


SGGetChannelVolume 


Programming  Info 

C  interface  file:  QuickTimeComponents.h 

Programming  summary:  "Configuration  Functions  for  All  Channel  Components" 
(V-2826),  "Working  With  Channel  Characteristics"  (V-2815) 

Related  Java  Methods 

quicktime.std.sg.SGChannel .getUsage( ) 


See  Also 

For  the  corresponding  set  function,  see  SGSetChannel  Usage  (III— 1782). 


S  G  GetChannel  V  olume 


Determines  a  channel's  sound  volume  setting. 

ComponentResul t  SGGetChannelVolume  ( 
SGChannel  c, 

short  *vol ume  ) ; 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 

vol ume 

A  pointer  to  an  integer  that  is  to  receive  the  volume  setting  of  the  channel 
represented  as  a  16-bit,  fixed-point  number.  The  high-order  8  bits  contain  the 
integer  part  of  the  value;  the  low-order  8  bits  contain  the  fractional  part. 
Volume  values  range  from  -1.0  to  1.0.  Negative  values  play  no  sound  but 
preserve  the  absolute  value  of  the  volume  setting. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuration  Functions  for  Sound  Channel 
Components"  (V-2831),  "Working  With  Channel  Characteristics"  (V-2815) 

Related  Java  Methods 

quicktime.std.sg.AudioChannel.getVol ume( ) 


See  Also 

For  the  corresponding  set  function,  see  SGSetChannel  Vol  ume  (III— 1783). 
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SGGetCompressBuffer 


SGGetCompressBuffer 


Returns  information  about  the  filter  buffer  established  for  a  video  channel. 

ComponentResul t  SGGetCompressBuffer  ( 

SGChannel  c, 

short  *depth, 

Rect  *compressSi ze  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 
depth 

A  pointer  to  a  field  that  is  to  receive  the  pixel  depth  of  the  filter  buffer.  If  your 
component  is  not  filtering  the  input  video  data,  set  the  returned  value  to  0. 
compressSi ze 

A  pointer  to  a  Rect  (IV-2399)  structure  that  is  to  receive  the  dimensions  of  the 
filter  buffer.  If  your  component  is  not  filtering  the  input  video  data,  return  an 
empty  rectangle  (all  coordinates  set  to  0). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuration  Functions  for  Video  Channel 
Components"  (V-2828),  "Working  With  Video  Channels"  (V-2819) 

See  Also 

For  the  corresponding  set  function,  see  SGSetCompressBuf  f  er  (III— 1784). 


SGGetDataOutput 


Determines  the  movie  file  that  is  currently  assigned  to  a  sequence  grabber 
component  and  the  control  flags  that  would  govern  a  record  operation. 

ComponentResul t  SGGetDataOutput  ( 

SeqGrabComponent  s, 

FSSpec  *movieFile, 

long  *whereFlags  ); 


Inside  QuickTime:  Functions  R-Z 
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SGGetDataOutput 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 
movi  eFi  1  e 

A  pointer  to  an  FSSpec  (IV-2262)  structure  that  is  to  receive  information  about 
the  movie  file  for  this  record  operation. 

whereFl  ags 

A  pointer  to  a  long  integer  that  is  to  receive  flags  (see  below)  that  control  the 
record  operation. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

whereFlags  Constants 

seqGrabToDi sk 

Instructs  the  sequence  grabber  component  to  write  the  recorded  data  to  a 
QuickTime  movie  in  the  movie  file  specified  by  the  movi  eFi  1  e  parameter.  If  this 
flag  is  set  to  1,  the  sequence  grabber  writes  the  data  to  the  file  as  the  data  is 
recorded. 
seqGrabToMemory 

Instructs  the  sequence  grabber  component  to  store  the  recorded  data  in 
memory  until  the  recording  process  is  complete.  The  sequence  grabber  then 
writes  the  recorded  data  to  the  movie  file  specified  by  the  mo v i  e  Fi  1  e  parameter. 
This  technique  provides  better  performance  than  recording  directly  to  the 
movie  file,  but  it  limits  the  amount  of  data  you  can  record.  If  this  flag  is  set  to  1, 
the  sequence  grabber  component  is  recording  to  memory. 

seqGrabDontllseTempMemory 

Prevents  the  sequence  grabber  component  from  using  temporary  memory 
during  the  record  operation.  By  default,  the  sequence  grabber  component  and 
its  channel  components  use  as  much  temporary  memory  as  necessary  to 
perform  the  record  operation.  If  this  flag  is  set  to  1,  the  sequence  grabber 
component  and  its  channel  components  do  not  use  temporary  memory. 
seqGrabAppendToFi 1 e 

Directs  the  sequence  grabber  component  to  add  the  recorded  data  to  the  data 
fork  of  the  movie  file  specified  by  the  movi  eFi  1  e  parameter.  By  default,  the 
sequence  grabber  component  deletes  the  movie  file  and  creates  a  new  file 
containing  one  movie  and  its  movie  resource.  If  this  flag  is  set  to  1,  the  sequence 
grabber  component  appends  the  recorded  data  to  the  data  fork  of  the  movie  file 
and  creates  a  new  movie  resource  in  that  file. 


III-1712 


Inside  QuickTime:  Functions  R-Z 


SGGetDataOutputStorageSpaceRemaining 


seqGrabDontAddMovi e Resource 

Prevents  the  sequence  grabber  component  from  adding  the  new  movie 
resource  to  the  movie  file  specified  by  the  movi  eFi  1  e  parameter.  By  default,  the 
sequence  grabber  component  creates  a  new  movie  resource  and  adds  that 
resource  to  the  movie  file.  If  this  flag  is  set  to  1,  the  sequence  grabber 
component  does  not  add  the  movie  resource  to  the  movie  file.  You  are  then 
responsible  for  adding  the  resource  to  a  file,  if  you  so  desire 
seqGrabDontMakeMovi e 

Prevents  the  sequence  grabber  component  from  creating  a  movie.  By  default, 
the  sequence  grabber  component  creates  a  new  movie  resource  and  adds  the 
captured  data  to  that  movie.  If  this  flag  is  set  to  1,  the  sequence  grabber  still  calls 
your  data  function,  but  does  not  write  any  data  to  the  movie  file. 

Discussion 

You  set  the  characteristics  returned  by  this  function  by  calling  SGSetDataOutput 
(III— 1785).  If  you  have  not  set  these  characteristics  before  calling  this  function,  the 
returned  data  is  meaningless. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuring  Sequence  Grabber  Components"  (V-2809) 

Related  Java  Methods 

qui cktime . i o . QTFi 1 e . f romSequenceGrabber( ) , 

qui cktime . std . sg . SequenceGrabber . getDataOutputFileO, 

qui  cktime .  std  .  sg  .  SequenceGrabber .  getDataOutputFlagsO 


See  Also 

See  SGSetDataOutput  (III— 1785). 


SGGetDataOutputStorageSpaceRemaining 


Returns  the  amount  of  space  remaining  in  the  data  reference  associated  with  an 
output. 

ComponentResul t  SGGetDataOutputStorageSpaceRemai ni ng  ( 

SeqGrabComponent  s, 

SGOutput  sgOut, 

unsigned  long  *space  ); 


Inside  QuickTime:  Functions  R-Z 


III-1713 


SGGetDataOutputStorageSpaceRemaining64 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 
sgOut 

Identifies  the  sequence  grabber  output  for  this  operation.  You  obtain  this 
identifier  by  calling  SGNewOutput  (III— 1757). 

space 

A  pointer  to  an  unsigned  long  integer,  where  the  sequence  grabber  component 
returns  a  value  that  indicates  the  number  of  bytes  of  space  remaining  in  the 
data  reference  associated  with  the  output. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Use  this  function  in  place  of  SGGetStorageSpaceRemai  ni  ng  (III— 1736)  in  cases  where 
you  are  working  with  more  than  one  output. 

Version  Notes 

A  sequence  grabber  output  ties  a  sequence  grabber  channel  to  a  specified  data 
reference  for  the  output  of  captured  data.  If  you  are  capturing  to  a  single  movie  file, 
you  can  continue  to  use  SGSetDataOutput  (III— 1 785)  or  SGSetDataRef  (III— 1787)  to 
specify  the  sequence  grabber's  destination.  However,  if  you  want  to  capture  movie 
data  into  several  different  files  or  data  references,  you  must  use  sequence  grabber 
outputs  to  do  so.  Even  if  you  are  using  outputs,  you  must  still  use  SGSetDataOutput 
or  SGSetDataRef  to  identify  where  the  sequence  grabber  should  create  the  movie 
resource.  You  are  responsible  for  creating  outputs,  assigning  them  to  sequence 
grabber  channels,  and  disposing  of  them  when  you  are  done. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Outputs"  (V-2814) 

Related  Java  Methods 

quicktime.std.sg.SGOutput. getDataStorageSpaceRemai n 1 n  g ( ) 


SGGetDataOutputStorageSpaceRemaining64 


Provides  a  64-bit  version  of  SGGetDataOutputStorageSpaceRemai  ni  ng  (III— 1713). 

ComponentResul t  SGGetDataOutputStorageSpaceRemai ni ng64  ( 
SeqGrabComponent  s, 

SGOutput  sgOut, 


III-1714 


Inside  QuickTime:  Functions  R-Z 


SGGetDataRate 


wi  de 


*space  ); 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaul  t  Component  (11-1131) 
or  OpenComponent  (11-1130). 

sgOut 

Identifies  the  sequence  grabber  output  for  this  operation.  You  obtain  this 
identifier  by  calling  SGNewOutput  (III— 1757). 
space 

A  pointer  to  a  64-bit  wide  integer,  where  the  sequence  grabber  component 
returns  a  value  that  indicates  the  number  of  bytes  of  space  remaining  in  the 
data  reference  associated  with  the  output. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Outputs"  (V-2814) 

See  Also 

For  further  information,  see  SGGetDataOutputStorageSpaceRemai  ni  ng  (III— 1713). 


SGGetDataRate 


Determines  for  a  sequence  grabber  how  much  recording  time  is  left. 

ComponentResul t  SGGetDataRate  ( 

SGChannel  c, 

long  *bytesPerSecond  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

bytesPerSecond 

A  pointer  to  a  long  integer  that  is  to  receive  a  value  indicating  the  number  of 
bytes  your  component  is  recording  per  second.  Your  component  calculates  this 
value  based  on  its  current  operational  parameters. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Inside  QuickTime:  Functions  R-Z 


III-1715 


SGGetDataRef 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuration  Functions  for  All  Channel  Components" 
(V-2826) 

SGGetDataRef 


Determines  the  data  reference  currently  assigned  to  a  sequence  grabber  component 
and  the  control  flags  that  would  govern  a  record  operation. 

ComponentResul t  SGGetDataRef  ( 

SeqGrabComponent  s, 

Handle  *dataRef, 

OSType  *dataRefType , 

1  ong  *whereFl ags  ) ; 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 
dataRef 

A  pointer  to  a  handle  that  is  to  receive  the  information  that  identifies  the 
destination  container. 

dataRefType 

A  pointer  to  a  field  that  is  to  receive  the  type  of  data  reference. 
whereFl  ags 

A  pointer  to  a  long  integer  that  is  to  receive  flags  (see  below)  that  control  the 
record  operation. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

whereFlags  Constants 

seqGrabToDi sk 

Instructs  the  sequence  grabber  component  to  write  the  recorded  data  to  a 
QuickTime  movie  in  the  movie  file  specified  by  the  movi  eFi  1  e  parameter.  If  this 
flag  is  set  to  1,  the  sequence  grabber  writes  the  data  to  the  file  as  the  data  is 
recorded. 


III-1716 


Inside  QuickTime:  Functions  R-Z 


SGGetDataRef 


seqGrabToMemory 

Instructs  the  sequence  grabber  component  to  store  the  recorded  data  in 
memory  until  the  recording  process  is  complete.  The  sequence  grabber  then 
writes  the  recorded  data  to  the  movie  file  specified  by  the  mov  i  eFi  1  e  parameter. 
This  technique  provides  better  performance  than  recording  directly  to  the 
movie  file,  but  it  limits  the  amount  of  data  you  can  record.  If  this  flag  is  set  to  1, 
the  sequence  grabber  component  is  recording  to  memory. 
seqGrabDontUseTempMemory 

Prevents  the  sequence  grabber  component  from  using  temporary  memory 
during  the  record  operation.  By  default,  the  sequence  grabber  component  and 
its  channel  components  use  as  much  temporary  memory  as  necessary  to 
perform  the  record  operation.  If  this  flag  is  set  to  1,  the  sequence  grabber 
component  and  its  channel  components  do  not  use  temporary  memory. 

seqGrabAppendToFi 1 e 

Directs  the  sequence  grabber  component  to  add  the  recorded  data  to  the  data 
fork  of  the  movie  file  specified  by  the  movi  eFi  1  e  parameter.  By  default,  the 
sequence  grabber  component  deletes  the  movie  file  and  creates  a  new  file 
containing  one  movie  and  its  movie  resource.  If  this  flag  is  set  to  1,  the  sequence 
grabber  component  appends  the  recorded  data  to  the  data  fork  of  the  movie  file 
and  creates  a  new  movie  resource  in  that  file. 
seqGrabDontAddMovi e Resource 

Prevents  the  sequence  grabber  component  from  adding  the  new  movie 
resource  to  the  movie  file  specified  by  the  movi  eFi  1  e  parameter.  By  default,  the 
sequence  grabber  component  creates  a  new  movie  resource  and  adds  that 
resource  to  the  movie  file.  If  this  flag  is  set  to  1,  the  sequence  grabber 
component  does  not  add  the  movie  resource  to  the  movie  file.  You  are  then 
responsible  for  adding  the  resource  to  a  file,  if  you  so  desire 
seqGrabDontMakeMovi e 

Prevents  the  sequence  grabber  component  from  creating  a  movie.  By  default, 
the  sequence  grabber  component  creates  a  new  movie  resource  and  adds  the 
captured  data  to  that  movie.  If  this  flag  is  set  to  1,  the  sequence  grabber  still  calls 
your  data  function,  but  does  not  write  any  data  to  the  movie  file. 

Discussion 

This  function  allows  you  to  determine  the  data  reference  that  is  currently  assigned 
to  a  sequence  grabber  component  and  the  control  flags  that  would  govern  a  record 
operation.  You  set  these  characteristics  by  calling  SGSetDataRef  (III— 1787).  If  you 
have  not  set  these  characteristics  before  calling  this  function,  the  returned  data  is 
meaningless. 


Inside  QuickTime:  Functions  R-Z 


III-1717 


SGGetFlags 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuring  Sequence  Grabber  Components"  (V-2809) 

Related  Java  Methods 

quicktime.std.sg.SequenceGrabber.getDataRefO, 

quicktime.std.sg.SequenceGrabber.getDataRefFlagsO, 

qui ckti me . std .movi es .  medi a . Data  Ref . f romSequenceGrabber ( ) 

See  Also 

For  the  corresponding  set  function,  see  SGSetDataRef  (III— 1787). 


SGGetFlags 


Retrieves  a  sequence  grabber's  control  flags. 

ComponentResul t  SGGetFlags  ( 
SeqGrabComponent  s, 

1 ong  *sgFl ags  ) ; 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDef  aul  t Component  (11-1131) 
or  OpenComponent  (11-1130). 
sgFl  ags 

A  pointer  to  a  long  integer  that  is  to  receive  the  control  flag  (see  below)  for  the 
current  operation. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

sgFlags  Constant 

sgFlagControlledGrab 

Informs  the  sequence  grabber  component  that  you  are  working  with  a 
frame-addressable  device  to  perform  a  controlled  record  operation.  The 
sequence  grabber  and  its  channel  components  optimize  their  operation  for  this 
situation.  This  flag  allows  the  sequence  grabber  component  to  trade  off  speed 
and  quality.  This  flag  is  set  to  1  if  you  are  performing  a  controlled  grab  using  a 
frame-addressable  source  device. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


III-1718 
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SGGetFrameRate 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Characteristics" 
(V-2813) 

See  Also 

For  the  corresponding  set  function,  see  SGSetFl  ags  (III— 1789). 


SGGetFrameRate 


Retrieves  a  video  channel's  frame  rate  for  recording. 

ComponentResul t  SGGetFrameRate  ( 

SGChannel  c. 

Fixed  *frameRate  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

f rameRate 

A  pointer  to  a  field  to  receive  the  current  frame  rate. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Configuration  Functions  for  Video  Channel 
Components"  (V-2828),  "Working  With  Video  Channels"  (V-2819) 

See  Also 

For  the  corresponding  set  function,  see  SGSetFrameRate  (III— 1792). 


SGGetGWorld 


Determines  the  graphics  port  and  device  for  a  sequence  grabber  component. 

ComponentResul t  SGGetGWorld  ( 

SeqGrabComponent  s, 

CGrafPtr  *gp, 

GDHandle  *gd  ); 


Inside  QuickTime:  Functions  R-Z 


III-1719 


SGGetlndChannel 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 

9P 

A  pointer  to  a  location  that  is  to  receive  a  pointer  to  the  destination  graphics 
port.  Set  this  parameter  to  N I L  if  you  are  not  interested  in  this  information, 
gd 

A  pointer  to  a  location  that  is  to  receive  a  handle  to  the  destination  graphics 
device.  Set  this  parameter  to  N I L  if  you  are  not  interested  in  this  information. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuring  Sequence  Grabber  Components"  (V-2809) 

Related  Java  Methods 

qui ckti me . qd . QDGraphl cs . f romSequenceGrabber ( ) , 
quicktime.qd.GDevice.fromSequenceGrabbert ) , 
quicktime.std.sg.SequenceGrabber.getGWorldO, 
quicktime.std.sg.SequenceGrabber.getGWorldDevicet) 


See  Also 

For  the  corresponding  set  function,  see  SGSetGWorl  d  (III— 1792). 


SGGetlndChannel 


Collects  information  about  all  of  the  channel  components  currently  in  use  by  a 
sequence  grabber  component. 


ComponentResul t  SGGetlndChannel  ( 

SeqGrabComponent  s, 

short  index, 

SGChannel  *ref, 

OSType  *chanType 


) : 


III-1720 


Inside  QuickTime:  Functions  R-Z 


SGGetlnstrument 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaul  t  Component  (11-1131) 
or  OpenComponent  (11-1130). 
i  ndex 

Specifies  an  index  value  that  identifies  the  channel  to  be  queried.  The  first 
channel  has  an  index  value  of  1. 

ref 

A  pointer  to  a  field  to  receive  a  value  identifying  your  connection  to  the 
channel.  If  you  do  not  want  to  receive  this  information,  set  this  parameter  to 
NIL. 
chanType 

A  pointer  to  a  field  to  receive  the  channel's  subtype  value  (see  below).  This 
value  indicates  the  media  type  supported  by  the  channel  component. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

chanType  Constants 

Vi deoMedi aType 
Video  channel. 

SoundMedi aType 

Sound  channel. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuring  Sequence  Grabber  Components"  (V-2809) 

Related  Java  Methods 

qui cktime . std . sg . SequenceGrabber . getlndChannelTypeO, 
qui  cktime .  std  .  sg  .  SequenceGrabber .  getlndChannelO 


SGGetlnstrument 


Gets  a  tone  description  for  a  music  sequence  grabber  channel. 

ComponentResul t  SGGetlnstrument  ( 

SGChannel  c, 

ToneDescri pti on  *td  ); 


Inside  QuickTime:  Functions  R-Z 


III-1721 


SGGetLastMovieResID 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 
td 

Pointer  to  a  ToneDescri  pti  on  (IV-2487)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Related  Java  Methods 

quicktime.std.sg.SGMusicChannel. get  Instrument ( ) 

See  Also 

For  the  corresponding  set  function,  see  SGSetlnstrument  (III— 1794). 


SGGetLastMovieResID 


Retrieves  the  last  resource  ID  used  by  the  sequence  grabber  component. 

ComponentResul t  SGGetLastMovieResID  ( 

SeqGrabComponent  s, 

short  *resID  ); 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  fromOpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 
resID 

A  pointer  to  an  integer  that  is  to  receive  the  resource  ID  the  sequence  grabber 
assigned  to  the  movie  resource  it  just  created. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Controlling  Sequence  Grabber  Components"  (V-2811) 


III-1722 
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SGGetMaximumRecordTime 


SGGetMaximumRecordTime 


Determines  the  time  limit  you  have  set  for  a  record  operation. 

ComponentResul t  SGGetMaximumRecordTime  ( 

SeqGrabComponent  s, 

unsigned  long  *ticks  ); 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaul  t  Component  (11-1131) 
or  OpenComponent  (11-1130). 

ti  cks 

A  pointer  to  a  long  integer  that  is  to  receive  a  value  indicating  the  maximum 
duration  for  the  record  operation,  in  system  ticks  (sixtieths  of  a  second).  A 
value  of  0  indicates  that  there  is  no  time  limit. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Characteristics" 
(V-2813) 

Related  Java  Methods 

qui cktime . std . sg . SequenceGrabber . getMaxi mumRecordTi me( ) 


See  Also 

For  the  corresponding  set  function,  see  SGSetMaxi  mumRecordT i  me  (III— 1796). 


SGGetMode 


Determines  whether  a  sequence  grabber  component  is  in  preview  mode  or  record 
mode. 

ComponentResul t  SGGetMode  ( 

SeqGrabComponent  s. 

Boolean  *previ ewMode , 

Boolean  *recordMode  ); 


Inside  QuickTime:  Functions  R-Z 


III-1723 


SGGetMovie 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 
previ ewMode 

A  pointer  toaBoolean.  The  sequence  grabber  component  sets  this  field  to  TRUE 
if  the  component  is  in  preview  mode. 

recordMode 

A  pointer  toaBoolean.  The  sequence  grabber  component  sets  this  field  to  TRUE 
if  the  component  is  in  record  mode. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Sequence  Grabber  Components"  (V-2811) 

Related  Java  Methods 

quicktime.std.sg.SequenceGrabber.isPrevi ewMode ( ) , 
quicktime.std.sg.SequenceGrabber.isRecordModeO 


SGGetMovie 


Returns  a  reference  to  the  movie  that  contains  the  data  collected  during  a  record 
operation. 

Movie  SGGetMovie  ( 

SeqGrabComponent  s  ) ; 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  fromOpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 

function  result  A  movie  identifier,  such  as  that  returned  from  NewMovi  e  (11-1069). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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SGGetNextExtendedFrameReference 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Controlling  Sequence  Grabber  Components"  (V-2811) 

Related  Java  Methods 

qui cktime . std .movi es . Movi e . f romSequenceGrabberl ) , 
qui cktime . std . sg . SequenceGrabber . getMovi e( ) 


SGGetNextExtendedFrameReference 


Allows  a  channel  component  to  retrieve  the  sample  references  stored  previously  by 
SGAddExtendedMovi eData  (III — 1678)  or  SGAddExtendedFrameReference  (III — 1677). 

ComponentResul t  SGGetNextExtendedFrameReference  ( 

SeqGrabComponent  s, 

SeqGrabExtended Frame  Inf oPtr  f ramelnf o , 

TimeValue  *f rameDurati on  , 

long  *frameNumber  ); 


An  instance  of  the  sequence  grabber  component  connected  to  your  channel 
component.  The  sequence  grabber  component  provides  this  value  through 
SGIni tChannel  (III — 1751). 
f ramelnfo 

Apointer  to  a  SeqGrabExtendedFramelnfo  (IV-2429)  structure.  Your  component 
must  place  the  appropriate  information  into  this  structure. 

f rameDurati on 

A  pointer  to  a  time  value.  The  sequence  grabber  component  calculates  the 
duration  of  the  specified  frame  and  returns  that  duration  in  this  structure.  The 
sequence  grabber  component  cannot  calculate  the  duration  of  the  last  frame  in 
a  sequence.  For  the  last  frame,  the  time  value  is  set  to  -1. 

f rameNumber 

A  pointer  to  a  long  integer  representing  the  frame  number.  Frame  numbers 
need  not  be  sequential,  and  need  not  start  at  0.  To  retrieve  information  about 
the  first  frame  in  a  movie,  set  the  integer  to  -1. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  channel  component  can  process  frame  references  sequentially  or  randomly. 
You  can  specify  any  relative  frame  for  which  you  want  to  retrieve  information. 
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III-1725 


SGGetNextFrameReference 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Utility  Functions  for  Sequence  Grabber  Channel 
Components"  (V-2833) 

See  Also 

See  SGGetNextFrameReference  (III— 1726).  This  function  differs  from 
SGGetNextFrameReference  in  that  it  fills  out  a  SeqGrabExtendedFramelnfo  (IV-2429) 
structure  instead  of  a  SeqGrabFramelnfo  (IV-2430)  structure. 


SGGetNextFrameReference 


Lets  a  channel  component  retrieve  the  sample  references  that  were  stored  by  calling 
SGAddMovi  eData  (III — 1682)  or  SGAddFrameReference  (III — 1681). 

ComponentResul t  SGGetNextFrameReference  ( 

SeqGrabComponent  s, 

SeqGrabFramelnfoPtr  framelnfo, 

Time Value  *frame Duration, 

1  ong  *f rameNumber  ) ; 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 

framelnfo 

A  pointer  to  a  SeqGrabFramelnfo  (IV-2430)  structure.  Your  component  must 
identify  itself  to  the  sequence  grabber  component  by  setting  the  frameChannel 
field  of  this  structure  to  the  component  instance  that  identifies  the  current 
connection  to  your  channel.  You  get  this  value  from  SGNewChannel  (III— 1 753)  or 
SGNewChannel  FromComponent  (III— 1756).  The  sequence  grabber  component  then 
returns  information  about  the  specified  frame  in  the  remaining  fields  of  this 
structure. 

f rameDurati on 

A  pointer  to  a  time  value.  The  sequence  grabber  component  calculates  the 
duration  of  the  specified  frame  and  returns  that  duration  in  the  structure 
referred  to  by  this  parameter.  The  sequence  grabber  component  cannot 
calculate  the  duration  of  the  last  frame  in  a  sequence.  In  this  case,  the  sequence 
grabber  component  sets  the  returned  time  value  to  -1. 


III-1726 
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SGGetOutputDataReference 


f rameNumber 

A  pointer  to  a  long  integer.  Your  channel  component  specifies  the  frame 
number  corresponding  to  the  frame  about  which  you  want  to  retrieve 
information.  Frames  are  numbered  starting  at  0.  However,  frame  numbers 
need  not  start  at  0,  and  they  need  not  be  sequential.  Set  the  integer  to  -1  to 
retrieve  information  about  the  first  frame  in  a  movie. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui ckTi  meComponents  .  h 

Programming  summary:  "Utility  Functions  for  Sequence  Grabber  Channel 
Components"  (V-2833) 


SGGetOutputDataReference 


Returns  information  about  the  data  reference  associated  with  the  specified  sequence 
grabber  output. 

ComponentResul t  SGGetOutputDataReference  ( 

SeqGrabComponent  s, 

SGOutput  sgOut, 

Handle  *dataRef, 

OSType  *dataRefType  ); 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaul  t  Component  (11-1131) 
or  OpenComponent  (11-1130). 

sgOut 

Identifies  the  sequence  grabber  output  for  this  operation.  You  obtain  this 
identifier  by  calling  SGNewOutput  (III— 1757). 
dataRef 

A  pointer  to  the  handle  in  which  the  data  reference  is  returned.  If  you  do  not 
need  the  data  reference,  set  this  parameter  to  N I L. 

dataRefType 

A  pointer  in  which  the  type  of  the  data  reference  is  returned.  If  you  do  not  need 
this  information,  set  this  parameter  to  NIL. 


Inside  QuickTime:  Functions  R-Z 


III-1727 


SGGetOutputMaximumOffset 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  caller  is  responsible  for  disposing  of  the  returned  handle. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Outputs"  (V-2814) 

Related  Java  Methods 

qu i c kt i me. std.sg.SGOutput. get Data  Reference!) 


SGGetOutputMaximumOffset 


Returns  the  maximum  offset  for  data  written  to  the  specified  sequence  grabber 
output. 

ComponentResul t  SGGetOutputMaximumOffset  ( 

SeqGrabComponent  s, 

SGOutput  sgOut, 

wi  de  *maxOffset  ) ; 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 

sgOut 

Identifies  the  current  sequence  grabber  output.  You  obtain  this  identifier  by 
calling  SGNewOutput  (III— 1757). 

maxOffset 

A  pointer  to  the  value  of  the  maximum  offset  for  data  written  to  this  output. 
This  value  is  initialized  to  ( 2 A 32-1 )  on  systems  with  a  32-bit  file  system,  and 
( 2A64- 1 )  on  systems  with  a  64-bit  file  system. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Outputs"  (V-2814) 


III-1728 
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SGGetOutputNextOutput 


Related  Java  Methods 

qui cktime . std . sg . SGOutput . getMaxi mumOf f set( ) 


See  Also 

For  the  corresponding  set  function,  see  SGSetOutputMaxi  mumOf  f  set  (III— 1799). 


SGGetOutputNextOutput 


Returns  the  next  sequence  grabber  output  for  the  specified  output. 

ComponentResul t  SGGetOutputNextOutput  ( 

SeqGrabComponent  s, 

SGOutput  sgOut, 

SGOutput  *nextOut  ); 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaul  t  Component  (11-1131) 
or  OpenComponent  (11-1130). 

sgOut 

Identifies  the  current  sequence  grabber  output.  You  obtain  this  identifier  by 
calling  SGNewOutput  (III— 1757). 
nextOut 

A  pointer  to  the  next  output  to  be  used.  If  there  is  no  next  output,  this  value  is 
NIL. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Outputs"  (V-2814) 

Related  Java  Methods 

qui cktime . std . sg . SGOutput . getNextOutput( ) 


See  Also 

For  the  corresponding  set  function,  see  SGSetOutputNextOutput  (III— 1800). 
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SGGetPause 


SGGetPause 


Determines  whether  the  sequence  grabber  is  paused. 

ComponentResul t  SGGetPause  ( 

SeqGrabComponent  s, 

Byte  *paused  ) ; 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  fromOpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 

paused 

A  pointer  to  a  field  that  is  to  receive  a  constant  (see  below)  that  indicates 
whether  the  sequence  grabber  is  currently  paused. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

paused  Constants 

seqGrabtlnpause 

The  sequence  grabber  is  not  paused. 
seqGrabPause 

The  sequence  grabber  is  paused;  all  channels  are  stopped. 
seqGrabPauseForMenu 

The  sequence  grabber  is  paused  in  order  to  display  a  menu;  some  or  all  of  the 
channels  may  be  stopped. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Sequence  Grabber  Components"  (V-2811) 

Related  Java  Methods 

quicktime.std.sg.SequenceGrabber.getPauset) 


SGGetPreferredPacketSize 

Returns  the  preferred  packet  size  for  the  sequence  grabber  component. 

ComponentResul t  SGGetPreferredPacketSize  ( 

SGChannel  c, 


III-1730 
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SGGetSettings 


long  *preferredPacketSizeInBytes  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

preferredPacketSi zelnBytes 

The  preferred  packet  size  in  bytes. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

SGGetPreferredPacketSi  ze  was  added  in  QuickTime  2.5  to  support  video 
conferencing  applications. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Utility  Functions  for  Sequence  Grabber  Channel 
Components"  (V-2833) 

See  Also 

For  the  corresponding  set  function,  see  SGSetPreferredPacketSi  ze  (III— 1801). 


SGGetSettings 


Retrieves  the  current  settings  of  all  channels  used  by  the  sequence  grabber. 

ComponentResul t  SGGetSettings  ( 

SeqGrabComponent  s, 

UserData  *ud, 

long  flags  ); 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaul  t  Component  (11-1131) 
or  OpenComponent  (11-1130). 

ud 

A  pointer  to  a  space  where  the  sequence  grabber  returns  a  pointer  to  a 
UserData  Record  (IV-2496)  structure  that  contains  the  configuration  information. 
Your  application  is  responsible  for  disposing  of  this  structure  when  it  is  done 
with  it. 

fl  ags 

Reserved  for  Apple.  Set  this  parameter  to  0. 
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SGGetSoundlnputDriver 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Settings"  (V-2812) 

Related  Java  Methods 

qu i c kti me. std. mo vies. media. User Data . f romSequenceGrabber ( ) , 
quicktime.std.sg.SequenceGrabber.getSettingst) 


See  Also 

For  the  corresponding  set  function,  see  SGSetSetti  ngs  (III— 1801). 


SGGetSoundlnputDriver 

Determines  the  sound  input  device  currently  in  use  by  a  sound  channel  component. 

long  SGGetSoundlnputDriver  ( 

SGChannel  c  ) ; 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 

function  result  A  reference  to  the  sound  input  device.  If  your  sound  channel  is  not 
using  a  sound  input  device,  returns  NIL. 

Discussion 

You  may  want  to  gain  access  to  the  sound  input  device  if  you  want  to  change  the 
device's  configuration. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Configuration  Functions  for  Sound  Channel 
Components"  (V-2831),  "Working  With  Sound  Channels"  (V-2821) 

Related  Java  Methods 

quicktime.std.sg.SGSoundChannel .getlnputDrivert ) , 
qu i c kti me. sound. SPB Device . f romSoundChannel ( ) 


III-1732 
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S  G  G  et  S  oundlnputParameters 


See  Also 

For  the  corresponding  set  function,  see  SGSetSoundlnputDri  ver  (III— 1802). 


SGGetSoundlnputParameters 


Retrieves  various  parameters  that  relate  to  sound  recording. 


Component Res ul t  SGGetSoundlnputParameters 
SGChannel  c, 

short  *samp1eSize, 

short  *numChannel s , 

OSType  *compressi onType  ); 


( 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

sampl eSi ze 

A  pointer  to  a  field  to  receive  the  sample  size.  Set  this  field  to  8  for  8-bit  sound 
or  to  16  for  16-bit  sound. 
numChannel s 

A  pointer  to  a  field  to  receive  the  number  of  sound  channels  used  by  the  sound 
sample.  Set  this  field  to  1  for  monaural  sounds  or  to  2  for  stereo  sounds. 

compressi onType 

A  pointer  to  a  field  to  receive  the  format  of  the  sound  data  (see  below). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

compressionType  Constants 

'  raw  ' 

Sound  samples  are  uncompressed,  in  offset-binary  format  (that  is,  sample  data 
values  range  from  0  to  255). 

' MAC3 ' 

Sound  samples  have  been  compressed  by  the  Sound  Manager  at  a  ratio  of  3:1. 

' MAC6 ' 

Sound  samples  have  been  compressed  by  the  Sound  Manager  at  a  ratio  of  6:1. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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SGGetSoundlnputRate 


Programming  Info 

C  interface  file:  QuickTimeComponents.h 

Programming  summary:  "Configuration  Functions  for  Sound  Channel 
Components"  (V-2831),  "Working  With  Sound  Channels"  (V-2821) 

Related  Java  Methods 

quicktime.std.sg.SGSoundChannel .getSoundlnputParameterst ) 


See  Also 

For  the  corresponding  set  function,  see  SGSetSoundlnputParameters  (III— 1803). 


SGGetSoundlnputRate 


Determines  the  rate  at  which  the  sound  channel  is  collecting  sound  data. 

Fixed  SGGetSoundlnputRate  ( 

SGChannel  c  ) ; 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 


function  result  A  fixed-point  number  that  indicates  the  number  of  samples  your 
sound  channel  collects  per  second. 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  Qui  ckTimeComponents .  h 

Programming  summary:  "Configuration  Functions  for  Sound  Channel 
Components"  (V-2831),  "Working  With  Sound  Channels"  (V-2821) 

Related  Java  Methods 

quicktime.std.sg.SGSoundChannel .getSoundlnputRatet ) 


See  Also 

For  the  corresponding  set  function,  see  SGSetSoundlnputRate  (III— 1804). 


SGGetSoundRecordChunkSize 

Determines  the  amount  of  sound  data  the  sequence  grabber  component  works  with 
at  a  time. 

long  SGGetSoundRecordChunkSize  ( 


III-1734 


Inside  QuickTime:  Functions  R-Z 


SGGetSrcVideoBounds 


SGChannel  c  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 


function  result  A  long  integer  that  specifies  the  number  of  seconds  of  sound  data 
your  channel  works  with  at  a  time. 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuration  Functions  for  Sound  Channel 
Components"  (V-2831),  "Working  With  Sound  Channels"  (V-2821) 

Related  Java  Methods 

qui cktime . std . sg . SGSoundChannel . getRecordChunkSi ze( ) 


See  Also 

For  the  corresponding  set  function,  see  SGSetSoundRecordChunkSi  ze  (III— 1805). 


SGGetSrcVideoBounds 


Determines  the  size  of  the  source  video  boundary  rectangle. 

ComponentResul t  SGGetSrcVideoBounds  ( 

SGChannel  c, 

Rect  *r  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

r 

A  pointer  to  a  Rect  (IV-2399)  structure  that  is  to  receive  information  about  your 
channel's  source  video  boundary  rectangle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

For  video  channel  components  that  work  with  video  digitizer  components,  the 
source  video  boundary  rectangle  corresponds  to  the  video  digitizer's  active  source 
rectangle. 
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SGGetStorageSpaceRemaining 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuration  Functions  for  Video  Channel 
Components"  (V-2828),  "Working  With  Video  Channels"  (V-2819) 

Related  Java  Methods 

quicktime.std.sg.SGVideoChannel .getSrcVideoBounds( ) 


SGGetStorageSpaceRemaining 


Monitors  the  amount  of  space  remaining  for  use  during  a  record  operation. 

ComponentResul t  SGGetStorageSpaceRemaining  ( 

SeqGrabComponent  s, 

unsigned  long  *bytes  ); 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  fromOpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 

bytes 

A  pointer  to  a  long  integer  that  is  to  receive  a  value  indicating  the  amount  of 
space  remaining  for  the  current  record  operation.  If  you  are  recording  to 
memory,  this  value  contains  information  about  the  amount  of  memory 
remaining.  If  you  are  recording  to  a  movie  file,  this  value  contains  information 
about  the  amount  of  storage  space  available  on  the  device  that  holds  the  file. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  can  call  this  function  only  after  you  have  started  a  record  operation. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Characteristics" 
(V-2813) 

Related  Java  Methods 

quicktime.std.sg.SequenceGrabber. getStorageSpaceRemai ni ng( ) 


III-1736 
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SGGetStorageSpaceRemaining64 


SGGetStorageSpaceRemaining64 


Provides  a  64-bit  version  of  SGGetStorageSpaceRemai  ni  ng  (III— 1 736). 

ComponentResul t  SGGetStorageSpaceRemai ni ng64  ( 
SeqGrabComponent  s, 

wide  *bytes  ); 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaul  t  Component  (11-1131) 
or  OpenComponent  (11-1130). 

bytes 

A  pointer  to  a  wide  integer  that  is  to  receive  a  value  indicating  the  amount  of 
space  remaining  for  the  current  record  operation.  If  you  are  recording  to 
memory,  this  value  contains  information  about  the  amount  of  memory 
remaining.  If  you  are  recording  to  a  movie  file,  this  value  contains  information 
about  the  amount  of  storage  space  available  on  the  device  that  holds  the  file. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

See  Also 

See  SGGetStorageSpaceRemai  ni  ng  (III — 1736). 


SGGetTextReturnToSpaceValue 


Indicates  whether  the  text  channel  component  should  replace  return  characters 
with  spaces. 

ComponentResul t  SGGetTextReturnToSpaceValue  ( 

SGChannel  c, 

short  *rettospace  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 
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SGGetTimeBase 


rettospace 

A  pointer  to  a  16-bit  integer.  On  return,  this  parameter  is  TRU  E  if  the  text  channel 
is  replacing  return  characters  with  spaces,  or  FALSE  if  the  text  channel  is  not 
replacing  return  characters  with  spaces. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

When  you  capture  text  from  a  closed-caption  television  source,  the  text  is  composed 
of  four  lines  of  text  of  up  to  32  characters  each,  each  line  separated  by  a  return 
character.  Sometimes  it  is  useful  to  replace  the  return  characters  with  spaces.  You 
can  call  this  function  to  determine  whether  the  text  channel  component  is  replacing 
return  characters  with  spaces. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Text  Channel  Support"  (V-2874) 

Related  Java  Methods 

qui ckti me . std . sg . SGTextChannel .getReturnToSpaceValuet) 


See  Also 

For  the  corresponding  set  function,  see  SGSetTextReturnToSpaceVal  ue  (III— 1807). 


SGGetTimeBase 


Retrieves  a  reference  to  the  time  base  that  is  being  used  by  a  sequence  grabber 
component. 

ComponentResul t  SGGetTimeBase  ( 

SeqGrabComponent  s, 

TimeBase  *tb  ); 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  fromOpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 
tb 

A  pointer  to  a  time  base  identifier,  such  as  that  returned  by  NewT i  meBase 
(11-1119). 
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function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Characteristics" 
(V-2813) 

Related  Java  Methods 

qui cktime . std . sg . SequenceGrabber . getTi meBase( ) 


SGGetTimeRemaining 


Obtains  an  estimate  of  the  amount  of  recording  time  that  remains  for  the  current 
record  operation. 

ComponentResul t  SGGetTimeRemaining  ( 

SeqGrabComponent  s, 

long  *ticksLeft  ); 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaul  t  Component  (11-1131) 
or  OpenComponent  (11-1130). 

ti cksLeft 

A  pointer  to  a  long  integer  that  is  to  receive  a  value  indicating  an  estimate  of  the 
amount  of  time  remaining  for  the  current  record  operation.  This  value  is 
expressed  in  system  ticks  (sixtieths  of  a  second). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Characteristics" 
(V-2813) 

Related  Java  Methods 

qui cktime . std . sg . SequenceGrabber . getTi meRemai ni ng( ) 
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SGGetUserVideoCompressorList 


Returns  the  video  compression  formats  to  be  displayed  by  the  specified  sequence 
grabber  video  channel. 

ComponentResul t  SGGetUserVideoCompressorList  ( 

SGChannel  c, 

Handle  *compressorTypes  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 

compressorTypes 

A  pointer  to  handle  where  the  list  of  video  compression  formats  should  be 
returned. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns  a  copy  of  the  list  of  video  compression  formats  previously 
passed  to  SGSetUserVi  deoCompressorLi  st  (III— 1810).  If  no  video  compression 
formats  have  been  set,  it  sets  the  compressorTypes  handle  to  NIL.  The  caller  of  this 
routine  is  responsible  for  disposing  of  the  returned  handle. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Utility  Functions  for  Sequence  Grabber  Channel 
Components"  (V-2833) 

See  Also 

For  the  corresponding  set  function,  see  SGSetUserVi  deoCompressorLi  st  (III— 1810). 


SGGetUseScreenBuffer 


Determines  whether  a  video  channel  is  allowed  to  use  an  offscreen  buffer. 

ComponentResul t  SGGetUseScreenBuffer  ( 

SGChannel  c, 

Boolean  *useScreenBuffer  ); 
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c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 
useScreenBuf f er 

A  pointer  toaBoolean  value.  Set  this  field  to  T  RU  E  if  your  channel  draws  directly 
to  the  screen.  Set  it  to  FALSE  if  your  channel  can  use  an  offscreen  buffer.  If  your 
channel  cannot  work  with  offscreen  buffers,  ignore  this  value. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuration  Functions  for  Video  Channel 
Components"  (V-2828),  "Working  With  Video  Channels"  (V-2819) 

See  Also 

For  the  corresponding  set  function,  see  SGSetUseScreenBuf  fer  (III— 1811). 


SGGetVideoBottlenecks 


Determines  the  callback  functions  that  have  been  assigned  to  a  video  channel. 

ComponentResul t  SGGetVideoBottlenecks  ( 

SGChannel  c, 

VideoBottles  *vb  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

vb 

A  pointer  to  a  Vi  deoBottl  es  (IV-2501)  structure.  This  function  sets  the  fields  of 
that  structure  to  indicate  the  callback  functions  that  have  been  assigned  to  this 
video  channel.  You  must  set  the  procCount  field  in  the  VideoBottles  structure  to 
9. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Video  Channel  Callback  Functions"  (V-2823) 

See  Also 

For  the  corresponding  set  function,  see  SGSetVi  deoBottl  enecks  (III— 1811). 


SGGetVideoCompressor 


Determines  a  channel's  current  image  compression  parameters. 

ComponentResul t  SGGetVideoCompressor  ( 

SGChannel  c, 

short  *depth, 

CompressorComponent  Compressor, 

CodecQ  *spati al Qual i ty , 

CodecQ  *temporal Qual i ty , 

long  *keyFrameRate  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

depth 

A  pointer  to  a  field  that  is  to  receive  the  depth  at  which  the  image  is  likely  to  be 
viewed.  Image  compressor  components  may  use  the  depth  as  an  indication  of 
the  color  or  grayscale  resolution  of  the  compressed  images.  Return  the  depth 
value  currently  in  use  by  your  channel  component.  If  this  parameter  is  set  to 
N I L,  the  sequence  grabber  component  is  not  interested  in  this  information, 
compressor 

A  pointer  to  a  field  that  is  to  receive  an  image  compressor  identifier.  Return  the 
identifier  that  corresponds  to  the  image  compressor  your  channel  is  using.  If 
this  parameter  is  set  to  NIL,  the  sequence  grabber  component  is  not  interested 
in  this  information. 

spati al Qual i ty 

A  pointer  to  a  field  that  is  to  receive  the  desired  compressed  image  quality. 
Return  the  current  quality  value.  If  this  parameter  is  set  to  N I L,  the  sequence 
grabber  component  is  not  interested  in  this  information. 

temporal Qual i ty 

A  pointer  to  a  field  that  is  to  receive  the  desired  temporal  quality  of  the 
sequence.  This  parameter  governs  the  level  of  compression  you  desire  with 
respect  to  information  between  successive  frames  in  the  sequence.  Return  the 
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current  temporal  quality  value.  If  this  parameter  is  set  to  N I L,  the  sequence 
grabber  component  is  not  interested  in  this  information. 

keyFrameRate 

A  pointer  to  a  field  that  is  to  receive  the  maximum  number  of  frames  allowed 
between  key  frames.  Key  frames  provide  points  from  which  a  temporally 
compressed  sequence  maybe  decompressed.  This  value  controls  the  frequency 
at  which  the  image  compressor  places  key  frames  into  the  compressed 
sequence.  Return  the  current  key  frame  rate.  If  this  parameter  is  set  to  NIL,  the 
sequence  grabber  component  is  not  interested  in  this  information. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

spatialQuality  and  temporalQuality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 

codecNormal Quality 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 
codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field, 
codec Los  si essQual i ty 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuration  Lunctions  for  Video  Channel 
Components"  (V-2828),  "Working  With  Video  Channels"  (V-2819) 

Related  Java  Methods 

qui cktime . std . sg . SGVi deoChannel . getCompressorl ) 

See  Also 

Lor  the  corresponding  set  function,  see  SGSetVi  deoCompressor  (III— 1812). 
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SGGetVideoCompressorType 


Determines  the  type  of  image  compression  that  is  being  applied  to  a  channel's  video 
data. 

ComponentResul t  SGGetVideoCompressorType  ( 

SGChannel  c, 

OSType  *compressorType  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 

compressorType 

A  pointer  to  a  field  that  is  to  receive  information  about  the  type  of  image 
compression  to  use.  Return  a  value  (see  below)  that  corresponds  to  one  of  the 
image-compression  types  supported  by  the  Image  Compression  Manager.  You 
should  use  GetCodecNameLi  st  (1-386)  to  retrieve  these  names,  so  that  your 
application  can  take  advantage  of  new  compressor  types  that  may  be  added  in 
the  future. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

compressorType  Constants 

' rpza ' 

Video  compressor. 

'jpeg' 

Photo  compressor. 

'  rl  e  ' 

Animation  compressor. 

'  raw  ' 

Raw  compressor. 

'  smc  ' 

Graphics  compressor. 

' cvi d ' 

Compact  video  compressor. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuration  Functions  for  Video  Channel 
Components"  (V-2828),  "Working  With  Video  Channels"  (V-2819) 

Related  Java  Methods 

qui cktime . std . sg . SGVi deoChannel . getCompressorType( ) 


See  Also 

For  the  corresponding  set  function,  see  SGSetVi  deoCompressorType  (III— 1814). 


SGGetVideoDigitizerComponent 

Determines  the  video  digitizer  component  that  is  providing  source  video  to  a  video 
channel  component. 

Componentlnstance  SGGetVideoDigitizerComponent  ( 

SGChannel  c  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

function  result  A  component  instance  that  identifies  the  connection  between  your 
video  channel  component  and  its  video  digitizer  component.  If  your 
video  channel  component  does  not  use  a  video  digitizer  component, 
set  this  returned  value  to  NIL. 

Discussion 

This  function  allows  the  sequence  grabber  component  to  determine  the  video 
digitizer  component  that  is  providing  source  video  to  your  video  channel 
component.  For  example,  the  sequence  grabber  component  can  use  this  function  to 
obtain  access  to  the  video  digitizer  component  so  that  the  grabber  component  can 
set  the  digitizer's  parameters. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Configuration  Functions  for  Video  Channel 
Components"  (V-2828),  "Working  With  Video  Channels"  (V-2819) 

Related  Java  Methods 

qui cktime . std . sg . SGVi deoChannel . getDi gi  ti zerComponent( ) 
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See  Also 

For  the  corresponding  set  function,  see  SGSetVideoDigi  ti  zerComponent  (III— 1815).  If 
the  sequence  grabber  component  changes  any  video  digitizer  component 
parameters,  it  notifies  your  sequence  grabber  channel  component  by  calling 
SGVi  deoDi  gi  ti  zerChanged  (III — 1822). 


SGGetVideoRect 


Determines  the  portion  of  the  source  video  image  that  is  to  be  captured. 

ComponentResul t  SGGetVideoRect  ( 

SGChannel  c, 

Rect  *r  )  ; 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 
r 

A  pointer  to  a  Rect  (IV-2399)  structure  that  is  to  receive  the  dimensions  of  the 
rectangle  that  defines  the  portion  of  the  source  video  image  your  component  is 
going  to  capture. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuration  Functions  for  Video  Channel 
Components"  (V-2828),  "Working  With  Video  Channels"  (V-2819) 

Related  Java  Methods 

quickti me. std.sg.SGVideoChannel.getVideo RectO 


See  Also 

For  the  corresponding  set  function,  see  SGSetVi  deoRect  (III— 1816). 


SGGrabCompressComplete 


Provides  the  default  behavior  for  your  grab-compress-complete  function. 
ComponentResul t  SGGrabCompressComplete  ( 


III-1746 


Inside  QuickTime:  Functions  R-Z 


SGGrabFrame 


SGChannel  c. 

Boolean  *done, 

SGCompressInfo  *ci , 
TimeRecord  *tr  ); 


The  connection  identifier  for  the  channel  for  this  operation.  The  sequence 
grabber  provides  this  value  to  your  grab-compress-complete  function. 

done 

A  pointer  to  a  Boolean  value.  This  function  sets  this  value  to  TRUE  when  it  is 
done;  it  sets  it  to  FALSE  if  the  operation  is  incomplete.  The  sequence  grabber 
provides  this  pointer  to  your  grab-compress-complete  function, 
ci 

A  pointer  to  an  SGCompressInfo  (IV-2432)  structure.  When  the  operation  is 
complete,  the  function  fills  in  this  structure  with  information  about  the 
compression  operation, 
tr 

A  pointer  to  a  Ti  meRecord  (IV-2486)  structure.  When  the  operation  is  complete, 
the  function  uses  this  structure  to  indicate  when  the  frame  was  grabbed. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


SGGrabFrame 


Provides  the  default  behavior  for  your  grab  function. 

ComponentResul t  SGGrabFrame  ( 

SGChannel  c, 

short  bufferNum  ); 


The  reference  that  identifies  the  channel  for  this  operation.  The  sequence 
grabber  component  provides  this  value  to  your  grab  function. 

bufferNum 

Identifies  the  buffer.  The  sequence  grabber  component  provides  this  value  to 
your  grab  function. 
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function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


SGGrabFrameComplete 


Provides  the  default  behavior  for  your  grab-complete  function. 


Component Res ul t  SGGrabFrameCompl ete 
SGChannel  c, 

short  bufferNum, 

Bool ean  *done  ) ; 


( 


c 

The  reference  that  identifies  the  channel  for  this  operation.  The  sequence 
grabber  provides  this  value  to  your  grab-complete  function. 

bufferNum 

Identifies  the  buffer.  The  sequence  grabber  provides  this  value  to  your 
grab-complete  function. 

done 

A  pointer  to  a  Boolean  value.  The  function  sets  this  value  to  TRUE  if  the  capture 
is  complete,  and  sets  it  to  FALSE  if  the  capture  is  incomplete.  The  sequence 
grabber  provides  this  pointer  to  your  grab-complete  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 


SGGrabPict 


Lets  your  application  obtain  a  Pi  cture  (IV-2331)  structure  from  a  sequence  grabber 
component. 

ComponentResul t  SGGrabPict  ( 

SeqGrabComponent  s, 


III-1748 


Inside  QuickTime:  Functions  R-Z 


SGGrabPict 


Pi cHandl e 
const  Rect 
short 
1  ong 


*P. 

*bounds , 

of f screenDepth , 

grabPi  ctFl  ags  ); 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaul  t  Component  (11-1131) 
or  OpenComponent  (11-1130). 

P 

A  pointer  to  a  field  that  is  to  receive  a  handle  to  the  Picture  (IV-233 1 )  structure. 
If  the  function  cannot  create  the  structure,  it  sets  this  handle  to  NIL. 
bounds 

A  pointer  to  the  boundary  region  for  the  Pi  cture  (IV-2331)  structure.  By 
default,  this  rectangle  lies  in  the  current  graphics  port.  If  you  set  the 
grabPi  ctOffScreen  flag  in  the  grabPi  ctFl  ags  parameter  to  1,  the  sequence 
grabber  places  the  structure  in  an  offscreen  graphics  world.  In  this  case,  the 
rectangle  is  interpreted  in  that  offscreen  world, 
of f screenDepth 

The  pixel  depth  for  the  offscreen  graphics  world.  This  parameter  is  typically  set 
to  0,  which  chooses  the  best  available  depth.  If  you  set  the  grabPi  ctOffScreen 
flag  in  the  grabPi  ctFl  ags  parameter  to  1,  the  sequence  grabber  places  the 
Pi  cture  (IV-2331)  structure  in  an  offscreen  graphics  world.  You  specify  the 
pixel  depth  of  this  offscreen  graphics  world  with  this  parameter.  If  you  are 
displaying  the  picture,  this  parameter  is  ignored. 

grabPi  ctFl  ags 

Contains  flags  (see  below)  that  control  the  operation. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

grabPictFlags  Constants 

grabPi ctOffScreen 

Instructs  the  sequence  grabber  to  place  the  Pi  cture  (IV-2331)  structure  in  an 
offscreen  graphics  world.  Set  this  flag  to  1  to  use  an  offscreen  graphics  world. 
In  this  case,  you  use  the  offscreenDepth  parameter  to  specify  the  pixel  depth  in 
the  offscreen  buffer.  In  addition,  the  rectangle  specified  by  the  bounds 
parameter  is  applied  to  the  offscreen  buffer. 
grabPi ctlgnoreCl i p 

Instructs  the  sequence  grabber  to  ignore  any  clipping  regions  you  may  have 
defined  for  the  sequence  grabber's  channels.  Set  this  flag  to  1  to  have  the 
sequence  grabber  ignore  these  clipping  regions. 
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grabPictCurrentlmage 

Set  this  flag  to  1  to  provide  the  fastest  possible  image  capture.  Although  this 
flag  may  fail  under  certain  circumstances,  the  failure  is  recoverable;  it  just  will 
not  return  a  Pi  cture  (IV-2331)  structure.  You  can  then  call  SGGrabPi  ct  again 
without  the  flag  set.  This  routine  does  not  pause  the  current  preview  or  grab 
the  next  frame.  It  just  causes  the  currently  displayed  image  to  be  captured.  It's 
a  good  idea  to  call  SGPause  (III— 1771)  before  calling  SGGrabPi  ct  with  this  flag. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Sequence  Grabber  Components"  (V-2811) 

Related  Java  Methods 

quicktime.qd.Pict.fromSequenceGrabberl ) , 
qui cktime. std . sg . SequenceGrabber . grabPi ct ( ) 


SGHandleUpdateEvent 


Requests  that  a  sequence  grabber  handle  an  update  event. 

ComponentResul t  SGHandleUpdateEvent  ( 

SeqGrabComponent  s, 

const  EventRecord  *event, 

Bool ean  *handl ed  ) ; 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  fromOpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 

event 

A  pointer  to  an  EventRecord  (IV-2246)  structure, 
handl ed 

A  pointer  to  a  Bool  ean  that  returns  TRUE  if  the  event  was  handled,  FALSE 
otherwise. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 
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SGIdle 


Provides  processing  time  for  sequence  grabber  components. 

ComponentResul t  SGIdle  ( 

SeqGrabComponent  s  ); 


s 

An  instance  of  the  sequence  grabber  component  connected  to  your  channel 
component.  The  sequence  grabber  component  provides  this  value  through 
SGIni tChannel  (III — 1751). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

After  starting  a  preview  or  record  operation,  the  application  calls  this  function  as 
often  as  possible.  The  sequence  grabber  component  then  calls  your  SGIdle  function. 
This  continues  until  the  calling  application  stops  the  operation  by  calling  SGStop 
(III-1819)SGIdle  function  reports  several  status  and  error  conditions  by  means  of  its 
result  code.  If  your  component  returns  a  nonzero  result  code  during  a  record 
operation,  the  application  should  call  SGStop  so  that  the  sequence  grabber 
component  can  store  the  data  it  has  collected. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Controlling  Sequence  Grabber  Channel  Components" 
(V-2824),  "Controlling  Sequence  Grabber  Components"  (V-2811) 

Related  Java  Methods 

qui cktime . std . sg . SequenceGrabber . idle!) 


SGInitChannel 


Initializes  a  channel  component. 

ComponentResul t  SGInitChannel  ( 
SGChannel  c, 

SeqGrabComponent  owner  ); 


Inside  QuickTime:  Functions  R-Z 


III-1751 
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c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 
owner 

Identifies  the  sequence  grabber  component  that  has  been  connected  to  your 
channel  component.  You  should  save  this  value  so  that  your  channel 
component  can  call  the  utility  functions  that  are  provided  by  the  sequence 
grabber  component. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuring  Sequence  Grabber  Channel  Components" 
(V-2824) 

SGInitialize 


Initializes  the  sequence  grabber  component. 

ComponentResul t  SGInitialize  ( 
SeqGrabComponent  s  ) ; 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  0  p  e  n  D  e  f  a  u  1 1 C  omp  o  n  e  n  t  (II— 1 131) 
or  OpenComponent  (11-1130). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Before  you  can  call  this  function  you  must  establish  a  connection  to  the  sequence 
grabber  component.  Use  OpenDef  aul  tComponent  (11-1131)  or  OpenComponent  (11-1130) 
to  establish  a  component  connection,  as  shown  below: 

//  SGInitialize  coding  example 

//  See  “Discovering  QuickTime,”  page  262 

SeqGrabComponent  MakeMySequenceGrabber  (WindowPtr  pMacWnd) 

{ 

SeqGrabComponent  seqGrab  =  NIL; 
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OSErr  nErr  =  noErr; 

//  open  the  default  sequence  grabber 

seqGrab  =  OpenDef aul tComponent( SeqGrabComponentType ,  0); 
if  (seqGrab  !=  NIL)  { 

//  initialize  the  default  sequence  grabber  component 
nErr  =  SGIni ti al i ze( seqGrab) ; 

if  (nErr  ==  noErr)  { 

//  set  its  graphics  world  to  the  specified  window 

nErr  =  SGSetGWor1d(seqGrab,  (CGraf Ptr)pMacWnd ,  NIL); 

} 

} 

if  (nErr  &&  (seqGrab  !=  NIL))  {  //  clean  up  on  failure 

Cl oseComponent( seqGrab) ; 
seqGrab  =  NIL; 

} 

return  seqGrab; 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuring  Sequence  Grabber  Components"  (V-2809) 

Related  Java  Methods 

qui cktime . std . sg . SequenceGrabber . SequenceGrabber( ) 


SGNewChannel 


Creates  a  sequence  grabber  channel  and  assigns  a  channel  component  to  the 
channel. 

ComponentResul t  SGNewChannel  ( 

SeqGrabComponent  s, 

OSType  channelType, 

SGChannel  *ref  ); 
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SGNewChannel 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 
channel  Type 

The  type  of  channel  to  open  (see  below).  This  value  corresponds  to  the 
component  subtype  value  of  the  channel  component. 

ref 

Apointer  to  the  f  rameChannel  field  in  the  SeqGrabFramelnfo  (IV-2430)  structure 
that  is  to  receive  a  reference  to  the  channel  that  is  added  to  the  sequence  grabber 
component.  If  the  sequence  grabber  component  successfully  locates  and 
connects  to  an  appropriate  channel  component,  the  sequence  grabber 
component  returns  a  reference  to  the  channel  component  into  this  field. 

function  result  See  "Error  Codes"  (IV-2663).  If  the  sequence  grabber  component 

cannot  open  a  connection,  it  sets  the  result  code  to  a  nonzero  value. 
It  returns  noErr  if  there  is  no  error. 

channelType  Constants 

Vi deoMedi aType 
Video  channel. 

SoundMedi aType 

Sound  channel. 

Discussion 

The  channel  component  is  responsible  for  providing  digitized  data  to  the  sequence 
grabber  component.  You  specify  the  type  of  channel  component  to  be  added  to  the 
sequence  grabber  component,  as  shown  in  the  following  sample  code: 

//  SGNewChannel  coding  example 
//  See  “Discovering  QuickTime,”  page  263 
void  MakeMyGrabChannel s  ( SeqGrabComponent 

SGChannel 
SGChannel 
const  Rect 
Bool ean 

{ 

OSErr  nErr; 

long  lUsage; 

//  figure  out  the  usage 

lUsage  =  seqGrabPrevi ew ;  //  always  previewing 


seqGrab , 
*sgchanVi deo , 
*sgchanSound , 
*rect , 

bWi 1 1  Record ) 
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if  ( bWi 1 1  Record ) 

lUsage  |=  seqGrabRecord ;  //  sometimes  recording 

//  create  a  video  channel 

nErr  =  SGNewChannel ( seqGrab ,  Vi deoMedi aType ,  sgchanVideo) ; 
if  (nErr  ==  noErr)  { 

//  set  boundaries  for  new  video  channel 
nErr  =  SGSetChannel Bounds (*sgchanVi deo ,  rect); 

//  set  usage  for  new  video  channel 
if  (nErr  ==  noErr) 

nErr  =  SGSetChannel Usage(*sgchanVi deo ,  lUsage  | 

seqGrabPl ay Du ri ng Record ) ; 

if  (nErr  !=  noErr)  { 

//  clean  up  on  failure 
SGDisposeChanneK seqGrab,  *sgchanVideo); 

*sgchanVideo  =  NIL; 

} 


//  create  a  sound  channel 

nErr  =  SGNewChannel ( seqGrab ,  SoundMedi aType ,  sgchanSound ) ; 
if  (nErr  ==  noErr)  { 

//  set  usage  of  new  sound  channel 

nErr  =  SGSetChannel Usage(*sgchanSound ,  lUsage); 

if  (nErr  !=  noErr)  { 

//  clean  up  on  failure 
SGDisposeChanneK seqGrab,  *sgchanSound); 

*sgchanSound  =  NIL; 

} 

} 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuring  Sequence  Grabber  Components"  (V-2809) 

Related  Java  Methods 

qui  cktime .  std  .  sg  .  SGVi  deoChannel  .  SGVi  deoChanneK), 
qui cktime . std . sg . SGMusi cChannel . SGMusi cChannel ( ) , 
quicktime.std.sg.SGSoundChannel.SGSoundChanneK), 
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quicktime.std.sg.SGTextChannel .SGTextChannel ( ) 


See  Also 

If  you  want  to  use  a  specific  channel  component,  you  may  use 
SGNewChannel  FromComponent  (III — 1756). 


SGNewChannelFromComponent 


Creates  a  sequence  grabber  channel  and  assigns  a  channel  component  to  the 
channel. 

ComponentResul t  SGNewChannelFromComponent  ( 

SeqGrabComponent  s, 

SGChannel  *newChannel  , 

Component  sgChannel Component  ); 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  0  p  e  n  D  e  f  a  u  1 1 C  omp  o  n  e  n  t  (II— 1 131) 
or  OpenComponent  (11-1130). 

newChannel 

A  pointer  to  a  channel  component  that  is  to  receive  a  reference  to  the  channel 
that  is  added  to  the  sequence  grabber  component.  If  the  sequence  grabber 
component  successfully  locates  and  connects  to  the  specified  channel 
component,  the  sequence  grabber  component  returns  a  reference  to  the  channel 
component  into  this  field. 

sgChannel Component 

Identifies  the  channel  component  to  use.  You  supply  a  component  ID  value  to 
the  sequence  grabber.  The  sequence  grabber  then  opens  a  connection  to  that 
channel  component  and  returns  your  connection  ID  in  the  field  specified  by  the 
newChannel  parameter.  You  may  obtain  a  component  ID  value  by  calling 
Fi ndNextComponent  (1-360). 

function  result  See  "Error  Codes"  (IV-2663).  If  the  sequence  grabber  component 

cannot  open  a  connection,  it  sets  the  result  code  to  a  nonzero  value. 
It  returns  noE nr  if  there  is  no  error. 

Discussion 

This  function  is  similar  to  SGNewChannel  (III— 1753),  except  that  this  function  allows 
you  to  specify  a  particular  component  rather  than  just  a  component  subtype  value. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuring  Sequence  Grabber  Components"  (V-2809) 

See  Also 

When  you  are  done  with  the  sequence  grabber  component,  you  can  dispose  of  the 
channels  you  have  used  by  calling  SGDi  sposeChannel  (III— 1695). 


SGNewOutput 


Creates  a  new  sequence  grabber  output. 


ComponentResul t  SGNewOutput  ( 
SeqGrabComponent  s. 

Handle  dataRef, 

OSType  dataRefType, 

long  whereFlags, 

SGOutput  *sgOut  ); 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaul  t  Component  (11-1131) 
or  OpenComponent  (11-1130). 

dataRef 

A  handle  to  the  destination  container. 
dataRefType 

The  type  of  data  reference;  see  "Data  References"  (IV-2661).  If  the  data 
reference  is  an  alias,  you  must  set  the  parameter  to  rAl  i  asType. 
whereFl ags 

Flags  (see  below)  that  control  the  record  operation.  You  must  set  either 
seqGrabToDi  sk  or  seqGrabToMemory  to  1.  Set  unused  flags  to  0. 

sgOut 

A  pointer  to  a  sequence  grabber  output.  The  sequence  grabber  component 
returns  an  output  identifier  that  you  can  use  with  other  sequence  grabber 
component  functions. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

whereFlags  Constants 

seqGrabToDi sk 

Instructs  the  sequence  grabber  component  to  write  the  recorded  data  to  a 
QuickT ime  movie  in  the  movie  file  specified  by  the  m o  v  i  e  F  i  1  e  parameter.  If  this 
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flag  is  set  to  1,  the  sequence  grabber  writes  the  data  to  the  file  as  the  data  is 
recorded. 

seqGrabToMemory 

Instructs  the  sequence  grabber  component  to  store  the  recorded  data  in 
memory  until  the  recording  process  is  complete.  The  sequence  grabber  then 
writes  the  recorded  data  to  the  movie  file  specified  by  the  mo v i  e  Fi  1  e  parameter. 
This  technique  provides  better  performance  than  recording  directly  to  the 
movie  file,  but  it  limits  the  amount  of  data  you  can  record.  If  this  flag  is  set  to  1, 
the  sequence  grabber  component  is  recording  to  memory. 

seqGrabDontllseTempMemory 

Prevents  the  sequence  grabber  component  from  using  temporary  memory 
during  the  record  operation.  By  default,  the  sequence  grabber  component  and 
its  channel  components  use  as  much  temporary  memory  as  necessary  to 
perform  the  record  operation.  If  this  flag  is  set  to  1,  the  sequence  grabber 
component  and  its  channel  components  do  not  use  temporary  memory. 
seqGrabAppendToFi 1 e 

Directs  the  sequence  grabber  component  to  add  the  recorded  data  to  the  data 
fork  of  the  movie  file  specified  by  the  movi  eFi  1  e  parameter.  By  default,  the 
sequence  grabber  component  deletes  the  movie  file  and  creates  a  new  file 
containing  one  movie  and  its  movie  resource.  If  this  flag  is  set  to  1,  the  sequence 
grabber  component  appends  the  recorded  data  to  the  data  fork  of  the  movie  file 
and  creates  a  new  movie  resource  in  that  file. 

seqGrabDontAddMovi e Resource 

Prevents  the  sequence  grabber  component  from  adding  the  new  movie 
resource  to  the  movie  file  specified  by  the  movi  eFi  1  e  parameter.  By  default,  the 
sequence  grabber  component  creates  a  new  movie  resource  and  adds  that 
resource  to  the  movie  file.  If  this  flag  is  set  to  1,  the  sequence  grabber 
component  does  not  add  the  movie  resource  to  the  movie  file.  You  are  then 
responsible  for  adding  the  resource  to  a  file,  if  you  so  desire 

seqGrabDontMakeMovi e 

Prevents  the  sequence  grabber  component  from  creating  a  movie.  By  default, 
the  sequence  grabber  component  creates  a  new  movie  resource  and  adds  the 
captured  data  to  that  movie.  If  this  flag  is  set  to  1,  the  sequence  grabber  still  calls 
your  data  function,  but  does  not  write  any  data  to  the  movie  file. 

Discussion 

Once  you  have  created  the  sequence  grabber  output,  you  can  use 
SGSetChannel  Output  (III— 1778)  to  assign  the  output  to  a  sequence  grabber  channel. 
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Version  Notes 

A  sequence  grabber  output  ties  a  sequence  grabber  channel  to  a  specified  data 
reference  for  the  output  of  captured  data.  If  you  are  capturing  to  a  single  movie  file, 
you  can  continue  to  use  SGSetDataOutput  (III— 1785)  or  SGSetDataRef  (III— 1 787)  to 
specify  the  sequence  grabber's  destination.  However,  if  you  want  to  capture  movie 
data  into  several  different  files  or  data  references,  you  must  use  sequence  grabber 
outputs  to  do  so.  Even  if  you  are  using  outputs,  you  must  still  use  SGSetDataOutput 
or  SGSetDataRef  to  identify  where  the  sequence  grabber  should  create  the  movie 
resource.  You  are  responsible  for  creating  outputs,  assigning  them  to  sequence 
grabber  channels,  and  disposing  of  them  when  you  are  done. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Outputs"  (V-2814) 


SGPanelCanRun 


Lets  a  sequence  grabber  component  determine  whether  a  panel  component  can 
work  with  the  current  sequence  grabber  channel  component. 

ComponentResul t  SGPanelCanRun  ( 

SeqGrabComponent  s, 

SGChannel  c  ); 


s 

Identifies  the  sequence  grabber  component's  connection  to  your  panel 
component.  See  SGPanel  SetGrabber  (III— 1767). 

c 

The  connection  identifier  for  the  channel  for  this  operation.  The  sequence 
grabber  component  provides  you  with  a  connection  to  the  channel  component 
in  question.  You  must  determine  whether  your  panel  component  can  operate 
with  this  channel  component  and  its  associated  channel  hardware. 

function  result  If  your  component  can  work  with  the  specified  channel,  return  a 
result  code  of  noErr.  Otherwise,  return  an  appropriate  sequence 
grabber  or  sequence  grabber  channel  component  result  code.  See 
"Error  Codes"  (IV-2663). 

Discussion 

Set  the  channel  FI  agHasDependency  flag  in  the  ComponentDescri  pti  on  (IV-2212) 
structure  of  your  sequence  grabber  panel  component  to  cause  the  sequence  grabber 
component  to  call  this  function.  Your  component  should  query  the  channel 
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component  to  determine  whether  you  can  operate  with  it.  You  may  want  to  use 
channel  component  functions  to  determine  the  characteristics  of  the  digitization 
source  attached  to  the  channel. 

Special  Considerations 

If  your  panel  component  can  only  support  a  limited  number  of  connections,  you 
should  regulate  the  number  of  active  connections  through  this  function.  Return  a 
nonzero  result  code  to  indicate  to  the  sequence  grabber  that  your  panel  component 
cannot  support  the  current  connection. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Managing  Your  Panel  Component"  (V-2835) 


SGPanelEvent 


Lets  a  component  receive  and  process  dialog  events. 


ComponentResul t  SGPanelEvent  ( 


SeqGrabComponent 
SGChannel 
Di al ogPtr 
short 

const  EventRecord 

short 

Bool ean 


s , 

c , 

d, 

i temOffset , 
*theEvent , 
*i temHi t , 
*handled  ); 


Identifies  the  sequence  grabber  component's  connection  to  your  panel 
component.  See  SGPanel  SetGrabber  (III— 1767). 

c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

d 

A  dialog  pointer  identifying  the  settings  dialog  box. 
i temOffset 

The  offset  to  your  panel's  first  item  in  the  dialog  box. 
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theEvent 

A  pointer  to  an  EventRecord  (IV-2246)  structure.  This  structure  contains 
information  identifying  the  nature  of  the  event, 
i temHi t 

A  pointer  to  a  field  that  is  to  receive  the  item  number  in  cases  where  your 
component  handles  the  event.  The  number  returned  is  an  absolute,  not  a 
relative  number,  so  it  must  be  offset  by  the  i  temOf  f  set  parameter. 

handl ed 

A  pointer  to  a  Boolean  value.  Set  this  Boolean  value  to  TRUE  if  you  handle  the 
event;  set  it  to  FALSE  if  you  do  not. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Processing  Your  Panel's  Events"  (V-2836) 


SGPanelGetDitl 


Lets  a  sequence  grabber  component  determine  the  dialog  items  managed  by  your 
panel  component. 

ComponentResul t  SGPanelGetDitl  ( 

SeqGrabComponent  s. 

Handle  *  d  i  1 1  ); 


Identifies  the  sequence  grabber  component's  connection  to  your  panel 
component.  See  SGPanel  SetGrabber  (III— 1767). 

d  i  1 1 

A  pointer  to  a  handle  provided  by  the  sequence  grabber  component.  Your 
component  returns  the  item  list  in  this  handle.  Your  component  should  resize 
this  handle  as  appropriate.  The  sequence  grabber  component  will  dispose  of 
this  handle  after  retrieving  the  item  list,  so  make  sure  that  the  item  list  is  not 
stored  in  a  resource. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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Discussion 

The  sequence  grabber  uses  the  information  returned  by  this  function  to  build  a 
sequence  grabber  settings  dialog  box  for  the  user.  The  sequence  grabber  component 
will  open  your  resource  file  before  calling  this  function,  unless  you  have  instructed 
the  sequence  grabber  component  not  to  open  your  resource  file  by  setting  the 
channel  FI  agDontOpenResFi  1  e  flag  in  your  your  panel  component's 
ComponentDescri pti  on  (IV-2212)  structure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Managing  Your  Panel  Component"  (V-2835) 


SGPanelGetSettings 


Retrieves  a  panel's  current  settings  for  a  sequence  grabber  component. 

ComponentResul t  SGPanelGetSettings  ( 

SeqGrabComponent  s, 

SGChannel  c, 

UserData  *ud, 

1 ong  f 1 ags  ) ; 


Identifies  the  sequence  grabber  component's  connection  to  your  panel 
component.  See  SGPanel  SetGrabber  (III— 1767). 

c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

ud 

A  pointer  to  a  UserData  Record  (IV-2496)  structure.  Your  component  is 
responsible  for  creating  a  new  structure  and  returning  it  by  means  of  this 
pointer.  Your  component  is  not  responsible  for  disposing  of  the  structure. 
These  settings  may  be  stored  as  part  of  a  larger  sequence  grabber  configuration 
and  may  be  stored  for  a  long  period  of  time.  Therefore,  you  should  not  store 
values  that  may  change  without  your  knowledge  (such  as  component  ID  or 
connection  values).  You  are  free  to  format  the  data  in  user  data  items  any  way 
you  desire. 
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flags 

Reserved  for  future  use. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Make  sure  your  component  can  retrieve  the  settings  information  from  the  user  data 
item  when  this  function  is  called.  You  may  choose  to  format  the  data  in  such  a  way 
that  other  components  can  parse  it  easily,  thus  allowing  your  component  to  operate 
with  other  panel  components. 

Special  Considerations 

You  create  new  user  data  items  by  calling  NewUserData  (11-1124).  You  may  then  use 
other  Movie  Toolbox  functions  to  manipulate  the  user  data  items. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Managing  Your  Panel's  Settings"  (V-2837) 

See  Also 

For  the  corresponding  set  function,  see  SGPanel  SetSetti  ngs  (III— 1769). 


SGPanelGetTitle 


Gets  the  displayed  title  of  a  sequence  grabber  panel. 

ComponentResul t  SGPanelGetTitle  ( 
SeqGrabComponent  s, 

Str255  title  ); 


Identifies  the  sequence  grabber  component's  connection  to  your  panel 
component.  See  SGPanel  SetGrabber  (III— 1767). 
ti  tl  e 

A  string  containing  the  panel's  title. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Functions  R-Z 


III-1763 


SGPanellnstall 


Programming  Info 

C  interface  file:  QuickTimeComponents.h 

Programming  summary:  "Managing  Your  Panel  Component"  (V-2835) 


SGPanellnstall 


Installs  added  items  in  a  sequence  grabber  settings  dialog  box  before  the  dialog  box 
is  displayed  to  the  user. 

ComponentResul t  SGPanellnstall  ( 


SeqGrabComponent 

s  , 

SGChannel 

c  , 

Di al ogPtr 

d. 

short 

i temOffset 

Identifies  the  sequence  grabber  component's  connection  to  your  panel 
component.  See  SGPanel  SetGrabber  (III— 1767). 

c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 
d 

A  dialog  pointer  identifying  the  settings  dialog  box.  Your  component  may  use 
this  value  to  manage  its  part  of  the  dialog  box. 

i temOffset 

The  offset  to  your  panel's  first  item  in  the  dialog  box.  Because  sequence  grabber 
components  build  your  dialog  items  into  a  larger  dialog  box  containing  other 
items,  this  value  may  be  different  each  time  your  panel  component  is  installed; 
do  not  rely  on  it  being  the  same. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

A  sequence  grabber  component  calls  this  function  just  before  displaying  the  dialog 
box  to  the  user.  The  sequence  grabber  provides  you  with  information  identifying 
the  channel  that  your  panel  is  to  configure,  the  dialog  box,  and  the  offset  of  your 
panel's  items  into  the  dialog  box.  You  may  use  this  opportunity  to  set  default  dialog 
values  or  to  initialize  your  control  values. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


III-1764 


Inside  QuickTime:  Functions  R-Z 


SGPanelltem 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Managing  Your  Panel  Component"  (V-2835) 


SGPanelltem 


Receives  and  processes  mouse  clicks  in  the  sequence  grabber  settings  dialog  box. 


ComponentResul t  SGPanelltem  ( 
SeqGrabComponent  s, 

SGChannel  c, 

DialogPtr  d, 

short  itemOffset, 

short  itemNum  ); 


Identifies  the  sequence  grabber  component's  connection  to  your  panel 
component.  See  SGPanel  SetGrabber  (III— 1767). 
c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

d 

A  dialog  pointer  identifying  the  settings  dialog  box. 
i temOf f set 

The  offset  to  your  panel's  first  item  in  the  dialog  box. 
i temNum 

The  item  number  of  the  dialog  item  selected  by  the  user.  The  sequence  grabber 
provides  an  absolute  item  number.  It  is  your  responsibility  to  adjust  this  value 
to  account  for  the  offset  to  your  panel's  first  item  in  the  dialog  box. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

A  sequence  grabber  component  calls  this  function  whenever  the  user  clicks  an  item 
in  the  settings  dialog  box.  Your  component  may  then  perform  whatever  processing 
is  appropriate,  depending  upon  the  item  number. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Functions  R-Z 


III-1765 


SGPanelRemove 


Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Processing  Your  Panel's  Events"  (V-2836) 

See  Also 

Sequence  grabber  components  use  your  component's  SGPanelValidatelnput 
(III— 1770)  function  to  validate  the  current  input  settings  as  a  whole. 


SGPanelRemove 


Removes  a  panel  from  the  sequence  grabber  settings  dialog  box. 
ComponentResul t  SGPanel Remove  ( 


SeqGrabComponent 

s  , 

SGChannel 

c  , 

Di al ogPtr 

d. 

short 

i temOffset  ) 

s 

Identifies  the  sequence  grabber  component's  connection  to  your  panel 
component.  See  SGPanel  SetGrabber  (III— 1767). 
c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 

d 

A  dialog  pointer  identifying  the  settings  dialog  box. 
i temOffset 

The  offset  to  your  panel's  first  item  in  the  dialog  box. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

A  sequence  grabber  component  calls  this  function  just  before  removing  your  items 
from  the  settings  dialog  box.  The  sequence  grabber  provides  you  with  information 
identifying  the  channel  your  panel  is  to  configure,  the  dialog  box,  and  the  offset  of 
your  panel's  items  into  the  dialog  box.  You  may  use  this  opportunity  to  save  any 
changes  you  may  have  made  to  the  dialog  box  or  to  retrieve  the  contents  of  text 
items. 

Special  Considerations 

If  the  sequence  grabber  opened  your  resource  file,  it  will  still  be  open  when  it  calls 
this  function. 


III-1766 


Inside  QuickTime:  Functions  R-Z 


SGPanelSetEventFilter 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui ckTi  meComponents  .  h 

Programming  summary:  "Managing  Your  Panel  Component"  (V-2835) 

See  Also 

Sequence  grabbers  call  your  SGPanel  Install  (III— 1764)  function  before  displaying 
the  settings  dialog  box  to  the  user. 


SGPanelSetEventFilter 


Sets  the  event  filter  callback  for  a  sequence  grabber  panel  component. 

ComponentResul t  SGPanelSetEventFilter  ( 

SeqGrabComponent  s, 

SGModal  Fi  1  terllPP  proc, 

long  refCon  ); 


s 

Identifies  the  sequence  grabber  component's  connection  to  your  panel 
component.  See  SGPanel  SetGrabber  (III— 1767). 

proc 

An  SGModal  FilterProc  (III— 2144)  callback. 
refCon 

A  reference  constant  to  be  passed  to  your  callback.  Use  this  parameter  to  point 
to  a  data  structure  containing  any  information  your  function  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Processing  Your  Panel's  Events"  (V-2836) 


SGPanelSetGrabber 


Identifies  a  sequence  grabber  component  to  a  panel  component. 
ComponentResul t  SGPanelSetGrabber  ( 


Inside  QuickTime:  Functions  R-Z 


III-1767 


SGPanelSetResFile 


SeqGrabComponent  s, 

SeqGrabComponent  sg  ) ; 


s 

Identifies  the  sequence  grabber  component's  connection  to  your  panel 
component, 
sg 

Identifies  a  connection  to  the  sequence  grabber  component  that  is  using  your 
panel  component.  Your  component  may  use  this  connection  to  call  sequence 
grabber  component  functions. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

A  sequence  grabber  component  calls  this  function  in  order  to  identify  itself  to  your 
panel  component.  Your  component  can  use  the  provided  connection  to  call 
sequence  grabber  functions,  either  to  determine  the  characteristics  of  the  current 
capture  operation  or  to  alter  those  characteristics. 

Special  Considerations 

This  is  typically  the  first  function  a  sequence  grabber  component  calls  after  opening 
your  panel  component. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Managing  Your  Panel  Component"  (V-2835) 


SGPanelSetResFile 


Lets  the  sequence  grabber  pass  a  resource  file's  reference  number. 

ComponentResul t  SGPanelSetResFile  ( 

SeqGrabComponent  s, 

short  resRef  ) ; 


Identifies  the  sequence  grabber  component's  connection  to  your  panel 
component.  See  SGPanel  SetGrabber  (III— 1767). 


III-1768 


Inside  QuickTime:  Functions  R-Z 


SGPanelSetSettings 


resRef 

A  reference  number  that  identifies  your  component's  resource  file.  After  it 
closes  your  resource  file,  the  sequence  grabber  component  calls  this  function 
and  sets  this  value  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

A  sequence  grabber  component  calls  this  function  to  pass  you  your  component's 
resource  file  reference  number.  By  default,  the  sequence  grabber  component  opens 
your  component's  resource  file  for  you.  You  can  use  this  reference  number  to 
retrieve  resources  from  your  resource  file.  The  sequence  grabber  component  also 
calls  this  function  when  it  closes  your  component's  resource  file.  In  this  case,  it  sets 
the  resRef  parameter  to  0.  The  sequence  grabber  component  may  close  your 
resource  file  at  any  time;  you  should  not  count  on  any  particular  calling  sequence. 
If  you  do  not  want  the  sequence  grabber  component  to  open  your  resource  file,  set 
the  channel  FI  agDontOpenResFi  1  e  flag  in  your  panel  component's 
ComponentDescri pti on  (IV-2212)  structure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Managing  Your  Panel  Component"  (V-2835) 


SGPanelSetSettings 


Restores  a  panel's  current  settings  for  a  sequence  grabber  component. 
ComponentResul t  SGPanelSetSettings  ( 


SeqGrabComponent  s, 
SGChannel  c, 

UserData  ud, 

long  flags  ); 


Identifies  the  sequence  grabber  component's  connection  to  your  panel 
component.  See  SGPanel  SetGrabber  (III— 1767). 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 


Inside  QuickTime:  Functions  R-Z 


III-1769 


SGPanelValidatelnput 


ud 

Identifies  a  UserDataRecord  (IV-2496)  structure  that  contains  new  settings 
information  for  your  panel.  Your  component  must  not  dispose  of  this  structure, 
fl  ags 

Reserved  for  future  use. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  component  originally  creates  the  settings  information  when  the  sequence 
grabber  calls  SGPanel  GetSetti  ngs  (III— 1762).  The  sequence  grabber  passes  this 
configuration  information  back  to  you  in  the  ud  parameter  to  this  function.  Your 
component  should  parse  the  configuration  information  and  use  it  to  establish  your 
panel's  current  settings.  Note  that  your  component  may  not  be  able  to 
accommodate  the  original  settings.  For  example,  because  the  settings  may  have 
been  stored  for  some  time,  the  hardware  environment  may  not  be  able  to  support 
the  values  in  the  settings.  You  should  try  to  make  your  new  settings  match  the 
original  settings  as  closely  as  possible.  If  you  cannot  get  close  enough,  return  an 
appropriate  sequence  grabber  or  sequence  grabber  channel  result  code. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Managing  Your  Panel's  Settings"  (V-2837) 

See  Also 

For  the  corresponding  get  function,  see  SGPanel  GetSetti  ngs  (III— 1762). 


SGPanelValidatelnput 


Validates  the  contents  of  the  user  dialog  box  for  a  sequence  grabber  component. 

ComponentResul t  SGPanelValidatelnput  ( 

SeqGrabComponent  s, 

Boolean  *ok  ); 


Identifies  the  sequence  grabber  component's  connection  to  your  panel 
component.  See  SGPanel  SetGrabber  (III— 1767). 


III-1770 


Inside  QuickTime:  Functions  R-Z 


SGPause 


ok 

A  pointer  to  a  Boolean  value.  Set  this  value  to  TRUE  if  the  settings  are  OK; 
otherwise,  set  it  to  FALSE. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  sequence  grabber  calls  this  function  when  the  user  clicks  the  OK  button.  If  the 
user  clicks  the  Cancel  button,  the  sequence  grabber  does  not  call  this  function.  You 
indicate  whether  the  settings  are  acceptable  by  setting  the  Boolean  value  referred  to 
by  the  okparameter.  If  you  set  this  value  to  FALSE,  the  sequence  grabber  component 
ignores  the  OK  button  in  the  dialog  box. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Processing  Your  Panel's  Events"  (V-2836) 


SGPause 


Suspends  or  restarts  a  sequence  grabber  record  or  preview  operation. 

ComponentResul t  SGPause  ( 

SeqGrabComponent  s. 

Byte  pause  ); 


s 

An  instance  of  the  sequence  grabber  component  connected  to  your  channel 
component.  The  sequence  grabber  component  provides  this  value  through 
SGIni tChannel  (III — 1751). 

pause 

A  constant  (see  below)  that  instructs  your  component  to  suspend  or  restart  the 
current  operation. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

pause  Constants 

seqGrabUnpause 

Restart  the  current  operation. 
seqGrabPause 

Pause  the  current  operation. 


Inside  QuickTime:  Functions  R-Z 


III-1771 


SGPrepare 


Discussion 

Your  component  should  not  release  any  system  resources  or  temporary  memory 
associated  with  the  current  operation.  You  should  be  ready  to  restart  the  operation 
immediately. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Sequence  Grabber  Channel  Components" 
(V-2824),  "Controlling  Sequence  Grabber  Components"  (V-2811) 

Related  Java  Methods 

qui ckti me. std . sg . SequenceGrabber . pause! ) 


SGPrepare 


Instructs  a  sequence  grabber  to  get  ready  to  begin  a  preview  or  record  operation. 

ComponentResul t  SGPrepare  ( 

SeqGrabComponent  s, 

Boolean  prepareForPreview, 

Boolean  prepareForRecord  ); 


s 

An  instance  of  the  sequence  grabber  component  connected  to  your  channel 
component.  The  sequence  grabber  component  provides  this  value  through 
SGInl tChannel  (III — 1751). 

prepareForPrevi ew 

The  sequence  grabber  component  sets  this  parameter  to  TRUE  to  prepare  for  a 
preview  operation.  The  sequence  grabber  component  may  set  both  the 
prepareForPrevi  ew  and  prepareForRecord  parameters  to  TRUE. 

prepareForRecord 

The  sequence  grabber  component  sets  this  parameter  to  TRUE  to  prepare  for  a 
record  operation.  The  sequence  grabber  component  may  set  both  the 
prepareForPrevi  ew  and  prepareForRecord  parameters  to  TRUE. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

If  you  do  not  call  this  function  before  starting  a  record  or  preview  operation,  the 
sequence  grabber  component  makes  these  preparations  when  you  start  the 


III-1772 


Inside  QuickTime:  Functions  R-Z 


SGRelease 


operation.  You  cannot  call  this  function  after  you  start  a  preview  or  record 
operation.  If  you  call  this  function  without  subsequently  starting  a  record  or 
preview  operation,  you  should  call  SGRel  ease  (III— 1773).  This  allows  the  sequence 
grabber  component  to  release  any  system  resources  it  allocated  when  you  called 
this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Controlling  Sequence  Grabber  Channel  Components" 
(V-2824),  "Controlling  Sequence  Grabber  Components"  (V-2811) 

Related  Java  Methods 

qui cktime . std . sg . SequenceGrabber . prepareC ) 


SGRelease 


Instructs  the  sequence  grabber  to  release  any  system  resources  it  allocated  when 
you  called  SGPrepare  (III— 1 772). 

ComponentResul t  SGRelease  ( 

SeqGrabComponent  s  ); 


s 

An  instance  of  the  sequence  grabber  component  connected  to  your  channel 
component.  The  sequence  grabber  component  provides  this  value  through 
SGIni tChannel  (III — 1751). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  cannot  call  this  function  during  a  record  or  preview  operation. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Controlling  Sequence  Grabber  Channel  Components" 
(V-2824),  "Controlling  Sequence  Grabber  Components"  (V-2811) 

Related  Java  Methods 

qui cktime . std . sg . SequenceGrabber . rel ease( ) 


Inside  QuickTime:  Functions  R-Z 


III-1773 


SGSetAdditionalSoundRates 


SGSetAdditionalSoundRates 


Specifies  a  list  of  sound  sample  rates  to  be  included  in  the  sequence  grabber's  sound 
settings  dialog  box. 

ComponentResul t  SGSetAdditionalSoundRates  ( 

SGChannel  c, 

Hand! e  rates  ) ; 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 

rates 

A  handle  containing  a  list  of  unsigned  32-bit  fixed-point  values.  The  sequence 
grabber  channel  determines  the  number  of  sample  rates  contained  in  the 
handle,  based  on  the  size  of  the  handle.  If  any  of  the  requested  rates  are  not 
supported  directly  by  the  available  sound  capture  hardware,  sound  will  be 
captured  at  one  of  the  available  hardware  rates  and  then  converted  in  software 
to  the  requested  rate. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  sequence  grabber  channel  makes  a  copy  of  the  additional  rates  handle,  so  your 
application  can  immediately  dispose  of  it  after  making  this  call. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Utility  Functions  for  Sequence  Grabber  Channel 
Components"  (V-2833) 

See  Also 

For  the  corresponding  get  function,  see  SGGetAddi  ti  onal  SoundRates  (III— 1697). 


SGSetChannelBounds 


Specifies  a  channel's  display  boundary  rectangle. 

ComponentResul t  SGSetChannelBounds  ( 

SGChannel  c, 

const  Rect  *bounds  ) ; 


III-1774 


Inside  QuickTime:  Functions  R-Z 


SGSetChannelClip 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 
bounds 

A  pointer  to  a  Rect  (IV-2399)  structure  that  defines  your  channel's  display 
boundary  rectangle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuration  Functions  for  Video  Channel 
Components"  (V-2828),  "Working  With  Channel  Characteristics"  (V-2815) 

Related  Java  Methods 

quic kti me. std.sg.VisualChannel. set Bounds!) 


See  Also 

For  the  corresponding  get  function,  see  SGGetChannel  Bounds  (III— 1700). 


SGSetChannelClip 


Sets  a  channel's  clipping  region. 

ComponentResul t  SGSetChannelClip  ( 
SGChannel  c, 

RgnHandle  theClip  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 
theCl i p 

A  handle  to  the  new  clipping  region.  You  should  make  a  copy  of  this  region;  the 
application  may  dispose  of  the  region  immediately. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Functions  R-Z 


III-1775 


SGSetChannelDevice 


Programming  Info 

C  interface  file:  QuickTimeComponents.h 

Programming  summary:  "Configuration  Functions  for  All  Channel  Components" 
(V-2826),  "Working  With  Channel  Characteristics"  (V-2815) 

Related  Java  Methods 

qui cktime. std . sg . Vi sual Channel . set Cl i p( ) 


See  Also 

For  the  corresponding  get  function,  see  SGGetChannel  Cl  i  p  (III— 1700). 


SGSetChannelDevice 


Assigns  a  device  to  a  channel. 

ComponentResul t  SGSetChannelDevice  ( 
SGChannel  c, 

Stri ngPtr  name  ) ; 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 

name 

A  pointer  to  the  device's  name  string.  This  name  is  contained  in  the  name  field 
of  the  appropriate  SGDevi  ceName  (IV-2434)  structure  in  the  SGDevi  ceLi  stRecord 
(IV-2433)  structure  that  your  channel  component  returns  to  the 
SGGetChannel  Devi  ceLi  st  (III— 1701)  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Managing  Channel  Devices"  (V-2828),  "Working  With 
Channel  Devices"  (V-2818) 


SGSetChannelMatrix 

Sets  a  channel's  display  transformation  matrix. 
ComponentResul t  SGSetChannelMatrix  ( 


III-1776 
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SGSetChannelMaxFrames 


SGChannel  c, 

const  MatrixRecord  *m  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 
m 

A  pointer  to  a  Matri  xRecord  (IV-2304)  structure.  This  parameter  is  set  to  NI L  to 
select  the  identity  matrix. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuration  Functions  for  All  Channel  Components" 
(V-2826),  "Working  With  Channel  Characteristics"  (V-2815) 

Related  Java  Methods 

qui ckti me . std . sg . Vi sual Channel . setMatrix( ) 


See  Also 

For  the  corresponding  get  function,  see  SGGetChannel  Matri  x  (III— 1703).  Other 
channel  component  functions  may  affect  this  matrix.  The  SGSetChannel  Bounds 
(III— 1774)  function  sets  the  matrix  values  so  that  the  matrix  maps  the  channel's 
output  to  the  channel's  boundary  rectangle.  SGSetVi  deoRect  (III— 1816)  modifies  the 
matrix  so  that  the  specified  video  rectangle  appears  in  the  existing  destination 
rectangle. 


SGSetChannelMaxFrames 


Limits  the  number  of  frames  that  the  sequence  grabber  will  capture  from  a  specified 
channel. 

ComponentResul t  SGSetChannelMaxFrames  ( 

SGChannel  c, 

long  frameCount  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 
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III-1777 


SGSetChannelOutput 


f rameCount 

The  maximum  number  of  frames  to  capture  during  the  preview  or  record 
operation.  The  sequence  grabber  component  sets  this  parameter  to  -1  to 
remove  the  limit. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  may  use  this  function  only  after  you  have  prepared  the  sequence  grabber 
component  for  a  record  operation  or  during  an  active  record  operation. 

Special  Considerations 

Note  that  sequence  grabber  components  clear  this  value  when  you  prepare  for  a 
record  operation. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuration  Functions  for  All  Channel  Components" 
(V-2826),  "Working  With  Channel  Characteristics"  (V-2815) 

See  Also 

For  the  corresponding  get  function,  see  SGGetChannel  MaxFrames  (III— 1704). 


SGSetChannelOutput 


Assigns  an  output  to  a  channel. 

ComponentResul t  SGSetChannelOutput  ( 
SeqGrabComponent  s, 

SGChannel  c, 

SGOutput  sgOut  ) ; 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  fromOpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 


III-1778 
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SGSetChannelPlayFlags 


sgOut 

Identifies  the  sequence  grabber  output  for  this  operation.  You  obtain  this 
identifier  by  calling  SGNewOutput  (III— 1757). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Use  this  function  to  assign  an  output  to  a  channel.  One  output  may  be  assigned  to 
one  or  more  channels.  Note  that  when  you  call  SGSetDataRef  (III— 1 787)  or 
SGSetDataOutput  (III— 1785)  the  sequence  grabber  component  sets  every  channel  to 
the  specified  file  or  container.  If  you  want  to  use  different  outputs,  you  must  use  this 
function  to  assign  the  channels  appropriately. 

Version  Notes 

A  sequence  grabber  output  ties  a  sequence  grabber  channel  to  a  specified  data 
reference  for  the  output  of  captured  data.  If  you  are  capturing  to  a  single  movie  file, 
you  can  continue  to  use  SGSetDataOutput  (III— 1785)  or  SGSetDataRef  (III— 1 787)  to 
specify  the  sequence  grabber's  destination.  However,  if  you  want  to  capture  movie 
data  into  several  different  files  or  data  references,  you  must  use  sequence  grabber 
outputs  to  do  so.  Even  if  you  are  using  outputs,  you  must  still  use  SGSetDataOutput 
or  SGSetDataRef  to  identify  where  the  sequence  grabber  should  create  the  movie 
resource.  You  are  responsible  for  creating  outputs,  assigning  them  to  sequence 
grabber  channels,  and  disposing  of  them  when  you  are  done. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Outputs"  (V-2814) 

Related  Java  Methods 

qui cktime . std . sg . SGOutput . setChannel ( ) 


S  G  SetChannelPlay  Flags 


Adjusts  the  speed  and  quality  with  which  the  sequence  grabber  displays  data  from 
a  channel. 

ComponentResul  t  SGSetChannelPlayFlags  ( 

SGChannel  c, 

long  playFlags  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 
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SGSetChannelPlayFlags 


pi  ay  FI ags 

A  long  integer  that  contains  flags  (see  below)  that  influence  channel  playback. 
A  sequence  grabber  component  must  use  one  of  these  values. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

playFlags  Constants 

channel  PI ayNormal 

Your  channel  component  uses  its  default  playback  methodology, 
channel  PI  ay  Fast 

Your  channel  component  sacrifices  playback  quality  to  achieve  the  specified 
playback  rate. 
channelPlayHighQuality 

Your  channel  component  plays  the  channel's  data  at  the  highest  possible 
quality.  This  option  sacrifices  playback  rate  for  the  sake  of  image  quality.  It  may 
reduce  the  amount  of  processor  time  available  to  other  programs  in  the 
computer.  This  option  should  not  affect  the  quality  of  the  recorded  data, 
however. 

channel  PI ayAl 1  Data 

Your  channel  component  tries  to  play  all  of  the  data  it  captures,  even  the  data 
that  is  stored  in  offscreen  buffers.  This  option  is  useful  when  you  want  to  be 
sure  that  the  user  sees  as  much  of  the  captured  data  as  possible.  The  sequence 
grabber  component  sets  this  flag  to  1  to  play  all  the  captured  data.  The  sequence 
grabber  component  may  combine  this  flag  with  any  of  the  other  values  for  the 
pi  ay  FI  ags  parameter. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuration  Functions  for  All  Channel  Components" 
(V-2826),  "Working  With  Channel  Characteristics"  (V-2815) 

Related  Java  Methods 

quicktime.std.sg.SGChannel.setPlayFlagsO 


See  Also 

For  the  corresponding  get  function,  see  SGGetChannel  PI  ayFl  ags  (III— 1705). 
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SGSetChannelRefCon 


SGSetChannelRefCon 


Sets  the  value  of  a  reference  constant  that  is  passed  to  your  callback  functions  for 
channel  components. 

ComponentResul t  SGSetChannelRefCon  ( 

SGChannel  c, 

long  refCon  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

refCon 

A  reference  constant  value  that  your  component  should  pass  to  the  callback 
functions  that  have  been  assigned  to  this  channel.  Use  this  parameter  to  point 
to  a  data  structure  containing  any  information  your  callbacks  need. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuration  Functions  for  All  Channel  Components" 
(V-2826),  "Working  With  Channel  Characteristics"  (V-2815) 


SGSetChannelSettings 


Configures  a  sequence  grabber  channel. 
ComponentResul t  SGSetChannelSettings  ( 


SeqGrabComponent  s, 
SGChannel  c, 

UserData  ud, 

long  flags  ); 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDef  aul  tComponent  (11-1131) 
or  OpenComponent  (11-1130). 
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SGSetChannelUsage 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 
ud 

A  UserDataRecord  (IV-2496)  structure  that  contains  the  configuration 
information  to  be  used  by  the  channel  component. 

fl  ags 

Reserved  for  Apple.  Set  this  parameter  to  0. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Settings"  (V-2812) 

Related  Java  Methods 

quicktime.std.sg.SGChannel .setSettings( ) 

See  Also 

For  the  corresponding  get  function,  see  SGGetChannel  Setti  ngs  (III— 1707). 


S  G  SetChannelU  sage 


Specifies  how  a  channel  is  to  be  used  by  the  sequence  grabber  component. 

ComponentResul t  SGSetChannelUsage  ( 

SGChannel  c, 

1 ong  usage  ) ; 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 

usage 

Contains  flags  (see  below)  specifying  how  your  channel  is  to  be  used.  The 
sequence  grabber  component  may  set  more  than  one  of  these  flags  to  1.  It  sets 
unused  flags  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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S  G  S  etChannel  Volume 


usage  Constants 

seqGrabRecord 

This  flag  is  set  to  1  if  your  channel  is  being  used  for  recording. 
seqGrabPrevi ew 

This  flag  is  set  to  1  if  your  channel  is  being  used  for  previewing. 
seqGrabPl ay Duri ng Record 

This  flag  is  set  to  1  if  your  channel  plays  its  captured  data  during  a  record 
operation. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuration  Functions  for  All  Channel  Components" 
(V-2826),  "Working  With  Channel  Characteristics"  (V-2815) 

Related  Java  Methods 

qui cktime . std . sg . SGChannel . setUsage( ) 


See  Also 

For  the  corresponding  get  function,  see  SGGetChannel  Usage  (III— 1709). 


S  G  SetChannel  V  olume 


Sets  a  channel's  sound  volume. 

ComponentResul t  SGSetChannel Voi ume  ( 
SGChannel  c, 

short  volume  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 
vol ume 

The  volume  setting  of  your  channel  represented  as  a  16-bit,  fixed-point  number. 
The  high-order  8  bits  contain  the  integer  part  of  the  value;  the  low-order  8  bits 
contain  the  fractional  part.  Volume  values  range  from  -1.0  to  1.0.  Negative 
values  play  no  sound  but  preserve  the  absolute  value  of  the  volume  setting. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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SGSetCompressBuffer 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuration  Functions  for  Sound  Channel 
Components"  (V-2831),  "Working  With  Channel  Characteristics"  (V-2815) 

Related  Java  Methods 

quicktime.std.sg.AudioChannel.setVol ume( ) 


See  Also 

For  the  corresponding  get  function,  see  SGGetChannel  Vol  urne  (III— 1710). 


SGSetCompressBuffer 


Allows  the  sequence  grabber  component  to  direct  your  component  to  create  a  filter 
buffer  for  your  video  channel. 

ComponentResul t  SGSetCompressBuffer  ( 

SGChannel  c, 

short  depth, 

const  Rect  *compressSi ze  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 

depth 

The  pixel  depth  of  the  filter  buffer.  If  the  sequence  grabber  sets  this  parameter 
to  0,  use  the  depth  of  the  video  buffer,  which  the  sequence  grabber  sets  with 
SGSetChannel  Bounds  (III — 1 774). 

compressSi ze 

A  pointer  to  a  Rect  (IV-2399)  structure  that  contains  the  dimensions  of  the  filter 
buffer.  This  buffer  should  be  larger  than  the  destination  buffer.  To  stop  filtering 
the  input  source  video  data,  the  sequence  grabber  component  sets  this 
parameter  to  N I L  or  it  sets  the  coordinates  of  this  rectangle  to  0  (specifying  an 
empty  rectangle). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Some  video  source  data  may  contain  unacceptable  levels  of  visual  noise  or  artifacts. 
One  technique  for  removing  this  noise  is  to  capture  the  image  and  then  reduce  it  in 
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SGSetDataOutput 


size.  During  the  size  reduction  process,  the  noise  can  be  filtered  out.  Logically,  this 
buffer  sits  between  the  source  video  buffer  and  the  destination  rectangle  you  set 
with  the  SGSetChannel Bounds  (III— 1774). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuration  Functions  for  Video  Channel 
Components"  (V-2828),  "Working  With  Video  Channels"  (V-2819) 

See  Also 

For  the  corresponding  get  function,  see  SGGetCompressBuffer  (III— 1711). 


SGSetDataOutput 


Specifies  the  movie  file  and  options  for  a  sequence  grabber  record  operation. 

ComponentResul t  SGSetDataOutput  ( 

SeqGrabComponent  s, 

const  FSSpec  *movieFile, 

long  whereFlags  ); 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaul  t  Component  (11-1131) 
or  OpenComponent  (11-1130). 
movi eFi 1 e 

A  pointer  to  the  FSSpec  (IV-2262)  structure  that  identifies  the  movie  file  for  this 
record  operation. 

whereFl  ags 

Contains  flags  (see  below)  that  control  the  record  operation.  You  must  set  either 
seqGrabToDi  sk  flag  or  seqGrabToMemory  to  1.  Set  unused  flags  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

whereFlags  Constants 

seqGrabToDi sk 

Instructs  the  sequence  grabber  component  to  write  the  recorded  data  to  a 
QuickT ime  movie  in  the  movie  file  specified  by  the  m  o  v  i  e  F  i  1  e  parameter.  If  this 
flag  is  set  to  1,  the  sequence  grabber  writes  the  data  to  the  file  as  the  data  is 
recorded. 
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S  G  S  etD  ataOutput 


seqGrabToMemory 

Instructs  the  sequence  grabber  component  to  store  the  recorded  data  in 
memory  until  the  recording  process  is  complete.  The  sequence  grabber  then 
writes  the  recorded  data  to  the  movie  file  specified  by  the  mo v i  e  Fi  1  e  parameter. 
This  technique  provides  better  performance  than  recording  directly  to  the 
movie  file,  but  it  limits  the  amount  of  data  you  can  record.  If  this  flag  is  set  to  1, 
the  sequence  grabber  component  is  recording  to  memory. 
seqGrabDontllseTempMemory 

Prevents  the  sequence  grabber  component  from  using  temporary  memory 
during  the  record  operation.  By  default,  the  sequence  grabber  component  and 
its  channel  components  use  as  much  temporary  memory  as  necessary  to 
perform  the  record  operation.  If  this  flag  is  set  to  1,  the  sequence  grabber 
component  and  its  channel  components  do  not  use  temporary  memory. 

seqGrabAppendToFi 1 e 

Directs  the  sequence  grabber  component  to  add  the  recorded  data  to  the  data 
fork  of  the  movie  file  specified  by  the  movi  eFi  1  e  parameter.  By  default,  the 
sequence  grabber  component  deletes  the  movie  file  and  creates  a  new  file 
containing  one  movie  and  its  movie  resource.  If  this  flag  is  set  to  1,  the  sequence 
grabber  component  appends  the  recorded  data  to  the  data  fork  of  the  movie  file 
and  creates  a  new  movie  resource  in  that  file. 
seqGrabDontAddMovi e Resource 

Prevents  the  sequence  grabber  component  from  adding  the  new  movie 
resource  to  the  movie  file  specified  by  the  movi  eFi  1  e  parameter.  By  default,  the 
sequence  grabber  component  creates  a  new  movie  resource  and  adds  that 
resource  to  the  movie  file.  If  this  flag  is  set  to  1,  the  sequence  grabber 
component  does  not  add  the  movie  resource  to  the  movie  file.  You  are  then 
responsible  for  adding  the  resource  to  a  file,  if  you  so  desire 
seqGrabDontMakeMovi e 

Prevents  the  sequence  grabber  component  from  creating  a  movie.  By  default, 
the  sequence  grabber  component  creates  a  new  movie  resource  and  adds  the 
captured  data  to  that  movie.  If  this  flag  is  set  to  1,  the  sequence  grabber  still  calls 
your  data  function,  but  does  not  write  any  data  to  the  movie  file. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuring  Sequence  Grabber  Components"  (V-2809) 

Related  Java  Methods 

quicktime.std.sg.SequenceGrabber.setDataOutputO 
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SGSetDataProc 


See  Also 

For  the  corresponding  get  function,  see  SGGetDataOutput  (III— 1711). 


SGSetDataProc 


Specifies  a  data  function  for  use  by  the  sequence  grabber. 

ComponentResul t  SGSetDataProc  ( 

SeqGrabComponent  s, 

SGDataUPP  proc, 

long  refCon  ); 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaul  t  Component  (11-1131) 
or  OpenComponent  (11-1130). 

proc 

A  pointer  to  your  data  function.  To  remove  your  data  function,  set  this 
parameter  to  NIL. 

refCon 

A  reference  constant.  The  sequence  grabber  provides  this  value  to  your  data 
callback.  Use  this  parameter  to  point  to  a  data  structure  containing  any 
information  your  function  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuring  Sequence  Grabber  Components"  (V-2809) 


SGSetDataRef 


Specifies  the  destination  data  reference  for  a  record  operation. 

ComponentResul t  SGSetDataRef  ( 

SeqGrabComponent  s. 

Handle  dataRef, 

OSType  dataRefType, 

long  whereFlags  ); 
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SGSetDataRef 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 
dataRef 

A  handle  to  the  information  that  identifies  the  destination  container. 
dataRefType 

The  type  of  data  reference.  If  the  data  reference  is  an  alias,  you  must  set  the 
parameter  to  rAl  i  asType. 
whereFl  ags 

Contains  flags  (see  below)  that  control  the  record  operation.  You  must  set  either 
seqGrabToDi  sk  or  seqGrabToMemory  to  1.  Set  unused  flags  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

whereFlags  Constants 

seqGrabToDi sk 

Instructs  the  sequence  grabber  component  to  write  the  recorded  data  to  a 
QuickTime  movie  in  the  movie  file  specified  by  the  movi  eFi  1  e  parameter.  If  this 
flag  is  set  to  1,  the  sequence  grabber  writes  the  data  to  the  file  as  the  data  is 
recorded. 

seqGrabToMemory 

Instructs  the  sequence  grabber  component  to  store  the  recorded  data  in 
memory  until  the  recording  process  is  complete.  The  sequence  grabber  then 
writes  the  recorded  data  to  the  movie  file  specified  by  the  mo v i  e  Fi  1  e  parameter. 
This  technique  provides  better  performance  than  recording  directly  to  the 
movie  file,  but  it  limits  the  amount  of  data  you  can  record.  If  this  flag  is  set  to  1, 
the  sequence  grabber  component  is  recording  to  memory. 
seqGrabDontUseTempMemory 

Prevents  the  sequence  grabber  component  from  using  temporary  memory 
during  the  record  operation.  By  default,  the  sequence  grabber  component  and 
its  channel  components  use  as  much  temporary  memory  as  necessary  to 
perform  the  record  operation.  If  this  flag  is  set  to  1,  the  sequence  grabber 
component  and  its  channel  components  do  not  use  temporary  memory. 
seqGrabAppendToFi 1 e 

Directs  the  sequence  grabber  component  to  add  the  recorded  data  to  the  data 
fork  of  the  movie  file  specified  by  the  movi  eFi  1  e  parameter.  By  default,  the 
sequence  grabber  component  deletes  the  movie  file  and  creates  a  new  file 
containing  one  movie  and  its  movie  resource.  If  this  flag  is  set  to  1,  the  sequence 
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grabber  component  appends  the  recorded  data  to  the  data  fork  of  the  movie  file 
and  creates  a  new  movie  resource  in  that  file. 

seqGrabDontAddMovi e Resource 

Prevents  the  sequence  grabber  component  from  adding  the  new  movie 
resource  to  the  movie  file  specified  by  the  movi  eFi  1  e  parameter.  By  default,  the 
sequence  grabber  component  creates  a  new  movie  resource  and  adds  that 
resource  to  the  movie  file.  If  this  flag  is  set  to  1,  the  sequence  grabber 
component  does  not  add  the  movie  resource  to  the  movie  file.  You  are  then 
responsible  for  adding  the  resource  to  a  file,  if  you  so  desire 

seqGrabDontMakeMovi e 

Prevents  the  sequence  grabber  component  from  creating  a  movie.  By  default, 
the  sequence  grabber  component  creates  a  new  movie  resource  and  adds  the 
captured  data  to  that  movie.  If  this  flag  is  set  to  1,  the  sequence  grabber  still  calls 
your  data  function,  but  does  not  write  any  data  to  the  movie  file. 

Discussion 

This  function  allows  you  to  specify  the  destination  for  a  record  operation  using  a 
data  reference,  and  to  specify  other  options  that  govern  the  operation.  This  function 
is  similar  to  SGSetDataOutput  (III— 1785),  and  provides  you  with  an  alternative  way 
to  specify  the  destination. 

Special  Considerations 

If  you  are  performing  a  preview  operation,  you  don't  need  to  use  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuring  Sequence  Grabber  Components"  (V-2809) 

Related  Java  Methods 

qui cktime . std . sg . SequenceGrabber . set Data  Ref ( ) 


See  Also 

For  the  corresponding  get  function,  see  SGGetDataRef  (III— 1716). 


SGSetFlags 


Passes  control  information  about  the  current  operation  to  the  sequence  grabber 
component. 

ComponentResul t  SGSetFlags  ( 

SeqGrabComponent  s. 
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SGSetFontName 


I  ong 


sgFlags  ); 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  fromOpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 

sgFl  ags 

Contains  a  flag  (see  below)  to  tell  the  sequence  grabber  if  you  are  performing  a 
controlled  grab  using  a  frame-addressable  source  device. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

sgFlags  Constant 

sgFlagControlledGrab 

Set  this  flag  to  1  if  you  are  performing  a  controlled  grab  using  a 
frame-addressable  source  device.  The  sequence  grabber  and  its  channel 
components  optimize  their  operation  for  this  situation.  This  flag  allows  the 
sequence  grabber  component  to  trade  off  speed  and  quality. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Characteristics" 
(V-2813) 

See  Also 

For  the  corresponding  get  function,  see  SGGetFl ags  (III— 1718). 


SGSetFontName 


Sets  the  name  of  the  font  to  be  used  to  display  text  for  a  text  channel  component. 

ComponentResul t  SGSetFontName  ( 

SGChannel  c, 

Stri ngPtr  pstr  ) ; 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

pstr 

A  pointer  to  a  Pascal  string  containing  the  name  of  the  font. 
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function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

If  the  specified  font  is  available  on  the  system,  the  text  channel  uses  the  font  to 
display  text.  If  the  specified  font  is  not  available,  the  text  channel  uses  the  default 
system  font.  For  more  information  about  fonts,  see  Inside  Macintosh:  Text  (listed  in 

the  bibliography). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Text  Channel  Support"  (V-2874) 

Related  Java  Methods 

qui  cktime .  std  .  sg  .  SGTextChannel  .setFontNameO 


SGSetFontSize 


Sets  the  font  size  to  be  used  to  display  text  for  a  text  channel  component. 

ComponentResul t  SGSetFontSize  ( 

SGChannel  c, 

short  fontSize  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 
f ontSi ze 

The  point  size  of  the  font.  This  value  must  be  a  positive  integer. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Text  Channel  Support"  (V-2874) 

Related  Java  Methods 

qui cktime . std . sg . SGTextChannel . setFontSi  ze( ) 
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See  Also 

For  more  information  about  fonts  and  font  sizes,  see  Inside  Macintosh:  Text  (listed  in 

the  bibliography). 


SGSetFrameRate 


Specifies  a  video  channel's  frame  rate  for  recording. 

ComponentResul t  SGSetFrameRate  ( 

SGChannel  c, 

Fi xed  f rameRate  ) ; 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 
f rameRate 

The  desired  frame  rate.  If  this  parameter  is  set  to  0,  use  your  channel's  default 
frame  rate.  Typically,  this  corresponds  to  the  fastest  rate  that  your  channel  can 
support. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuration  Functions  for  Video  Channel 
Components"  (V-2828),  "Working  With  Video  Channels"  (V-2819) 

See  Also 

For  the  corresponding  get  function,  see  SGGetFrameRate  (III— 1719). 


SGSetGWorld 


Establishes  the  graphics  port  and  device  for  a  sequence  grabber  component. 

ComponentResul t  SGSetGWorld  ( 

SeqGrabComponent  s, 

CGrafPtr  gp, 

GDHandl e  gd  ) ; 
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s 

An  instance  of  the  sequence  grabber  component  connected  to  your  channel 
component.  The  sequence  grabber  component  provides  this  value  through 
SGIni tChannel  (III — 1751). 

9P 

The  destination  graphics  port,  which  must  be  a  color  graphics  port.  The 
sequence  grabber  component  always  sets  this  parameter  to  a  valid  value.  To 
use  the  current  graphics  port,  the  parameter  is  set  to  NIL. 

gd 

A  handle  to  the  destination  graphics  device.  The  sequence  grabber  component 
always  sets  this  parameter  to  a  valid  value. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  must  call  this  function  if  you  are  working  with  any  channels  that  collect  visual 
data.  If  you  are  working  only  with  data  that  has  no  visual  representation,  you  do 
not  need  to  call  this  function.  The  sequence  grabber  component  performs  this 
operation  implicitly  when  you  call  SGInitialize  (III— 1 752)  and  the  component  uses 
your  application's  current  graphics  port.  To  set  it  to  a  specified  window,  use  code 
such  as  the  following: 

//  SGSetGWorld  coding  example 

//  See  “Discovering  QuickTime,”  page  262 

SeqGrabComponent  MakeMySequenceGrabber  (WindowPtr  pMacWnd) 

{ 

SeqGrabComponent  seqGrab  =  NIL; 

OSErr  nErr  =  noErr; 

//  open  the  default  sequence  grabber 

seqGrab  =  OpenDef aul tComponent( SeqGrabComponentType ,  0); 
if  (seqGrab  !=  NIL)  { 

//  initialize  the  default  sequence  grabber  component 
nErr  =  SGIni ti al i ze( seqGrab) ; 

if  (nErr  ==  noErr)  { 

//  set  its  graphics  world  to  the  specified  window 

nErr  =  SGSetGWorld(seqGrab,  (CGraf Ptr)pMacWnd ,  NIL); 

} 

} 

if  (nErr  &&  (seqGrab  !=  NIL))  {  //  clean  up  on  failure 
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CloseComponent(seqGrab) ; 
seqGrab  =  NIL; 

} 

return  seqGrab; 

} 

Special  Considerations 

You  cannot  call  this  function  during  a  record  or  preview  operation,  or  after  you 
have  prepared  the  sequence  grabber  component  for  a  record  or  preview  operation 
by  calling  SGPrepare  (III— 1772).  The  window  in  which  the  sequence  grabber  is  to 
draw  video  frames  as  defined  by  this  function  must  be  visible  before  you  call 
SGPrepare;  otherwise,  the  sequence  grabber  does  not  display  the  frames  properly. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuring  Sequence  Grabber  Channel  Components" 
(V-2824),  "Configuring  Sequence  Grabber  Components"  (V-2809) 

Related  Java  Methods 

quicktime.std.sg.SequenceGrabber.setGWorldt) 


See  Also 

For  the  corresponding  get  function,  see  SGGetGWorl  d  (III— 1719). 


SGSetlnstrument 


Sets  a  tone  description  for  a  music  sequence  grabber  channel. 

ComponentResult  SGSetlnstrument  ( 

SGChannel  c, 

ToneDescripti on  *td  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 

td 

Pointer  to  a  ToneDescri  pti  on  (IV-2487)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Related  Java  Methods 

qui cktime . std . sg . SGMusi cChannel . set  I  instrument! ) 

See  Also 

For  the  corresponding  get  function,  see  SGGetlnstrument  (III— 1721). 


SGSetJustification 


Sets  the  alignment  to  be  used  to  display  text  for  a  text  channel  component. 

ComponentResul t  SGSetJustification  ( 

SGChannel  c, 

short  just  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

just 

A  constant  (see  below)  that  represents  the  text  alignment. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

just  Constants 

teFl ushDefaul t 

Default  alignment  according  to  the  primary  line  direction. 
teCenter 

Center  for  all  scripts. 
teFl  ushRi  ght 

Right  alignment  for  all  scripts. 
teFl  ushLeft 

Left  alignment  for  all  scripts. 

Discussion 

You  call  this  function  to  specify  the  alignment  to  be  used  for  text  in  a  text  track.  The 
text  channel  component  justifies  text  relative  to  the  boundaries  of  its  text  box. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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Programming  Info 

C  interface  file:  QuickTimeComponents.h 

Programming  summary:  "Text  Channel  Support"  (V-2874) 

Related  Java  Methods 

qui ckti me . std . sg . SGTextChannel . setJusti f i cati on ( ) 


See  Also 

For  more  information  on  text  alignment  and  the  text  justification  constants,  see 
Inside  Macintosh:  Text  (listed  in  the  bibliography). 


SGSetMaximumRecordTime 


Limits  the  duration  of  a  record  operation 

ComponentResul t  SGSetMaxi mumRecordTi me  ( 
SeqGrabComponent  s, 

unsigned  long  ticks  ); 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  fromOpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 

ticks 

The  maximum  duration  for  the  record  operation,  in  system  ticks  (sixtieths  of  a 
second).  Set  this  parameter  to  0  to  remove  the  time  limit  from  the  operation. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

By  default,  there  is  no  time  limit  on  a  record  operation.  If  you  do  not  set  a  limit,  a 
record  operation  will  run  until  it  exhausts  the  Operating  System  resources  or  you 
call  SGStop  (III— 1819).  Memory  and  disk  space  are  the  two  major  limiting  factors. 

Special  Considerations 

You  must  call  this  function  before  you  start  a  sequence  grabber  record  operation. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Characteristics" 
(V-2813) 
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Related  Java  Methods 

qui cktime . std . sg . SequenceGrabber . setMaxi mumRecordTi me( ) 

See  Also 

For  the  corresponding  get  function,  see  SGGetMaxi  mumRecordT i  me  (III— 1723). 


SGSetOutputFlags 


Configures  an  existing  sequence  grabber  output. 

ComponentResul t  SGSetOutputFlags  ( 

SeqGrabComponent  s, 

SGOutput  sgOut, 

long  whereFlags  ); 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaul  t  Component  (11-1131) 
or  OpenComponent  (11-1130). 

sgOut 

Identifies  the  sequence  grabber  output  for  this  operation.  You  obtain  this 
identifier  by  calling  SGNewOutput  (III— 1757). 
whereFl  ags 

Contains  flags  (see  below)  that  control  the  record  operation.  You  must  set  either 
seqGrabToDi  sk  or  seqGrabToMemory  to  1.  Set  unused  flags  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

whereFlags  Constants 

seqGrabToDi sk 

Instructs  the  sequence  grabber  component  to  write  the  recorded  data  to  a 
QuickT ime  movie  in  the  movie  file  specified  by  the  m  o  v  i  e  F  i  1  e  parameter.  If  this 
flag  is  set  to  1,  the  sequence  grabber  writes  the  data  to  the  file  as  the  data  is 
recorded. 

seqGrabToMemory 

Instructs  the  sequence  grabber  component  to  store  the  recorded  data  in 
memory  until  the  recording  process  is  complete.  The  sequence  grabber  then 
writes  the  recorded  data  to  the  movie  file  specified  by  the  movi  eFi  1  e  parameter. 
This  technique  provides  better  performance  than  recording  directly  to  the 
movie  file,  but  it  limits  the  amount  of  data  you  can  record.  If  this  flag  is  set  to  1, 
the  sequence  grabber  component  is  recording  to  memory. 
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seqGrabDontUseTempMemory 

Prevents  the  sequence  grabber  component  from  using  temporary  memory 
during  the  record  operation.  By  default,  the  sequence  grabber  component  and 
its  channel  components  use  as  much  temporary  memory  as  necessary  to 
perform  the  record  operation.  If  this  flag  is  set  to  1,  the  sequence  grabber 
component  and  its  channel  components  do  not  use  temporary  memory. 
seqGrabAppendToFi 1 e 

Directs  the  sequence  grabber  component  to  add  the  recorded  data  to  the  data 
fork  of  the  movie  file  specified  by  the  movi  eFi  1  e  parameter.  By  default,  the 
sequence  grabber  component  deletes  the  movie  file  and  creates  a  new  file 
containing  one  movie  and  its  movie  resource.  If  this  flag  is  set  to  1,  the  sequence 
grabber  component  appends  the  recorded  data  to  the  data  fork  of  the  movie  file 
and  creates  a  new  movie  resource  in  that  file. 

seqGrabDontAddMovi e Resource 

Prevents  the  sequence  grabber  component  from  adding  the  new  movie 
resource  to  the  movie  file  specified  by  the  movi  eFi  1  e  parameter.  By  default,  the 
sequence  grabber  component  creates  a  new  movie  resource  and  adds  that 
resource  to  the  movie  file.  If  this  flag  is  set  to  1,  the  sequence  grabber 
component  does  not  add  the  movie  resource  to  the  movie  file.  You  are  then 
responsible  for  adding  the  resource  to  a  file,  if  you  so  desire 
seqGrabDontMakeMovi e 

Prevents  the  sequence  grabber  component  from  creating  a  movie.  By  default, 
the  sequence  grabber  component  creates  a  new  movie  resource  and  adds  the 
captured  data  to  that  movie.  If  this  flag  is  set  to  1,  the  sequence  grabber  still  calls 
your  data  function,  but  does  not  write  any  data  to  the  movie  file. 

Discussion 

This  function  lets  you  configure  an  existing  sequence  grabber  output. 

Version  Notes 

A  sequence  grabber  output  ties  a  sequence  grabber  channel  to  a  specified  data 
reference  for  the  output  of  captured  data.  If  you  are  capturing  to  a  single  movie  file, 
you  can  continue  to  use  SGSetDataOutput  (III— 1 785)  or  SGSetDataRef  (III— 1787)  to 
specify  the  sequence  grabber's  destination.  However,  if  you  want  to  capture  movie 
data  into  several  different  files  or  data  references,  you  must  use  sequence  grabber 
outputs  to  do  so.  Even  if  you  are  using  outputs,  you  must  still  use  SGSetDataOutput 
or  SGSetDataRef  to  identify  where  the  sequence  grabber  should  create  the  movie 
resource.  You  are  responsible  for  creating  outputs,  assigning  them  to  sequence 
grabber  channels,  and  disposing  of  them  when  you  are  done. 


III-1798 


Inside  QuickTime:  Functions  R-Z 


S  G  S  etOutputMaximumO  f  f  s  et 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Outputs"  (V-2814) 

Related  Java  Methods 

qui cktime . std . sg . SGOutput . setOutputFl ags ( ) 


SGSetOutputMaximumOffset 


Specifies  the  maximum  offset  for  data  written  to  a  specified  sequence  grabber 
output. 

ComponentResul t  SGSetOutputMaximumOffset  ( 

SeqGrabComponent  s, 

SGOutput  sgOut, 

const  wide  *maxOffset  ); 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaul  t  Component  (11-1131) 
or  OpenComponent  (11-1130). 

sgOut 

Identifies  the  current  sequence  grabber  output.  You  obtain  this  identifier  by 
calling  SGNewOutput  (III— 1757). 
maxOf f set 

A  pointer  to  the  value  of  the  maximum  offset  for  data  written  to  this  output. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  an  error  if  no  more  outputs  are 
available.  Returns  noErr  if  there  is  no  error. 

Discussion 

If  an  attempt  is  made  to  write  data  beyond  the  maximum  offset,  the  sequence 
grabber  switches  to  the  next  output  specified  by  SGSetOutputNextOutput  (III— 1800). 
If  no  more  outputs  are  available,  an  end-of-file  error  is  returned  and  recording  ends. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Outputs"  (V-2814) 

Related  Java  Methods 

qui cktime . std . sg . SGOutput . setMaxi mumOf f set( ) 
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See  Also 

For  the  corresponding  get  function,  see  SGGetOutputMaximumOffset  (III— 1728). 


SGSetOutputNextOutput 


Specifies  the  order  in  which  sequence  grabber  outputs  should  be  used. 

ComponentResul t  SGSetOutputNextOutput  ( 

SeqGrabComponent  s, 

SGOutput  sgOut, 

SGOutput  nextOut  ) ; 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  fromOpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 

sgOut 

The  current  output  to  use.  When  a  new  output  is  created,  its  nextOut  is  set  to 
NIL. 

nextOut 

The  next  output  to  be  used.  To  specify  that  this  is  the  last  output,  set  this  value 
to  NIL. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  should  not  be  called  while  recording. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Outputs"  (V-2814) 

Related  Java  Methods 

qu i c kti me. std.sg. SGOutput . setNextOutput ( ) 


See  Also 

For  the  corresponding  get  function,  see  SGGetOutputNextOutput  (III— 1729). 
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SGSetPreferredPacketSize 


Sets  the  preferred  packet  size  for  the  sequence  grabber  channel  component. 

ComponentResul t  SGSetPreferredPacketSize  ( 

SGChannel  c, 

long  preferredPacketSizelnBytes  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

preferredPacketSi zelnBytes 

The  preferred  packet  size  in  bytes. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

This  function  was  added  in  QuickTime  2.5  to  support  video  conferencing 
applications. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Utility  Functions  for  Sequence  Grabber  Channel 
Components"  (V-2833) 

See  Also 

For  the  corresponding  get  function,  see  SGGetPreferredPacketSi  ze  (III— 1730). 


SGSetSettings 


Configures  a  sequence  grabber  and  its  channels. 

ComponentResul t  SGSetSettings  ( 
SeqGrabComponent  s, 

UserData  ud, 

long  flags  ); 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDef  aul  tComponent  (11-1131) 
or  OpenComponent  (11-1130). 
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ud 

A  UserDataRecord  (IV-2496)  structure  that  contains  the  configuration 
information  to  be  used  by  the  sequence  grabber, 
fl  ags 

Reserved  for  Apple.  Set  this  parameter  to  0. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  sequence  grabber  disposes  of  any  of  its  current  channels  before  applying  this 
configuration  information.  It  then  opens  connections  to  new  channels  as 
appropriate. 

Special  Considerations 

You  can  restore  saved  settings  by  using  NewUserDataFromHandl  e  (11-1124). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Settings"  (V-2812) 

Related  Java  Methods 

qui ckti me . std . sg . SequenceGrabber . setSetti ngs ( ) 


See  Also 

You  may  use  the  SGGetlndChannel  (III— 1720)  function  to  obtain  information  about 
each  channel  that  the  sequence  grabber  is  using  as  a  result  of  applying  this  new 
configuration. 


SGSetSoundlnputDriver 


Assigns  a  sound  input  device  to  a  sound  channel. 

ComponentResul t  SGSetSoundlnputDriver  ( 
SGChannel  c, 

ConstStr255Param  driverName  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 
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dri verName 

The  name  of  the  sound  input  device.  This  is  a  Pascal  string,  and  it  must 
correspond  to  a  valid  sound  input  device. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuration  Functions  for  Sound  Channel 
Components"  (V-2831),  "Working  With  Sound  Channels"  (V-2821) 

Related  Java  Methods 

quicktime.std.sg.SGSoundChannel.setlnputDriverO 


See  Also 

For  the  corresponding  get  function,  see  SGGetSoundlnputDri  ver  (III— 1732). 


SGSetSoundlnputParameters 


Sets  various  parameters  that  relate  to  sound  recording. 


Component Res ul t  SGSetSoundlnputParameters 
SGChannel  c, 

short  sampleSize, 

short  numChannels, 

OSType  compressi onType  ); 


( 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

sampl eSi ze 

The  number  of  bits  in  each  sound  sample.  This  field  is  set  to  8  for  8-bit  sound; 
it  is  set  to  16  for  16-bit  sound. 

numChannel s 

Indicates  the  number  of  sound  channels  to  be  used  by  the  sound  sample.  This 
field  is  set  to  1  for  monaural  sounds;  it  is  set  to  2  for  stereo  sounds, 
compressi onType 

A  constant  (see  below)  that  describes  the  format  of  the  sound  data. 
function  result  See  "Error  Codes"  (IV-2663).  If  your  sound  device  cannot  support  a 
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SGSetSoundlnputRate 


specified  parameter  value,  return  an  appropriate  Sound  Manager 
result  code.  Return  noErr  if  there  is  no  error. 

compressionType  Constants 

'  raw  ' 

Sound  samples  uncompressed,  in  offset-binary  format  (that  is,  sample  data 
values  range  from  0  to  255). 

'  MAC3 ' 

Sound  samples  compressed  by  the  Sound  Manager  at  a  ratio  of  3:1. 

' MAC6 ' 

Sound  samples  compressed  by  the  Sound  Manager  at  a  ratio  of  6:1. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuration  Functions  for  Sound  Channel 
Components"  (V-2831),  "Working  With  Sound  Channels"  (V-2821) 

Related  Java  Methods 

quicktime.std.sg.SGSoundChannel .setSoundlnputParameterst ) 


See  Also 

For  the  corresponding  get  function,  see  SGGetSoundlnputParameters  (III— 1733). 


SGSetSoundlnputRate 


Sets  the  rate  at  which  the  sound  channel  obtains  its  sound  data. 

ComponentResul t  SGSetSoundlnputRate  ( 

SGChannel  c, 

Fi  xed  rate  ) ; 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 

rate 

The  rate  at  which  your  sound  channel  is  to  acquire  data.  This  parameter 
specifies  the  number  of  samples  your  sound  channel  is  to  generate  per  second. 
If  your  sound  channel  cannot  support  the  specified  rate,  use  the  closest 
available  rate  that  you  can  support.  If  this  parameter  is  set  to  0,  use  your  default 
rate. 
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function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuration  Functions  for  Sound  Channel 
Components"  (V-2831),  "Working  With  Sound  Channels"  (V-2821) 

Related  Java  Methods 

quicktime.std.sg.SGSoundChannel.setSoundlnputRateC) 


See  Also 

For  the  corresponding  get  function,  see  SGGetSoundlnputRate  (III— 1734). 


SGSetSoundRecordChunkSize 


Controls  the  amount  of  sound  data  in  each  group  of  sound  samples  during  a  record 
operation. 

ComponentResul t  SGSetSoundRecordChunkSize  ( 

SGChannel  c, 

long  seconds  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 
seconds 

The  number  of  seconds  of  sound  data  your  sound  channel  component  is  to 
work  with  at  a  time.  This  parameter  is  set  to  a  negative  fixed-point  number  to 
specify  a  fraction  of  a  second.  For  example,  to  set  the  duration  to  half  a  second, 
-0.5  is  passed  in. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

During  record  operations,  the  sequence  grabber  component  and  its  sound  channels 
work  with  groups  of  sound  samples,  referred  to  as  chunks.  By  default,  each  chunk 
contains  two  seconds  of  sound  data.  Smaller  chunks  use  less  memory. 

Special  Considerations 

This  function  may  return  a  fraction. 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuration  Functions  for  Sound  Channel 
Components"  (V-2831),  "Working  With  Sound  Channels"  (V-2821) 

Related  Java  Methods 

quicktime.std.sg.SGSoundChannel .setRecordChunkSizet ) 


See  Also 

For  the  corresponding  get  function,  see  SGGetSoundRecordChunkSi  ze  (III— 1734). 


SGSetTextBackColor 


Sets  the  background  color  to  be  used  for  the  text  box. 

ComponentResul t  SGSetTextBackColor  ( 

SGChannel  c, 

RGBColor  *theColor  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 
theCol or 

A  pointer  to  an  RGBCol  or  (IV-2403)  structure  that  contains  the  new  background 
color. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  call  this  function  to  set  the  background  color  of  a  text  track.  The  text  channel 
component  uses  the  specified  color  as  the  background  of  the  text  box. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Text  Channel  Support"  (V-2874) 

Related  Java  Methods 

quicktime.std.sg.SGTextChannel .setBackColort ) 
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SGSetTextForeColor 


Sets  the  color  to  be  used  to  display  text. 

ComponentResul t  SGSetTextForeCol or  ( 
SGChannel  c, 

RGBColor  *theColor  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

theCol or 

A  pointer  to  an  RGBColor  (IV-2403)  structure  that  contains  the  new  text  color. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  call  this  function  to  set  the  text  color  for  a  text  track. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Text  Channel  Support"  (V-2874) 

Related  Java  Methods 

qui cktime . std . sg . SGTextChannel . setForeCol or( ) 


SGSetT  extReturnT  oSpace  V  alue 


Determines  whether  the  text  channel  component  should  replace  return  characters 
with  spaces. 

ComponentResul t  SGSetTextReturnToSpaceVal ue  ( 

SGChannel  c, 

short  rettospace  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

rettospace 

Set  this  parameter  to  TRUE  if  the  text  channel  should  replace  return  characters 
with  spaces,  or  FALSE  otherwise. 
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SGSettingsDialog 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

When  you  capture  text  from  a  closed-caption  television  source,  the  text  is  composed 
of  four  lines  of  text  of  up  to  32  characters  each,  each  line  separated  by  a  return 
character.  You  can  call  this  function  to  request  that  the  text  channel  component 
replace  the  return  characters  with  spaces. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Text  Channel  Support"  (V-2874) 

Related  Java  Methods 

qui ckti me . std . sg . SGTextChannel .setReturnToSpaceValuet ) 


See  Also 

For  the  corresponding  get  function,  see  SGGetTextReturnToSpaceVal  ue  (III— 1737). 


SGSettingsDialog 


Causes  a  sequence  grabber  to  display  its  settings  dialog  box  to  the  user. 


ComponentResul t  SGSettingsDialog  ( 


SeqGrabComponent 

SGChannel 

short 

Con st Component  Li stPtr 
1  ong 

SGModal FilterUPP 
1  ong 


s , 
c , 

numPanel s , 
panel  Li  st , 
fl ags , 
proc , 

procRef Num 


The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaultComponent  (II— 1 131) 
or  OpenComponent  (11-1130). 
c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 

numPanel s 

The  number  of  panel  components  to  be  listed  in  the  panel  component  pop-up 
menu.  You  specify  the  panel  components  with  the  panel  Li  st  parameter.  You 
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may  use  these  parameters  to  limit  the  user's  choice  of  panel  components.  If  you 
set  this  parameter  to  0  and  the  panel  Li  st  parameter  to  NIL,  the  sequence 
grabber  lists  all  available  panel  components. 

panel  Li  st 

A  pointer  to  an  array  of  component  identifiers.  The  sequence  grabber  presents 
only  these  components  in  the  panel  component  pop-up  menu.  You  specify  the 
number  of  identifiers  in  the  array  with  the  numPanels  parameter.  If  you  set  this 
parameter  to  NIL,  the  sequence  grabber  lists  all  available  panel  components. 

fl  ags 

Either  set  this  to  0  or  to  seqGrabSettingsPrevi  ewOnly  (see  below). 

proc 

Specifies  an  SGModal  Fi  1  terProc  (III— 2144)  callback.  Because  the  sequence 
grabber's  settings  dialog  box  is  a  movable  modal  dialog  box,  you  must  supply 
an  event  filter  function  to  process  update  events  in  your  window. 

procRef Num 

A  reference  constant  to  be  passed  to  your  filter  callback.  Use  this  parameter  to 
point  to  a  data  structure  containing  any  information  your  function  needs. 

function  result  See  "Error  Codes"  (IV-2663).  If  the  user  clicks  OK  and  the  settings 
are  acceptable  to  the  panel  and  channel  components,  this  function 
returns  a  result  code  of  noErr. 

flags  Constant 

seqGrabSetti ngsPrevi ewOnly 

Set  this  flag  to  indicate  that  the  user  will  be  using  the  dialog  box  provided  by 
this  function  to  configure  the  sequence  grabber  for  previewing  only,  not  for 
recording.  This  function  automatically  excludes  any  panels  that  aren't 
necessary  for  preview  configuring,  such  as  video  or  audio  compression 
settings.  Use  this  flag  for  applications  that  allow  a  live  video  signal  to  be  viewed 
but  not  captured. 

Discussion 

Because  the  user  may  change  several  channel  configuration  parameters,  your 
application  should  retrieve  new  configuration  information  from  the  channel  so  that 
you  can  update  any  values  you  save,  such  as  the  channel's  display  boundaries  or 
the  channel  device.  In  particular,  the  video  rectangle  for  the  channels  may  have  to 
be  adjusted. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Working  With  Sequence  Grabber  Settings"  (V-2812) 
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Related  Java  Methods 

quicktime.std.sg.SGChannel .settlngsDialogt ) 


SGSetUserVideoCompressorList 


Specifies  the  list  of  video  compression  formats  to  be  included  in  the  sequence 
grabber's  video  settings  dialog  box. 

ComponentResult  SGSetUserVideoCompressorList  ( 

SGChannel  c, 

Handle  compressorTypes  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 
compressorTypes 

A  handle  containing  a  list  of  OSTy  pe  values  indicating  which  video  compression 
formats  should  be  displayed.  See  "Codec  Identifiers"  (IV-2655).  The  sequence 
grabber  channel  determines  the  number  of  video  compression  formats 
contained  in  the  handle  based  on  the  size  of  the  handle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  lets  an  application  limit  the  number  of  video  compression  formats 
that  will  be  displayed  to  the  user.  For  applications  using  the  sequence  grabber  for  a 
very  specific  purpose,  this  function  allows  inappropriate  compression  choices  to  be 
filtered  out. 

Special  Considerations 

The  sequence  grabber  channel  makes  a  copy  of  the  video  compression  formats 
handle.  Therefore,  your  application  can  immediately  dispose  of  the  video 
compression  formats  handle  after  making  this  call. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Utility  Functions  for  Sequence  Grabber  Channel 
Components"  (V-2833) 

See  Also 

For  the  corresponding  get  function,  see  SGGetUserVi  deoCompressorLi  st  (III— 1740). 
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SGSetUseScreenBuffer 


Controls  whether  a  video  channel  uses  an  offscreen  buffer. 

ComponentResul t  SGSetUseScreenBuffer  ( 

SGChannel  c. 

Boolean  useScreenBuf fer  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

useScreenBuf fer 

Indicates  whether  to  use  an  offscreen  buffer.  If  this  parameter  is  set  to  TRUE, 
draw  directly  to  the  screen.  If  it  is  set  to  FALSE,  your  channel  may  use  an 
offscreen  buffer.  If  your  channel  cannot  work  with  offscreen  buffers,  ignore  this 
parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Directing  a  channel  to  draw  offscreen  may  be  useful  if  you  are  performing 
transformations  on  the  data  before  displaying  it  (such  as  blending  it  with  another 
graphical  image). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuration  Functions  for  Video  Channel 
Components"  (V-2828),  "Working  With  Video  Channels"  (V-2819) 

See  Also 

For  the  corresponding  get  function,  see  SGGetUseScreenBuffer  (III— 1740). 


SGSetVideoBottlenecks 


Assigns  callback  functions  to  a  video  channel. 

ComponentResul t  SGSetVideoBottlenecks  ( 
SGChannel  c, 

VideoBottles  *vb  ); 
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c 

The  connection  identifier  for  the  video  channel  for  this  operation.  You  get  this 
value  from  SGNewChannel  (III— 1 753)  or  SGNewChannel  FromComponent  (III— 1756). 
vb 

A  pointer  toaVideoBottles  (IV-2501)  structure,  which  identifies  the  callback 
functions  to  be  assigned  to  the  video  channel. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Video  Channel  Callback  Functions"  (V-2823) 

See  Also 

For  the  corresponding  get  function,  see  SGGetVi  deoBottl  enecks  (III— 1741). 


SGSetVideoCompressor 


Specifies  many  of  the  parameters  that  control  image  compression  of  the  video  data 
captured  by  a  video  channel. 

ComponentResul t  SGSetVideoCompressor  ( 

SGChannel  c, 

short  depth, 

CompressorComponent  compressor, 

CodecQ  spati al Qual i ty , 

CodecQ  temporal Qual i ty , 

1 ong  keyFrameRate  ) ; 


c 

The  connection  identifier  for  the  video  channel  for  this  operation.  You  get  this 
value  from  SGNewChannel  (III— 1 753)  or  SGNewChannel  FromComponent  (III— 1756). 
depth 

The  depth  at  which  the  image  is  likely  to  be  viewed.  Image  compressors  may 
use  this  as  an  indication  of  the  color  or  grayscale  resolution  of  the  compressed 
images.  If  the  sequence  grabber  component  sets  this  parameter  to  0,  let  the 
sequence  grabber  component  determine  the  appropriate  value  for  the  source 
image.  Values  of  1, 2, 4, 8, 16, 24,  and  32  indicate  the  number  of  bits  per  pixel  for 
color  images.  Values  of  33,  34, 36,  and  40  indicate  1-bit,  2-bit,  4-bit,  and  8-bit 
grayscale,  respectively,  for  grayscale  images.  Your  component  can  determine 


III-1812 


Inside  QuickTime:  Functions  R-Z 


SGSetVideoCompressor 


which  depths  are  supported  by  a  given  compressor  by  examining  the  Codeclnfo 
(IV-2202)  structure  returned  by  GetCodecInfo  (1-385). 

compressor 

The  image  compressor  identifier.  The  sequence  grabber  component  may 
specify  a  particular  compressor  by  setting  this  parameter  to  its  compressor 
identifier.  You  can  obtain  these  identifiers  from  GetCodecNameLi  st  (1-386). 

spati al Qual i ty 

A  constant  (see  below)  that  defines  the  desired  quality  of  the  compressed 
image. 

temporal Qual i ty 

A  constant  (see  below)  that  defines  the  desired  temporal  quality  of  the 
sequence.  This  parameter  governs  the  level  of  compression  the  sequence 
grabber  component  desires  with  respect  to  information  in  successive  frames  in 
the  sequence.  The  sequence  grabber  component  sets  this  parameter  to  0  to 
prevent  the  image  compressor  from  applying  temporal  compression  to  the 
sequence. 
keyFrameRate 

The  maximum  number  of  frames  allowed  between  key  frames.  Key  frames 
provide  points  from  which  a  temporally  compressed  sequence  may  be 
decompressed.  The  sequence  grabber  component  uses  this  parameter  to  control 
the  frequency  with  which  the  image  compressor  places  key  frames  into  the 
compressed  sequence. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

spatialQuality  and  temporalQuality  Constants 

codecMI nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 

codecNormal Quality 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 
codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field. 
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codec LosslessQuality 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuration  Functions  for  Video  Channel 
Components"  (V-2828),  "Working  With  Video  Channels"  (V-2819) 

Related  Java  Methods 

quicktime.std.sg.SGVideoChannel . setCompressor ( ) 


See  Also 

For  the  corresponding  get  function,  see  SGGetVi  deoCompressor  (III— 1742). 


SGSetVideoCompressorType 


Specifies  the  type  of  image  compression  to  be  applied  to  captured  video  images. 

ComponentResul t  SGSetVideoCompressorType  ( 

SGChannel  c, 

OSType  compressorType  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 
compressorType 

A  constant  (see  below)  that  defines  the  type  of  image  compression  to  use.  You 
should  use  GetCodecNameLi  st  (1-386)  to  retrieve  their  names,  so  that  your 
application  can  take  advantage  of  new  compressor  types  that  may  be  added  in 
the  future. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

compressorType  Constants 

' rpza ' 

Video  compressor. 

'jpeg' 

Photo  compressor. 


III-1814 


Inside  QuickTime:  Functions  R-Z 


SGSetVideoDigitizerComponent 


'  rl  e  ' 

Animation  compressor. 

'  raw  ' 

Raw  compressor. 

'  smc  ' 

Graphics  compressor. 

' cvi d ' 

Compact  video  compressor. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Configuration  Functions  for  Video  Channel 
Components"  (V-2828),  "Working  With  Video  Channels"  (V-2819) 

Related  Java  Methods 

qui cktime . std . sg . SGVi deoChannel . setCompressorType( ) 


See  Also 

For  the  corresponding  get  function,  see  SGGetVideoCompressorType  (III— 1744). 


SGSetVideoDigitizerComponent 


Assigns  a  video  digitizer  component  to  a  video  channel. 

ComponentResul t  SGSetVideoDigitizerComponent  ( 
SGChannel  c, 

Componentlnstance  vdig  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

vdi  g 

A  component  instance  that  identifies  a  connection  to  a  video  digitizer 
component.  Your  video  channel  component  should  use  this  video  digitizer 
component  to  obtain  its  source  video  data. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Functions  R-Z 


III-1815 


SGSetVideoRect 


Programming  Info 

C  interface  file:  QuickTimeComponents.h 

Programming  summary:  "Configuration  Functions  for  Video  Channel 
Components"  (V-2828),  "Working  With  Video  Channels"  (V-2819) 

Related  Java  Methods 

quicktime.std.sg.SGVideoChannel.setDIgiti zer Component ( ) 


See  Also 

For  the  corresponding  get  function,  see  SGGetVi  deoDigi  ti  zerComponent  (III— 1745). 


SGSetVideoRect 


Specifies  a  part  of  the  source  video  image  that  is  to  be  captured  by  a  sequence 
grabber  component. 

ComponentResul t  SGSetVideoRect  ( 

SGChannel  c, 

const  Rect  *r  ) ; 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 

r 

A  pointer  to  the  Rect  (TV-2399)  structure  that  defines  the  portion  of  the  source 
video  image  to  be  captured.  This  rectangle  must  lie  within  the  boundaries  of  the 
source  video  boundary  rectangle,  which  the  sequence  grabber  can  obtain  by 
calling  SGGetSrcVi  deoBounds  (III— 1735).  If  you  do  not  use  this  function  to  set  a 
source  rectangle,  the  sequence  grabber  component  captures  the  entire  video 
image,  as  defined  by  the  source  video  boundary  rectangle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  cannot  call  this  function  during  a  record  operation. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuration  Functions  for  Video  Channel 
Components"  (V-2828),  "Working  With  Video  Channels"  (V-2819) 


III-1816 


Inside  QuickTime:  Functions  R-Z 


SGSortDeviceList 


Related  Java  Methods 

qui cktime . std . sg . SGVi deoChannel . setVi deoRect( ) 

See  Also 

For  the  corresponding  get  function,  see  SGGetVi  deoRect  (III— 1746). 


SGSortDeviceList 


Sorts  a  device  list  alphabetically. 

ComponentResul t  SGSortDeviceList  ( 
SeqGrabComponent  s, 

SGDeviceList  list  ); 


s 

The  component  instance  that  identifies  your  connection  to  the  sequence 
grabber  component.  You  obtain  this  value  from  OpenDefaul  t  Component  (11-1131) 
or  OpenComponent  (11-1130). 

list 

A  handle  to  an  SGDevi  ceLi  stRecord  (IV-2433)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Utility  Functions  for  Sequence  Grabber  Channel 
Components"  (V-2833) 


SGSoundlnputDriverChanged 

Notifies  the  sequence  grabber  component  whenever  you  change  the  configuration 
of  a  sound  channel's  sound  input  device. 

ComponentResul t  SGSoundlnputDriverChanged  ( 

SGChannel  c  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 


Inside  QuickTime:  Functions  R-Z 


III-1817 


SGStartPreview 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuration  Functions  for  Sound  Channel 
Components"  (V-2831),  "Working  With  Sound  Channels"  (V-2821) 

Related  Java  Methods 

quicktime.std.sg.SGSoundChannel .set!nputDriver( ) 


S  G  StartPre  vie  w 

Instructs  the  sequence  grabber  to  begin  processing  data  from  its  channels. 

ComponentResul t  SGStartPreview  ( 

SeqGrabComponent  s  ) ; 


s 

An  instance  of  the  sequence  grabber  component  connected  to  your  channel 
component.  The  sequence  grabber  component  provides  this  value  through 
SGIni tChannel  (III — 1751). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Your  channel  component  should  immediately  present  the  data  to  the  user  in  the 
appropriate  format,  according  to  your  channel's  configuration.  Display  video  data 
in  the  destination  display  region;  play  sound  data  at  the  specified  volume  settings. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Controlling  Sequence  Grabber  Channel  Components" 
(V-2824),  "Controlling  Sequence  Grabber  Components"  (V-2811) 

Related  Java  Methods 

quicktime.std.sg.SequenceGrabber.startPreviewO 


III-1818 
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SGStartRecord 


See  Also 

In  preview  mode,  the  sequence  grabber  does  not  save  any  of  the  data  it  gathers  from 
its  channels.  If  you  want  to  record  the  data,  use  record  mode.  You  start  a  record 
operation  by  calling  SGStartRecord  (III— 1819). 


SGStartRecord 


Instructs  the  sequence  grabber  component  to  begin  collecting  data  from  its 
channels. 

ComponentResul t  SGStartRecord  ( 

SeqGrabComponent  s  ); 


s 

An  instance  of  the  sequence  grabber  component  connected  to  your  channel 
component.  The  sequence  grabber  component  provides  this  value  through 
SGIni tChannel  (III — 1751). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Controlling  Sequence  Grabber  Channel  Components" 
(V-2824),  "Controlling  Sequence  Grabber  Components"  (V-2811) 

Related  Java  Methods 

qui cktime . std . sg . SequenceGrabber . sta rt Record ( ) 


See  Also 

You  can  cause  the  sequence  grabber  to  display  the  data  it  obtains  from  its  channels 
without  storing  any  of  the  data  by  calling  SGStartPrevi  ew  (III— 1818). 


SGStop 


Stops  a  preview  or  record  operation. 

ComponentResul t  SGStop  ( 

SeqGrabComponent  s  ); 


Inside  QuickTime:  Functions  R-Z 


III-1819 


SGTransferFrameForCompress 


s 

An  instance  of  the  sequence  grabber  component  connected  to  your  channel 
component.  The  sequence  grabber  component  provides  this  value  through 
SGIni tChannel  (III — 1751). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

It  is  dangerous  to  allow  an  update  event  to  occur  during  recording.  Many  digitizers 
capture  directly  to  the  screen,  and  an  update  event  will  result  in  data  loss. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Sequence  Grabber  Channel  Components" 
(V-2824),  "Controlling  Sequence  Grabber  Components"  (V-2811) 

Related  Java  Methods 

qui cktime. std . sg . SequenceGrabber . stopt ) 


SGTransferFrameForCompress 


Provides  the  default  behavior  for  your  transfer-frame  function. 

ComponentResul t  SGTransferFrameForCompress  ( 

SGChannel  c, 

short  bufferNum, 

const  MatrixRecord  *mp, 

RgnHandl e  cl i pRgn  ) ; 


The  reference  that  identifies  the  channel  for  this  operation.  The  sequence 
grabber  component  provides  this  value  to  your  transfer-frame  function. 

bufferNum 

Identifies  the  buffer.  The  sequence  grabber  component  provides  this  value  to 
your  transfer-frame  function. 

mp 

A  pointer  toaMatrixRecord  (IV-2304)  structure  for  the  transfer  operation.  If 
there  is  no  matrix  for  the  operation,  set  this  parameter  to  N I F. 


III-1820 


Inside  QuickTime:  Functions  R-Z 


SGUpdate 


cl  i  pRgn 

A  handle  to  aMac  Region  (IV-2303)  structure  that  defines  the  clipping  region  for 
the  destination  image.  This  region  is  defined  in  the  destination  coordinate 
system.  If  there  is  no  clipping  region,  set  this  parameter  to  N I L. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


SGUpdate 


Informs  your  component  about  update  events,  to  update  its  display. 

ComponentResul t  SGUpdate  ( 

SeqGrabComponent  s, 

RgnHandle  updateRgn  ); 


s 

An  instance  of  the  sequence  grabber  component  connected  to  your  channel 
component.  The  sequence  grabber  component  provides  this  value  through 
SGIni tChannel  (III — 1751). 
updateRgn 

Indicates  the  part  of  the  window  that  has  been  changed. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Applications  can  determine  the  part  of  the  window  that  has  been  changed  by 
examining  the  appropriate  window  record.  For  example,  they  may  call  the 
sequence  grabber  in  this  manner: 

SGUpdate  (theSG,  ( ( Wi ndowPeeklupdateWi ndow) -SupdateRgn ) ; 

Special  Considerations 

Your  application  should  avoid  drawing  where  the  sequence  grabber  is  displaying 
video.  Doing  so  may  cause  some  video  digitizer  components  to  stop  displaying 
video. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Functions  R-Z 


III-1821 


SGVideoDigitizerChanged 


Programming  Info 

C  interface  file:  QuickTimeComponents.h 

Programming  summary:  "Controlling  Sequence  Grabber  Channel  Components" 
(V-2824),  "Controlling  Sequence  Grabber  Components"  (V-2811) 

Related  Java  Methods 

qui ckti me. std . sg . SequenceGrabber . update! ) 


SGVideoDigitizerChanged 

Notifies  the  sequence  grabber  component  whenever  you  change  the  configuration 
of  a  video  channel's  video  digitizer. 

ComponentResul t  SGVideoDigitizerChanged  ( 

SGChannel  c  ) ; 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

It  is  very  important  to  notify  the  sequence  grabber  of  any  configuration  changes  you 
make. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Configuration  Functions  for  Video  Channel 
Components"  (V-2828),  "Working  With  Video  Channels"  (V-2819) 

Related  Java  Methods 

quicktime.std.sg.SGVideoChannel .digitizerChangedt ) 


SGWriteExtendedMovieData 


Allows  your  channel  component  to  add  data  to  a  movie. 

ComponentResul t  SGWriteExtendedMovieData  ( 
SeqGrabComponent  s, 

SGChannel  c, 


III-1822 


Inside  QuickTime:  Functions  R-Z 


SGWriteExtendedMovieData 


Ptr 
1  ong 
wi  de 
SGOutput 


P. 

1  en , 

*of f set , 
*sgOut  ); 


s 

An  instance  of  the  sequence  grabber  component  connected  to  your  channel 
component.  The  sequence  grabber  component  provides  this  value  through 
SGIni tChannel  (III — 1751). 

c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

P 

The  location  of  the  data  to  be  added  to  the  movie. 

1  en 

The  number  of  bytes  of  data  to  be  added  to  the  movie, 
offset 

A  pointer  to  a  wide  integer  that  receives  the  offset  to  the  new  data  in  the  movie. 
If  the  movie  is  in  memory,  the  returned  offset  reflects  the  location  the  data  will 
have  in  the  movie  on  a  permanent  storage  device. 
sgOut 

A  pointer  to  the  sequence  grabber  output  to  which  the  data  was  written. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  differs  from  SGWri  teMovi  eData  (III-1824),  in  two  respects:  the  offset 
parameter  has  a  64-bit  value,  and  the  sgOut  parameter  does  not  exist  in 
SGWri teMovi eData. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Utility  Functions  for  Sequence  Grabber  Channel 
Components"  (V-2833) 

Related  Java  Methods 

qui cktime . std . sg . SequenceGrabber.wri te Extend edMovi  eData ( ) 


See  Also 

See  SGWri  teMovi  eData  (III — 1824). 


Inside  QuickTime:  Functions  R-Z 


III-1823 


SGWriteMovieData 


SGWriteMovieData 


Lets  a  channel  component  add  data  to  a  movie. 


ComponentResul t  SGWriteMovieData 


SeqGrabComponent  s, 
SGChannel  c, 

Ptr  p , 

long  len, 

long  *offset 


( 


) ; 


s 

An  instance  of  the  sequence  grabber  component  connected  to  your  channel 
component.  The  sequence  grabber  component  provides  this  value  through 
SGIni tChannel  (III — 1751). 

c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 

P 

The  location  of  the  data  to  be  added  to  the  movie. 

1  en 

The  number  of  bytes  of  data  to  be  added  to  the  movie, 
offset 

A  pointer  to  a  long  integer  that  is  to  receive  the  offset  to  the  new  data  in  the 
movie.  The  sequence  grabber  component  returns  an  offset  that  is  correct  in  the 
context  of  a  movie  resource,  even  if  the  movie  data  is  currently  stored  in 
memory.  That  is,  if  the  movie  is  in  memory,  the  returned  offset  reflects  the 
location  that  the  data  will  have  in  a  movie  on  a  permanent  storage  device,  such 
as  a  disk. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Utility  Functions  for  Sequence  Grabber  Channel 
Components"  (V-2833) 

See  Also 

See  SGWri  teExtendedMovi  eData  (III — 1822). 


III-1824 


Inside  QuickTime:  Functions  R-Z 


SGWriteSamples 


SGWriteSamples 


Called  by  a  sequence  grabber  component  when  it  is  ready  to  add  recorded  data  to 
a  movie. 

ComponentResul t  SGWriteSamples  ( 

SGChannel  c. 

Movie  m, 

AliasHandle  theFile  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 
m 

Identifies  the  movie  to  which  your  component  should  add  the  captured  data. 
Your  component  should  not  make  any  other  changes  to  the  movie  identified  by 
this  reference.  Use  SGWri  teMovi  eData  (III— 1824)  instead. 
theFi 1 e 

Identifies  the  movie  file.  The  sequence  grabber  component  provides  this  alias 
so  that  you  can  supply  it  to  the  Movie  Toolbox.  You  should  not  open  this  file  or 
write  to  it  directly.  Use  SGWri  teMovi  eData  (III— 1824)  instead. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Controlling  Sequence  Grabber  Channel  Components" 
(V-2824) 

ShowHideT  askBar 


Shows  or  hides  the  Windows  taskbar. 

void  ShowHideTaskBar  ( 

Boolean  showlt  ); 

showlt 

Pass  TRUE  to  show  the  task  bar,  FALSE  otherwise. 


Inside  QuickTime:  Functions  R-Z 


III-1825 


ShowMovielnformation 


Discussion 

This  call  can  be  used  to  hide  the  taskbar  during  full-screen  movie  playback. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML.h 


ShowMovielnformation 


Displays  a  movie's  information. 

void  ShowMovielnformation  ( 

Movie  theMovie, 

Modal  Fi  1  terLIPP  filterProc, 

1 ong  refCon  ) ; 


theMovi e 

A  movie  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e 
(11-1084). 
f  i  1 terProc 

A  Universal  Procedure  Pointer  that  accesses  a  Modal  Fi  1  terProc  (III— 2098) 
callback. 

refCon 

A  reference  constant  to  be  passed  to  your  filter  callback.  Use  this  parameter  to 
point  to  a  data  structure  containing  any  information  your  function  needs. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Related  Java  Methods 

qui ckti me . std .movi es . Movi e . showlnformati on ( ) 


III-1826 


Inside  QuickTime:  Functions  R-Z 


ShowMoviePoster 


ShowMoviePoster 


Displays  a  movie's  poster. 

void  ShowMoviePoster  ( 

Movie  theMovie  ); 

theMovi e 

A  movie  identifier.  Your  application  obtains  this  identifier  from  such  functions 
as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e 
(11-1084). 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

The  Movie  Toolbox  draws  the  movie  poster  once,  in  the  movie's  graphics  world, 
using  the  movie's  matrix  and  display  clipping  characteristics.  You  can  access  error 
returns  from  this  function  through  GetMovi  esError  (I — 492)  and 
GetMovi  esSti  ckyError  (1-494).  See  "Error  Codes"  (IV-2663). 

Special  Considerations 

This  function  works  on  both  active  and  inactive  movies. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Movie  Posters  and  Movie  Previews"  (V-2718) 

Related  Java  Methods 

qui cktime . std .movi es . Movi e . showPoster( ) 


SkewMatrix 


Modifies  the  contents  of  a  matrix  so  that  it  defines  a  skew  transformation. 


void  SkewMatrix  ( 
MatrixRecord 
Fi  xed 
Fi  xed 
Fi  xed 
Fi  xed 


*m, 

skewX , 
skewY , 
aboutX , 
aboutY  ); 


Inside  QuickTime:  Functions  R-Z 


III-1827 


SndAddModifier 


m 

A  pointer  to  the  matrix  for  this  operation.  The  SkewMatri  x  function  updates  the 
contents  of  the  MatrixRecord  (IV-2304)  structure  so  that  it  defines  a  skew 
operation;  it  concatenates  the  respective  transformations  onto  whatever  was 
initially  in  the  matrix  structure.  You  specify  the  magnitude  and  direction  of  the 
skew  operation  with  the  skewX  and  skewY  parameters.  You  specify  an  anchor 
point  with  the  a  bout  X  and  aboutY  parameters. 
skewX 

The  skew  value  to  be  applied  to  x  coordinates. 
skewY 

The  skew  value  to  be  applied  to  y  coordinates. 
aboutX 

The  x  coordinate  of  the  anchor  point. 
aboutY 

The  y  coordinate  of  the  anchor  point. 

Discussion 

A  skew  operation  alters  the  display  of  an  element  along  one  dimension.  For 
example,  converting  a  rectangle  into  a  parallelogram  is  a  skew  operation. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Matrices"  (V-2764) 

Related  Java  Methods 

qui ckti me . std . i mage . Matri x. skew( ) 


SndAddModifier 


Obsolete. 

( 

chan , 
modi  tier, 
i  d , 

1  n  1 1  ) ; 


OSErr  SndAddModifier 
SndChannel Ptr 
Ptr 
short 
1  ong 


III-1828 


Inside  QuickTime:  Functions  R-Z 


SndChannelStatus 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier.  Macintosh  Note:  Not  supported  by 

CarbonLib. 

Programming  Info 

C  interface  file:  Sound .  h 


SndChannelStatus 


Determines  the  status  of  a  sound  channel. 

OSErr  SndChannelStatus  ( 

SndChannel Ptr  chan, 

short  theLength, 

SCStatusPtr  theStatus  ); 


chan 

A  pointer  to  a  valid  sound  channel. 
theLength 

The  size  in  bytes  of  the  sound  channel  status  record.  You  should  set  this  field  to 
SizeOf(SCStatus). 
theStatus 

A  pointer  to  an  SCStatus  (IV-2425)  structure.  On  return,  the  fields  of  this 
structure  accurately  describe  the  sound  channel  specified  by  the  chan 
parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

You  can  call  this  function  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SndControl 

Obsolete. 

OSErr  SndControl  ( 
short  id. 


Inside  QuickTime:  Functions  R-Z 


III-1829 


SndDisposeChannel 


SndCommand  *cmd  ) ; 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier.  Macintosh  Note:  Not  supported  by 

CarbonLib. 

Programming  Info 

C  interface  file:  Sound .  h 


SndDisposeChannel 


Disposes  of  the  queue  of  sound  commands  associated  with  a  sound  channel. 

OSErr  SndDisposeChannel  ( 

SndChannel Ptr  chan, 

Bool ean  qui etNow  ) ; 


chan 

A  pointer  to  a  valid  SndChannel  (IV-2440)  structure, 
qui etNow 

A  Boolean  value  that  indicates  whether  the  channel  should  be  disposed 
immediately  (TRUE)  or  after  sound  stops  playing  (FALSE).  This  function  can 
dispose  of  a  channel  immediately  or  wait  until  the  queued  commands  are 
processed.  If  qui  etNow  is  set  to  TRUE,  a  f  1  ushCmd  command  and  then  a  qui  etCmd 
command  are  sent  to  the  channel,  bypassing  the  command  queue.  This 
removes  all  commands,  stops  any  sound  in  progress,  and  closes  the  channel.  If 
qui  etNow  is  set  to  FALSE,  then  the  Sound  Manager  issues  a  qui  etCmd  command 
only;  it  does  not  bypass  the  command  queue,  and  it  waits  until  the  qui  etCmd 
command  is  processed  before  disposing  of  the  channel. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

If  your  application  created  its  own  sound  channel  record  in  memory  or  installed  a 
sound  as  a  voice  in  a  channel,  the  Sound  Manager  does  not  dispose  of  that  memory. 
The  Sound  Manager  also  does  not  release  memory  associated  with  a  sound  resource 
that  you  have  played  on  a  channel.  You  might  use  the  userlnfo  field  of  the 
SndChannel  (IV-2440)  structure  to  store  the  address  of  a  sound  handle  you  wish  to 
release  before  disposing  of  the  sound  channel  itself. 

Special  Considerations 

Because  this  function  might  dispose  of  memory,  you  should  not  call  it  at  interrupt 
time. 


III-1830 


Inside  QuickTime:  Functions  R-Z 


SndDoCommand 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SndDoCommand 


Queues  a  command  in  a  sound  channel. 

OSErr  SndDoCommand  ( 

SndChannel Ptr  chan, 

const  SndCommand  *cmd. 

Boolean  noWait  ); 


chan 

A  pointer  to  a  valid  SndChannel  (IV-2440)  structure, 
cmd 

A  SndCommand  (IV-2441)  structure  to  be  sent  to  the  channel  specified  in  the  chan 
parameter. 
noWai  t 

A  flag  indicating  whether  the  Sound  Manager  should  wait  for  a  free  space  in  a 
full  queue  (FALSE)  or  whether  it  should  return  immediately  with  a  queueFul  1 
result  code  if  the  queue  is  full  (TRUE).  This  parameter  has  meaning  only  if  a 
sound  channel's  queue  of  sound  commands  is  full.  If  the  noWait  parameter  is  set 
to  FALSE  and  the  queue  is  full,  the  Sound  Manager  waits  until  there  is  space  to 
add  the  command,  thus  preventing  your  application  from  doing  other 
processing.  If  noWai  t  is  set  to  TRUE  and  the  queue  is  full,  the  Sound  Manager 
does  not  send  the  command  and  returns  the  queueFul  1  result  code. 

function  result  See  "Error  Codes"  (IV-2663).  If  noWai  t  is  set  to  TRUE  and  the  queue  is 
full,  the  Sound  Manager  does  not  send  the  command  and  returns  the 
queueFul  1  result  code.  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

Whether  this  function  moves  memory  depends  on  the  particular  sound  command 
you're  sending  it.  Most  of  the  available  sound  commands  do  not  cause  it  to  move 
memory  and  can  therefore  be  issued  at  interrupt  time.  Moreover,  you  can 
sometimes  safely  send  commands  at  interrupt  time  that  would  otherwise  cause 
memory  to  move  if  you've  previously  issued  the  soundCmd  sound  command  to 
preconfigure  the  channel  at  noninterrupt  time. 


Inside  QuickTime:  Functions  R-Z 


III-1831 


SndDoImmediate 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

See  "Sound  Commands"  (IV-2691). 


SndDoImmediate 


Places  a  sound  command  in  front  of  a  sound  channel's  command  queue. 

OSErr  SndDoImmediate  ( 

SndChannel Ptr  chan, 

const  SndCommand  *cmd  ) ; 


chan 

A  pointer  to  a  valid  SndChannel  (IV-2440)  structure. 

cmd 

A  SndCommand  (IV-2441)  structure  to  be  sent  to  the  channel  specified  in  the  chan 
parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  operates  much  like  SndDoCommand  (III— 1831),  except  that  it  bypasses  the 
existing  command  queue  of  the  sound  channel  and  sends  the  specified  command 
directly  to  the  Sound  Manager  for  immediate  processing.  This  function  also 
overrides  any  wai  tCmd,  pauseCmd,  or  syncCmd  commands  that  might  have  already 
been  processed.  However,  other  commands  already  received  by  the  Sound 
Manager  will  not  be  interrupted  by  this  function,  although  a  qui  etCmd  command 
sent  via  SndDoImmedi  ate  (III— 1832)  will  quiet  a  sound  already  playing. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

See  "Sound  Commands"  (IV-2691). 


III-1832 
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SndGetlnfo 


SndGetlnfo 


Retrieves  information  about  an  open  Sound  Manager  channel,  including  hardware 
settings. 

OSErr  SndGetlnfo  ( 

SndChannel Ptr  chan, 

OSType  selector, 

void  *infoPtr  ); 


chan 

A  pointer  to  a  valid  SndChannel  (IV-2440)  structure, 
sel ector 

A  sound  input  device  information  selector  that  specifies  the  type  of  information 
you  need.  See  "Sound  Information  Selectors"  (IV-2693). 
i nf oPtr 

A  pointer  to  a  buffer  in  which  information  should  be  returned.  This  buffer  must 
be  large  enough  to  contain  the  type  of  information  specified  in  the  sel  ector 
parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  should  be  used  instead  of  attempting  to  communicate  directly  with 
sound  components. 

Special  Considerations 

This  function  uses  a  selector-based  interface  similar  to  SPBGetDevi  celnfo  (III— 1871), 
with  the  same  sound  information  selectors. 

Version  Notes 

Available  only  with  Sound  Manager  version  3.1  or  later.  Check  for  this  by  calling 
SndSoundManagerVersion  (III— 1 847)  to  get  the  installed  version  number . 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

See  SPBGetDevi  celnfo  (III— 1871).  For  the  corresponding  set  function,  see  SndSetlnfo 
(III— 1845). 

SndGetSysBeepState 


Determines  if  the  system  alert  sound  is  enabled. 


Inside  QuickTime:  Functions  R-Z 


III-1833 


SndlnputGetDevicelnfo 


void  SndGetSysBeepState  ( 

short  *sysBeepState  ); 

sysBeepState 

On  return,  a  pointer  to  one  of  two  constants  (see  below)  that  represents  the  state 
of  the  system  alert  sound. 

sysBeepState  Constants 

sysBeepDi sabl e 

The  system  alert  sound  is  disabled. 
sysBeepEnabl e 

The  system  alert  sound  is  enabled. 

Special  Considerations 

You  can  call  this  function  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


See  Also 

For  the  corresponding  set  function,  see  SndSetSysBeepState  (III— 1846). 


SndlnputGetDevicelnfo 


Undocumented 

ComponentResul t  SndlnputGetDevicelnfo  ( 
Componentlnstance  self, 

OSType  infoType, 

void  *infoData  ); 


sel  f 

Undocumented 
i nfoType 

A  sound  input  device  information  selector  that  specifies  the  type  of  information 
you  need.  See  "Sound  Information  Selectors"  (IV-2693). 
i nfoData 

A  pointer  to  a  buffer  in  which  information  should  be  returned.  This  buffer  must 
be  large  enough  to  contain  the  type  of  information  specified  in  the  i  nfoType 
parameter. 


III-1834 


Inside  QuickTime:  Functions  R-Z 


SndlnputGetStatus 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


See  Also 

For  the  corresponding  set  function,  see  SndlnputSetDevi  celnfo  (III— 1838). 


SndlnputGetStatus 


Undocumented 


ComponentResul t  SndlnputGetStatus  ( 


Componentlnstance 

short 

unsigned  long 
unsigned  long 


self, 

*recordi ngStatus , 

*t ot a  1 Sampl esTo Record , 
*numberOf Samp! esRecorded  ); 


self 

Undocumented 
recordi ngStatus 
Undocumented 
total Sampl esTo Record 
Undocumented 
numberOf Sampl esRecorded 
Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SndlnputlnitHardware 

Undocumented 

ComponentResul t  SndlnputlnitHardware  ( 
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III-1835 


SndlnputPauseRecording 


Componentlnstance  self  ); 

sel  f 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

SndlnputPauseRecording 

Undocumented 

ComponentResul t  SndlnputPauseRecording  ( 

Componentlnstance  self  ); 

sel  f 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SndlnputReadAsync 


Undocumented 

ComponentResul t  SndlnputReadAsync  ( 
Componentlnstance  self, 

SndlnputCmpParamPtr  SICParmPtr  ); 


sel  f 

Undocumented 

SICParmPtr 

A  pointer  to  a  SndlnputCmpParam  (IV-2446)  structure. 


III-1836 
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SndlnputReadSync 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SndlnputReadSync 


Undocumented 

ComponentResul t  SndlnputReadSync  ( 
Componentlnstance  self, 

SndlnputCmpParamPtr  SICParmPtr  ); 


self 

Undocumented 

SICParmPtr 

A  pointer  to  a  SndlnputCmpParam  (IV-2446)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SndlnputResumeRecording 

Undocumented 

ComponentResul t  SndlnputResumeRecording  ( 

Componentlnstance  self  ); 

self 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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III-1837 


SndlnputSetDevicelnfo 


Programming  Info 

C  interface  file:  Sound .  h 


SndlnputSetDevicelnfo 

Undocumented 

ComponentResul t  SndlnputSetDevicelnfo  ( 

Componentlnstance  self, 

OSType  infoType, 

voi d  *1 nfoData  ) ; 

sel  f 

Undocumented 
i nfoType 

A  sound  input  device  information  selector  that  specifies  the  type  of  information 
you  need.  See  "Sound  Information  Selectors"  (IV-2693). 

1 nfoData 

A  pointer  to  a  buffer  in  which  information  should  be  returned.  This  buffer  must 
be  large  enough  to  contain  the  type  of  information  specified  in  the  1  nfoType 
parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


See  Also 

For  the  corresponding  get  function,  see  SndlnputGetDevi  celnfo  (III— 1834). 


SndlnputStopRecording 


Undocumented 

ComponentResul t  SndlnputStopRecording  ( 
Componentlnstance  self  ); 


sel  f 

Undocumented 


III-1838 
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SndManagerStatus 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SndManagerStatus 


Determines  information  about  all  sound  channels  currently  allocated. 

OSErr  SndManagerStatus  ( 

short  theLength, 

SMStatusPtr  theStatus  ); 

theLength 

The  size  in  bytes  of  the  SMStatus  (IV-2438)  structure. 
theStatus 

A  pointer  to  an  SMStatus  (IV-2438)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

If  this  function  executes  successfully,  the  fields  of  the  structure  specified  by 
theStatus  accurately  describe  the  current  status  of  the  Sound  Manager. 

Special  Considerations 

You  can  call  this  function  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SndNewChannel 


Allocates  a  new  sound  channel. 


OSErr  SndNewChannel 
SndChannel Ptr 
short 
1  ong 

SndCal 1 BackUPP 


*chan , 
synth , 
i  ni  t , 

userRoutine  ); 
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III-1839 


SndNe  wChannel 


chan 

A  pointer  to  a  valid  SndChannel  (IV-2440)  structure.  You  can  pass  a  pointer 
whose  value  is  NIL  to  force  the  Sound  Manager  to  allocate  the  SndChannel 
structure  internally.  If  you  do  this,  the  function  allocates  the  structure  in  your 
application's  heap  and  returns  a  pointer  to  it.  If  you  pass  a  pointer  to  N I L  in  this 
parameter,  the  function  allocates  enough  memory  to  store  128  sound 
commands .  However,  if  you  pass  a  pointer  toaSndChannel  structure  rather  than 
a  pointer  to  NIL,  the  amount  of  memory  allocated  is  determined  by  the  q  Length 
field  of  that  structure.  Thus,  if  you  wish  to  control  the  size  of  the  sound  queue, 
you  must  allocate  your  own  SndChannel  structure, 
synth 

A  constant  (see  below)  that  identifies  the  sound  data  type  you  intend  to  play  on 
this  channel.  If  you  do  not  want  to  specify  a  specific  data  type,  pass  0  in  this 
parameter.  You  might  do  this  if  you  plan  to  use  the  channel  to  play  a  single 
sound  resource  that  itself  specifies  the  sound's  data  type. 

i  n  i  t 

The  desired  initialization  parameters  for  the  channel.  If  you  cannot  determine 
what  types  of  sounds  you  will  be  playing  on  the  channel,  pass  0  in  this 
parameter.  To  specify  a  sound  output  device  other  than  the  current  sound 
output  device,  pass  the  value  kUseOpti  onal  OutputDevi  ce  in  the  synth  parameter 
and  the  signature  of  the  desired  sound  output  device  component  in  the  i  n  i  t 
parameter.  Only  sounds  defined  by  wave-table  data  and  sampled-sound  data 
currently  use  the  i  ni  t  parameter. 
userRouti ne 

A  pointer  to  a  SndCallBackProc  (III— 2147)  callback  that  the  Sound  Manager 
executes  whenever  it  receives  a  cal  1  BackCmd  command;  see  "Sound 
Commands"  (IV-2691).  If  you  pass  N I L,  then  any  cal  1  BackCmd  commands  sent 
to  this  channel  are  ignored. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

synth  Constants 

squareWaveSynth 

Square  wave  data. 
waveTabl eSynth 

Wave  table  data, 
sampl edSynth 

Sampled  sound  data. 


III-1840 
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SndPauseFilePlay 


kllseOpti  on  a  1  Output  Devi  ce 

Data  is  going  to  a  sound  output  device  other  than  the  current  device.  The  ability 
to  redirect  output  away  from  the  current  sound  output  device  is  intended  for 
use  by  specialized  applications  that  need  to  use  a  specific  sound  output  device. 
In  general,  your  application  should  always  send  sound  to  the  current  sound 
output  device  selected  by  the  user. 

Discussion 

This  function  internally  allocates  memory  to  store  a  queue  of  sound  commands. 
Regardless  of  whether  or  not  you  allocate  your  own  SndChannel  structure  through 
the  chan  parameter,  the  Sound  Manager  allocates  memory  for  the  sound  command 
queue  internally. 

Special  Considerations 

Because  this  function  allocates  memory,  you  should  not  call  it  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier.  In  Sound  Manager  versions  earlier  than 
version  3.0,  only  one  data  type  can  be  produced  at  any  one  time.  On  such  platforms, 
this  function  may  fail  if  you  attempt  to  open  a  channel  specifying  a  data  type  other 
than  the  one  currently  being  played. 

Programming  Info 

C  interface  file:  Sound .  h 

Related  Java  Methods 

qui ckti me . sound .SndChannel . SndChannel  ( ) 


SndPauseFilePlay 

Deprecated. 

OSErr  SndPauseFilePlay  ( 

SndChannel Ptr  chan  ); 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier.  Macintosh  Note:  Not  supported  by 

CarbonLib. 

Programming  Info 

C  interface  file:  Sound .  h 
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III-1841 


SndPlay 


SndPlay 


Plays  a  sound  resource  that  your  application  has  loaded  into  memory. 


OSErr  SndPlay  ( 
SndChannel Ptr 
SndLi stHandl e 
Bool ean 


chan , 

sndHandl e , 
async  ) ; 


chan 

A  pointer  to  a  valid  SndChannel  (IV-2440)  structure.  You  can  pass  N I L  instead  of 
a  pointer  to  a  sound  channel  if  you  want  the  Sound  Manager  to  internally 
allocate  a  sound  channel  in  your  application's  heap  zone. 
sndHandl e 

A  handle  to  the  sound  data  to  play,  which  is  expected  to  have  the  structure  of 
a  format  1  or  format  2  '  snd  '  resource.  You  can  pass  a  handle  to  data  created 
by  calling  SndRecord  (III— 1843)  as  well  as  a  handle  to  an  actual  '  snd  '  resource 
that  you  have  loaded  into  memory.  To  use  sampled-sound  data  with  a  format 
1  '  snd  '  resource,  the  resource  must  include  a  buf  f  erCmd  command.  If  a  format 
1  '  s  n  d  '  resource  does  not  specify  which  type  of  sound  data  is  to  be  played,  this 
function  defaults  to  square- wave  data.  It  also  supports  format  2  '  snd  ' 
resources  using  sampled-sound  data  and  a  buf  ferCmd  command, 
async 

A  Bool  ean  value  that  indicates  whether  the  sound  should  be  played 
asynchronously  (TRUE)  or  synchronously  (FALSE).  This  parameter  is  ignored 
(and  the  sound  plays  synchronously)  if  N I L  is  passed  in  the  chan  parameter. 

function  result  Returns  resProbl  em  if  the  sound  resource  has  not  yet  been  loaded. 
Returns  noErr  if  there  is  no  error. 

Discussion 

All  commands  and  data  referenced  by  sndHandl  e  are  sent  to  the  channel.  If  you 
supply  a  sound  channel  pointer  in  the  chan  parameter,  you  can  play  the  sound 
asynchronously.  When  a  sound  is  played  asynchronously,  the  callback  procedure 
supplied  to  SndNewChannel  (III— 1839)  can  be  called  when  a  cal  1  BackCmd  command  is 
processed  by  the  channel.  The  handle  you  pass  in  the  sndHdl  parameter  must  be 
locked  for  as  long  as  the  sound  is  playing  asynchronously. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier.  In  some  versions  of  the  Mac  OS  prior  to 
version  7.0,  the  SndPlay  function  will  not  work  properly  with  sound  resources  that 
specify  the  sound  data  type  twice.  This  might  happen  if  a  resource  specifies  that  a 
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sound  consists  of  sampled-sound  data  and  an  application  does  the  same  when 
creating  a  sound  channel. 

Programming  Info 

C  interface  file:  Sound .  h 

Related  Java  Methods 

quicktime.sound.Sound.playO,  qui ckti me. sound. SndChannel.pl  ay () 


SndPlayDoubleBuffer 


Deprecated. 

OSErr  SndPlayDoubleBuffer  ( 

SndChannel Ptr  chan, 

SndDoubl eBuf f erHeaderPtr  theParams  ); 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier.  Macintosh  Note:  Not  supported  by 

CarbonLib. 

Programming  Info 

C  interface  file:  Sound .  h 


SndRecord 


Records  a  sound  resource  into  memory. 

OSErr  SndRecord  ( 

Modal Fi 1 terUPP 
Poi  nt 
OSType 

SndLi stHandl e 
fi 1 terProc 

A  pointer  to  a  ModalFilterProc  (III— 2098)  callback  that  determines  how  user 
actions  in  the  sound  recording  dialog  box  are  filtered.  By  specifying  your  own 
filter  function,  you  can  override  or  add  to  the  default  actions  of  the  items  in  the 
dialog  box.  Otherwise,  pass  N I L. 
corner 

The  horizontal  and  vertical  coordinates  of  the  upper-left  corner  of  the  sound 
recording  dialog  box,  in  global  coordinates. 


fi 1 terProc , 
corner , 
quality, 
*sndHandle  ); 
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qual i ty 

A  constant  (see  below)  that  specifies  the  desired  quality  of  the  recorded  sound. 
The  precise  meanings  of  these  constants  are  defined  by  the  sound  input  device 
driver.  For  Apple-supplied  drivers,  this  parameter  determines  whether  the 
recorded  sound  is  to  be  compressed,  and  if  so,  whether  at  a  6:1  or  a  3:1  ratio. 
sndHandl e 

On  entry,  a  handle  to  some  storage  space  or  N I L.  If  the  handle  is  N I L,  the  Sound 
Input  Manager  allocates  a  handle  of  the  largest  amount  of  space  that  it  can  find 
in  your  application's  heap  and  returns  the  handle  in  this  parameter.  It  resizes 
the  handle  when  the  user  clicks  the  Save  button  in  the  sound  recording  dialog 
box.  If  this  parameter  is  not  N I L,  the  Sound  Input  Manager  simply  stores  the 
recorded  data  in  the  location  specified  by  that  handle.  On  return,  this  parameter 
contains  a  handle  to  a  valid  sound  resource  (or  it  is  unchanged,  if  the  call  did 
not  execute  successfully).  The  recorded  data  has  the  structure  of  a  format  1 
'  s  n  d  '  resource  and  can  be  stored  as  a  resource  or  can  be  played  using  S  n  d  P 1  a  y 
(III— 1842). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

quality  Constants 

si BestQual i ty 

The  best  quality  available.  This  specification  does  not  compress  the  sound  and 
provides  the  best  quality  output,  but  at  the  expense  of  increased  memory  use. 
si BetterQual i ty 

Quality  better  than  good.  The  sound  is  compressed  at  3:1  and  is  suitable  for 
most  nonvoice  recording, 
si GoodQual i ty 

Good  quality.  The  sound  is  compressed  at  6:1  and  is  suitable  for  voice 
recording. 

Discussion 

This  function  displays  a  sound  recording  dialog  box  and  is  always  called 
synchronously.  Controls  in  the  dialog  box  allow  the  user  to  start,  stop,  pause,  and 
resume  sound  recording,  as  well  as  to  playback  the  recorded  sound.  The  dialog  box 
also  lists  the  remaining  recording  time  and  the  current  microphone  sound  level. 

Special  Considerations 

Because  the  SndRecord  function  moves  memory,  you  should  not  call  it  at  interrupt 
time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


III-1844 


Inside  QuickTime:  Functions  R-Z 
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Programming  Info 

C  interface  file:  Sound .  h 


SndRecordT  oFile 


Deprecated. 


OSErr  SndRecordToFile 
Modal Fi 1 terUPP 
Poi  nt 
OSType 
short 


( 

fi 1 terProc , 
corner , 
quality, 
fRefNum  ); 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier.  Macintosh  Note:  Not  supported  by 

CarbonLib. 

Programming  Info 

C  interface  file:  Sound .  h 


SndSetlnfo 


Sets  information  about  an  open  Sound  Manager  channel. 


OSErr  SndSetlnfo  ( 
SndChannel Ptr 
OSType 
const  void 


chan , 
sel ector , 
*infoPtr  ); 


chan 

A  pointer  to  a  valid  SndChannel  (IV-2440)  structure, 
sel ector 

A  sound  input  device  information  selector  that  specifies  the  type  of  information 
you  need.  See  "Sound  Information  Selectors"  (IV-2693). 

i nf oPtr 

A  pointer  to  a  buffer  in  which  information  should  be  returned.  This  buffer  must 
be  large  enough  to  contain  the  type  of  information  specified  in  the  sel  ector 
parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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SndSetSysBeepState 


Discussion 

This  function  should  be  used  instead  of  attempting  to  communicate  directly  with 
sound  components. 

Special  Considerations 

This  function  uses  a  selector-based  interface  similar  to  SPBSetDevi  celnfo  (III— 1881), 
with  the  same  sound  information  selectors. 

Version  Notes 

Available  only  with  Sound  Manager  version  3.1  or  later.  Check  for  this  by  calling 
SndSoundManagerVersi  on  (III— 1847)  to  get  the  installed  version  number. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

See  SPBSetDevi  celnfo  (III— 1 88 1 ).  For  the  corresponding  get  function,  see  SndGetlnfo 
(III— 1833). 

SndSetSysBeepState 

Sets  the  state  of  the  system  alert  sound. 

OSErr  SndSetSysBeepState  ( 
short  sysBeepState  ); 

sysBeepState 

One  of  two  constants  (see  below)  that  represents  the  state  of  the  system  alert 
sound. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

sysBeepState  Constants 

sysBeepDi sabl e 

The  system  alert  sound  is  disabled. 
sysBeepEnabl e 

The  system  alert  sound  is  enabled. 

Discussion 

You  can  use  this  function  to  temporarily  disable  the  system  alert  sound  while  you 
play  a  sound  and  then  enable  the  alert  sound  when  you  are  done.  If  your  application 
disables  the  system  alert  sound,  be  sure  to  enable  it  when  your  application  gets  a 
suspend  event. 
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Special  Considerations 

You  can  call  this  function  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


See  Also 

For  the  corresponding  get  function,  see  SndGetSysBeepState  (ill-1833). 


SndSoundManagerVersion 

Determines  the  version  of  the  Sound  Manager  tools  available  on  the  user's 
computer. 

NumVersion  SndSoundManagerVersion  (  void  ); 

function  result  A  4-byte  version  number  that  contains  the  same  information  as  a 
NumVersi  on  (IV-2324)  structure. 

Discussion 

You  can  use  this  function  to  determine  if  a  computer  has  the  enhanced  Sound 
Manager,  which  is  necessary  for  multichannel  sound  and  for  continuous  plays  from 
disk. 

Special  Considerations 

You  can  call  this  function  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SndStartFilePlay 


Deprecated. 

OSErr  SndStartFilePlay  ( 
SndChannel Ptr 
short 
short 
1  ong 


chan , 
f RefNum, 
resNum, 
but f erSi ze , 
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SndStopFilePlay 


voi  d 

Audi oSel ecti onPtr 
Fi 1 ePl ay Comp 1 eti onUPP 
Bool ean 


*theBuffer , 
theSel ecti on , 
theCompl eti on , 
async  ) ; 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier.  Macintosh  Note:  Not  supported  by 

CarbonLib. 

Programming  Info 

C  interface  file:  Sound .  h 


SndStopFilePlay 


Deprecated. 

OSErr  SndStopFilePlay  ( 
SndChannel Ptr  chan, 

Bool ean  qui etNow  ) ; 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier.  Macintosh  Note:  Not  supported  by 

CarbonLib. 

Programming  Info 

C  interface  file:  Sound .  h 


SoundComponentAddSource 


Adds  a  new  sound  source  to  a  sound  output  device  component  that  can  mix 
multiple  channel  of  audio  data. 

ComponentResul t  SoundComponentAddSource  ( 

Componentlnstance  ti  , 

SoundSource  *sourceID  ); 


ti 

A  component  instance  that  identifies  your  sound  component. 
sourcelD 

On  return,  a  source  ID  for  the  newly  created  source  component  chain. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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Discussion 

This  function  is  called  by  the  Sound  Manager  to  create  a  new  sound  source.  If  your 
sound  output  device  component  can  mix  multiple  channels  of  sound,  it  needs  to 
define  this  function.  Your  component  should  call  OpenMixerSoundComponent 
(11—1132)  to  create  an  new  instance  of  the  Apple  Mixer  component.  The  Apple  Mixer 
component  then  creates  a  sound  component  chain  capable  of  generating  the  type  of 
data  your  sound  output  device  component  wants  to  receive.  The  Apple  Mixer  also 
assigns  a  unique  4-byte  source  ID  that  identifies  the  new  sound  source  and 
component  chain,  which  you  can  retrieve  by  calling  this  function.  This  function 
should  then  pass  that  source  ID  back  to  the  Sound  Manager  in  the  s  o  u  r  c  e  I D 
parameter. 

Special  Considerations 

Most  sound  components  do  not  need  to  implement  the  this  function.  Only  sound 
components  that  can  handle  more  than  one  source  of  input  need  to  define  it.  This 
function  is  called  at  noninterrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SoundComponentGetlnfo 


Gets  information  about  the  capabilities  of  your  sound  component. 

ComponentResul t  SoundComponentGetlnfo  ( 

Componentlnstance  ti  , 

SoundSource  sourcelD, 

OSType  selector, 

void  *infoPtr  ); 


ti 

A  component  instance  that  identifies  your  sound  component. 
sourcelD 

A  source  ID  for  a  source  component  chain, 
sel ector 

A  sound  input  device  information  selector  that  specifies  the  type  of  information 
requested.  See  "Sound  Information  Selectors"  (IV-2693).  If  your  component 
cannot  provide  the  information  specified  by  the  selector  parameter,  it  should 
pass  the  selector  to  its  source  component. 
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i nfoPtr 

On  output,  a  pointer  to  the  information  requested  by  the  caller. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  returns  information  about  your  sound  component.  If  the  information 
occupies  4  or  fewer  bytes,  it  should  be  returned  in  the  location  pointed  to  by  the 
1  nfoPtr  parameter.  If  the  information  is  larger  than  4  bytes,  the  i  nfoPtr  parameter 
is  a  pointer  toaSoundlnfoList  (IV-2453)  structure.  This  structure  consists  of  a  count 
and  a  handle  to  a  variable-sized  array.  The  data  type  of  the  array  elements  depends 
on  the  kind  of  information  being  returned.  For  example,  the  selector 
siSampleSizeAvailable  indicates  that  you  should  return  a  list  of  the  sample  sizes 
your  component  can  support.  You  return  the  information  by  passing  back,  in  the 
i  nfoPtr  parameter,  a  pointer  to  an  integer  followed  by  a  handle  to  an  array  of 
integers. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

For  the  corresponding  set  function,  see  SoundComponentSetlnfo  (III— 1856). 


SoundComponentGetSource 


Determines  your  component's  source  component. 

ComponentResul t  SoundComponentGetSource  ( 
Componentlnstance  ti  , 

SoundSource  sourcelD, 

Componentlnstance  *source  ); 


ti 

A  component  instance  that  identifies  your  sound  component. 
sourcelD 

A  source  ID  for  the  source  component  chain  created  by  the  Apple  Mixer, 
source 

A  component  instance  that  identifies  your  source  component.  This  should  be 
the  source  component  instance  your  component  was  passed  when  the  Sound 
Manager  called  your  SoundComponentSetSource  (III— 1858)  function.  In  the 
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unlikely  event  that  your  component  does  not  have  a  source,  you  should  return 
NIL. 

function  result  Your  SoundComponentGetSource  function  should  return  noErr  if 
successful  or  an  appropriate  result  code  otherwise.  See  "Error 
Codes"  (IV-2663). 

Discussion 

This  function  is  called  by  the  Sound  Manager  to  retrieve  your  component's  source 
component  instance.  In  general,  all  sound  components  have  sources,  except  for  the 
source  at  the  beginning  of  the  source  component  chain.  A  sound  output  device 
component  is  always  connected  directly  to  an  instance  of  the  Apple  Mixer. 
Accordingly,  a  sound  output  device  component  should  return  a  component 
instance  of  the  Apple  Mixer  in  the  source  parameter  and  a  source  ID  in  the  s  o  u  r  c  e  I D 
parameter.  A  utility  component  can  ignore  the  source  ID  parameter. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

For  the  corresponding  set  function,  see  SoundComponentSetSource  (III— 1858). 


SoundComponentGetSourceData 


Lets  a  sound  output  device  component  tell  its  source  component  when  it  needs 
more  data. 

ComponentResul t  SoundComponentGetSourceData  ( 

Componentlnstance  ti  , 

SoundComponentDataPtr  *sourceData  ); 


ti 

A  component  instance  that  identifies  your  sound  component. 
sourceData 

On  output,  a  pointer  to  a  SoundComponentData  (IV-2448)  structure  that  specifies 
the  type  and  location  of  the  data  your  component  has  processed. 

function  result  Your  SoundComponentGetSourceData  function  should  return  noErr  if 
successful  or  an  appropriate  result  code  otherwise.  See  "Error 
Codes"  (IV-2663).  If  your  component  cannot  generate  any  more 
data,  it  should  set  the  sampl  eCount  field  of  the  SoundComponentData 
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(IV-2448)  structure  to  0  and  return  noErr. 

Discussion 

This  function  is  called  when  the  sound  component  immediately  following  your 
sound  component  in  the  sound  component  chain  needs  more  data.  Your  function 
should  generate  a  new  block  of  audio  data,  fill  out  a  SoundComponentData  (IV-2448) 
structure  describing  the  format  and  location  of  that  data,  and  then  return  the 
address  of  that  structure  in  the  sourceData  parameter.  Your  function  might  itself 
need  to  get  more  data  from  its  source  component.  To  do  this,  it  calls  its  source 
component's  SoundComponentGetSourceData  function. 

Special  Considerations 

Sound  output  device  components  do  not  need  to  implement  this  function,  but  all 
utility  components  must  implement  it. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SoundComponentlnitOutputDevice 


Allows  a  sound  output  device  component  to  configure  associated  hardware 
devices. 

ComponentResul t  SoundComponentlnitOutputDevice  ( 

Componentlnstance  ti  , 

1 ong  acti ons  ) ; 


ti 

A  component  instance  that  identifies  your  sound  component, 
acti ons 

A  set  of  flags.  This  parameter  is  currently  unused. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Every  sound  output  device  component  must  implement  this  function.  It  is  called  by 
the  Sound  Manager  at  noninterrupt  time  to  allow  your  sound  output  device 
component  to  perform  any  hardware-specific  initialization.  You  should  perform 
any  necessary  initialization  that  was  not  already  performed  in  your  OpenComponent 
(11-1130)  function.  Note  that  your  OpenComponent  function  cannot  assume  that  the 
appropriate  hardware  is  available.  As  a  result,  the  Sound  Manager  calls  this 
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function  when  it  is  safe  to  communicate  with  your  audio  hardware.  You  can  call 
OpenMixerSoundComponent  (11-1132)  to  create  a  single  sound  component  chain. 

Special  Considerations 

This  function  is  always  called  at  noninterrupt  time.  All  other  component-defined 
routines  might  be  called  at  interrupt  time.  Accordingly,  this  function  should  handle 
any  remaining  memory  allocation  needed  by  your  component  and  it  should  lock 
down  any  relocatable  blocks  your  component  will  access. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SoundComponentPauseSource 


Pauses  the  playing  of  sounds  in  one  or  more  sound  channels  of  your  sound  output 
device  component. 

ComponentResul t  SoundComponentPauseSource  ( 

Componentlnstance  ti  , 

short  count, 

SoundSource  *sources  ); 


ti 

A  component  instance  that  identifies  your  sound  component, 
count 

The  number  of  source  IDs  in  the  array  pointed  to  by  the  source  parameter, 
sources 

An  array  of  source  IDs. 

function  result  Your  SoundComponentPauseSource  function  should  return  noErr  if 
successful  or  an  appropriate  result  code  otherwise.  See  "Error 
Codes"  (IV-2663).  You  should  return  noErr  even  if  no  sounds  are 
playing  in  the  specified  channels. 

Discussion 

This  function  is  called  by  the  Sound  Manager  to  pause  the  playing  of  the  sounds 
originating  from  the  sound  sources  specified  by  the  sources  parameter.  Your 
function  should  stop  sending  data  from  those  sources  to  the  associated  sound 
output  device.  Because  this  function  might  be  called  to  resume  playing  sounds,  you 
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should  not  flush  any  data.  If  your  component  supports  only  one  sound  source,  you 
can  ignore  the  sources  parameter. 

Special  Considerations 

Every  sound  output  device  component  must  implement  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SoundComponentPlaySourceBuffer 


Starts  a  new  sound  playing  through  your  sound  output  device  component. 


ComponentResul t  SoundComponentPlaySourceBuffer  ( 
Componentlnstance  ti , 

SoundSource  sourcelD, 

SoundParamBl ockPtr  pb, 

1 ong  acti ons  ) ; 


ti 

A  component  instance  that  identifies  your  sound  component. 
sourcelD 

A  source  ID  for  a  source  component  chain, 
pb 

A  pointer  to  a  SoundParamBl  ock  (IV-2454)  structure, 
acti ons 

A  set  of  32  bit  flags  (see  below)  that  describe  the  actions  to  be  taken  when 
preparing  to  play  the  source  data. 

function  result  Your  SoundComponentPl  aySourceBuffer  function  should  return  noErr 
if  successful  or  an  appropriate  result  code  otherwise.  See  "Error 
Codes"  (IV-2663). 

actions  Constants 

kSourcePaused 

If  this  bit  is  1,  the  component  chain  is  configured  to  play  the  specified  sound  but 
the  playback  is  initially  paused.  In  this  case,  your  SoundComponentStartSource 
function  must  be  called  to  begin  playback.  If  this  bit  is  0,  the  playback  begins 
immediately  once  the  component  chain  is  set  up  and  configured. 
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kPassThrough 

If  this  bit  is  1,  the  Sound  Manager  passes  all  data  through  to  the  sound  output 
device  component  unmodified.  A  sound  output  device  component  that  can 
handle  any  sample  rate  and  sound  format  described  in  a  sound  parameter 
block  should  set  this  bit  to  1. 
kNoSoundComponentChai n 

If  this  bit  is  1,  the  Sound  Manager  does  not  construct  a  component  chain  for 
processing  the  sound  data. 

Discussion 

This  function  is  called  by  the  Sound  Manager  to  start  a  new  sound  playing.  The 
sound  parameter  block  pointed  to  by  the  pb  parameter  specifies  the  sound  to  be 
played.  That  parameter  block  should  be  passed  successively  to  all  sound 
components  in  the  chain  specified  by  the  source  ID  parameter.  This  allows  the 
components  to  determine  their  output  formats  and  playback  settings  and  to  prepare 
for  a  subsequent  call  to  their  SoundComponentGetSourceData  (III— 1851)  function.  It 
also  allows  a  sound  output  device  component  to  prepare  for  starting  up  its 
associated  hardware. 

Special  Considerations 

Every  sound  component  must  implement  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SoundComponentRemoveSource 


Removes  sound  sources  from  your  sound  output  device  component. 

ComponentResul t  SoundComponentRemoveSource  ( 

Componentlnstance  ti  , 

SoundSource  sourcelD  ); 


ti 

A  component  instance  that  identifies  your  sound  component. 
sourcelD 

A  source  ID  for  the  source  component  chain  to  be  removed. 

function  result  Your  SoundComponentRemoveSource  function  should  return  noErr  if 

successful  or  an  appropriate  result  code  otherwise  See  "Error  Codes" 
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(IV-2663). 

Discussion 

This  function  is  called  by  the  Sound  Manager  to  remove  the  existing  sound  source 
specified  by  the  source  ID  parameter.  Your  component  should  do  whatever  is 
necessary  to  invalidate  that  source  and  then  call  SoundComponentRemoveSource 
(III— 1855). 

Special  Considerations 

Every  sound  output  device  component  that  implements  SoundComponentAddSource 
(III— 1848)  must  also  implement  this  function.  It  is  always  called  at  noninterrupt 
time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SoundComponentSetlnfo 


Modifies  the  settings  of  your  sound  component. 

ComponentResul t  SoundComponentSetlnfo  ( 
Componentlnstance  ti  , 

SoundSource  sourcelD, 

OSType  selector, 

voi d  *i nfoPtr  ) ; 


ti 

A  component  instance  that  identifies  your  sound  component. 
sourcelD 

A  source  ID  for  a  source  component  chain, 
sel ector 

A  sound  input  device  information  selector  that  specifies  the  type  of  information 
to  be  set.  See  "Sound  Information  Selectors"  (IV-2693).  If  your  component 
cannot  provide  the  information  specified  by  the  sel  ector  parameter,  it  should 
pass  the  selector  to  its  source  component, 
i nfoPtr 

A  pointer  to  the  information  your  component  is  to  use  to  modify  its  settings.  If 
the  information  associated  with  the  selector  parameter  occupies  4  or  fewer 
bytes,  it  is  passed  on  the  stack,  in  the  i  nfoPtr  parameter  itself.  Otherwise,  the 
i  nfoPtr  parameter  is  a  pointer  to  a  SoundlnfoLi  st  (IV-2453)  structure. 
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function  result  Your  SoundComponentSetlnfo  function  should  return  noErr  if 
successful  or  an  appropriate  result  code  otherwise.  See  "Error 
Codes"  (IV-2663). 

Discussion 

This  function  is  called  by  the  Sound  Manager  to  set  one  of  the  settings  for  your 
component,  as  specified  by  the  selector  parameter. 

Special  Considerations 

Every  sound  component  must  implement  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

For  the  corresponding  get  function,  see  SoundComponentGetlnfo  (III— 1849). 


SoundComponentSetOutput 


Queries  the  Apple  Mixer  component  to  indicate  the  type  of  data  a  sound  output 
device  component  expects  to  receive. 

ComponentResul t  SoundComponentSetOutput  ( 

Componentlnstance  ti  , 

SoundComponentDataPtr  requested, 

SoundComponentDataPtr  *actual  ); 


ti 

A  component  instance  that  identifies  your  sound  component, 
requested 

A  pointer  toaSoundComponentData  (IV-2448)  structure  that  specifies  the  type  of 
the  data  your  component  expects  to  receive, 
actual 

Currently  unused. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  can  be  called  by  a  sound  output  device  component  to  specify  the  kind 
of  audio  data  the  output  device  component  wants  to  receive.  The  Apple  Mixer  uses 
that  information  to  determine  the  type  of  sound  component  chain  it  needs  to 
construct  in  order  to  deliver  that  kind  of  audio  data  to  your  sound  output  device 
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component.  For  example,  if  your  sound  output  device  is  able  to  accept  16-bit 
samples,  the  Sound  Manager  doesn't  need  to  convert  16-bit  audio  data  into  8-bit 
data.  The  following  lines  of  code  illustrate  how  the  sound  output  device  component 
for  the  Apple  Sound  Chip  (ASC)  might  call  this  function  in  the  Apple  Mixer: 


//  SoundComponentSetOutput  coding  example 

myDataRec . f 1 ags  =  0; 

myDataRec . format  =  kOffsetBinary ; 

myDataRec . sampl eRate  =  rate22khz; 

myDataRec . sampl eSi ze  =  8: 

myDataRec . numChannel s  =  2; 

myDataRec . sampl eCount  =  1024: 

myErr  =  SoundComponentSetOutputtmySource , 


/*ignored  here*/ 

/*ASC  needs  offset  binary*/ 
/*ASC  needs  22  kHz  samples*/ 
/*ASC  needs  8-bit  data*/ 
/*ASC  can  do  stereo*/ 

/*ASC  uses  a  IK  FIFO*/ 
&myDataRec,  &myActual); 


Special  Considerations 

Only  the  Apple  Mixer  component  needs  to  implement  this  function.  In  general, 
however,  a  sound  output  device  component  shouldn't  need  to  call  this  function. 
Instead,  it  can  indicate  the  type  of  data  it  expects  to  receive  when  it  calls 
OpenMi  xerSoundComponent  (11-1132).  This  function  is  intended  for  sophisticated 
sound  output  device  components  that  might  want  to  reinitialize  the  Apple  Mixer. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SoundComponentSetSource 


Identifies  your  sound  component's  source  component. 

ComponentResul t  SoundComponentSetSource  ( 
Componentlnstance  ti  , 

SoundSource  sourcelD, 

Componentlnstance  source  ); 


ti 

A  component  instance  that  identifies  your  sound  component. 
sourcelD 

A  source  ID  for  the  source  component  chain  created  by  the  Apple  Mixer, 
source 

A  component  instance  that  identifies  your  source  component. 
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function  result  Your  SoundComponentSetSource  function  should  return  noErr  if 
successful  or  an  appropriate  result  code  otherwise.  See  "Error 
Codes"  (IV-2663). 

Discussion 

This  function  is  called  by  the  Sound  Manager  to  identify  to  your  sound  component 
the  sound  component  that  is  its  source.  Your  component  uses  that  information 
when  it  needs  to  obtain  more  data  from  its  source;  usually,  by  calling  its 
SoundComponentGetSourceData  (III— 1851)  function.  Because  a  sound  output  device 
component  is  always  connected  directly  to  one  or  more  instances  of  the  Apple 
Mixer,  this  function  needs  to  be  implemented  only  by  utility  components  (that  is, 
components  that  perform  modifications  on  sound  data).  Utility  components  are 
linked  together  into  a  chain  of  sound  components,  each  link  of  which  has  only  one 
input  source.  As  a  result,  a  utility  component  can  usually  ignore  the  source  ID 
parameter  passed  to  it. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

For  the  corresponding  get  function,  see  SoundComponentGetSource  (III— 1850). 


SoundComponentStartSource 


Starts  playing  sounds  in  one  or  more  sound  channels. 

ComponentResul t  SoundComponentStartSource  ( 
Componentlnstance  ti  , 

short  count, 

SoundSource  *sources  ); 


ti 

A  component  instance  that  identifies  your  sound  component, 
count 

The  number  of  source  IDs  in  the  array  pointed  to  by  the  source  parameter, 
sources 

An  array  of  source  IDs. 

function  result  Your  SoundComponentStartSource  function  should  return  noErr  if 
successful  or  an  appropriate  result  code  otherwise.  See  "Error 
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Codes"  (IV-2663).  You  should  return  noErr  even  if  no  sounds  are 
playing  in  the  specified  channels. 

Discussion 

This  function  is  called  by  the  Sound  Manager  to  begin  playing  the  sounds 
originating  from  the  sound  sources  specified  by  the  sources  parameter.  Your 
function  should  start  (or  resume)  sending  data  from  those  sources  to  the  associated 
sound  output  device.  If  your  component  supports  only  one  sound  source,  you  can 
ignore  the  sources  parameter. 

Special  Considerations 

Every  sound  output  device  component  must  implement  this  function.  It  can  be 
called  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SoundComponentStopSource 


Stops  playing  sounds  in  one  or  more  sound  channels. 

ComponentResul t  SoundComponentStopSource  ( 
Componentlnstance  ti  , 

short  count, 

SoundSource  *sources  ); 


ti 

A  component  instance  that  identifies  your  sound  component, 
count 

The  number  of  source  IDs  in  the  array  pointed  to  by  the  source  parameter, 
sources 

An  array  of  source  IDs. 

function  result  Your  SoundComponentStopSource  function  should  return  noErr  if 
successful  or  an  appropriate  result  code  otherwise.  See  "Error 
Codes"  (IV-2663).  You  should  return  noErr  even  if  no  sounds  are 
playing  in  the  specified  channels. 

Discussion 

Your  SoundComponentStopSource  function  is  called  by  the  Sound  Manager  to  stop  the 
sounds  originating  from  the  sound  sources  specified  by  the  sources  parameter. 
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Your  function  should  stop  sending  data  from  those  sources  to  the  associated  sound 
output  device.  In  addition,  your  SoundComponentStopSource  function  should  flush 
any  data  from  the  specified  sound  sources  that  it's  caching.  If  your  component 
supports  only  one  sound  source,  you  can  ignore  the  sources  parameter. 

Special  Considerations 

Every  sound  output  device  component  must  implement  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SoundConverterBeginConversion 

Starts  a  sound  conversion  process. 

OSErr  SoundConverterBeginConversion  ( 

SoundConverter  sc  ); 

sc 

The  sound  converter  identifier  returned  bySoundConverterOpen  (III— 1867). 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  resets  all  state  information  to  default  values  in  preparation  for  a  new 
input  buffer. 

Special  Considerations 

This  routine  can  be  called  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SoundConverterClose 


Closes  a  sound  converter. 

OSErr  SoundConverterClose  ( 
SoundConverter  sc  ); 
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sc 

The  sound  converter  identifier  returned  by  SoundConverterOpen  (III— 1867). 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SoundConverterConvertBuffer 


Converts  a  buffer  of  sound  data  from  an  input  format  to  an  output  format. 


OSErr  SoundConverterConvertBuffer  ( 
SoundConverter 
const  void 
unsigned  long 
voi  d 

unsigned  long 
unsigned  long 


sc , 

*i nputPtr , 
i nputFrames , 
*outputPtr , 
*outputFrames , 
*outputBytes  )  ; 


sc 

The  sound  converter  identifier  returned  by  SoundConverterOpen  (III— 1867). 
i nputPtr 

A  pointer  to  an  input  sound  data  buffer, 
i nputFrames 

The  number  of  frames  in  the  buffer  pointed  to  by  inputPtr. 
outputPtr 

A  pointer  to  a  buffer  where  the  output  data  should  be  placed. 
outputFrames 

On  return,  a  pointer  to  the  number  of  frames  written  into  the  buffer  pointed  to 
by  outputPtr. 

outputBytes 

On  return,  a  pointer  to  the  number  of  bytes  written  into  the  buffer  pointed  to 
by  outputPtr. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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Discussion 

This  routine  will  consume  all  the  data  in  the  input  buffer.  Depending  on  the 
complexity  of  the  conversion,  however,  not  all  the  converted  data  may  be  put  in  the 
output  buffer  right  away.  This  routine  is  used  to  flush  out  all  this  remaining  data 
before  a  conversion  session  is  closed.  If  you  are  using  this  routine  in  conjunction 
with  SoundConverterGetBuf ferSi  zes  (III— 1866),  it  is  very  important  that  you  do  not 
pass  in  a  value  in  i  nputFrames  larger  than  the  frames  parameter  value  returned  by 
SoundConverterGetBuf  ferSi  zes,  or  you  will  overflow  your  output  buffer. 

Special  Considerations 

This  function  can  be  called  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SoundConverterEndConversion 


Ends  a  sound  conversion  process. 


OSErr  SoundConverterEndConversion  ( 
SoundConverter  sc, 

void  *outputPtr, 

unsigned  long  *outputFrames , 

unsigned  long  *outputBytes  ); 


sc 

The  sound  converter  identifier  returned  bySoundConverterOpen  (III— 1867). 
outputPtr 

A  pointer  to  a  buffer  where  the  last  of  the  output  data  should  be  placed.  Any 
data  remaining  in  the  sound  converter  is  flushed  out  and  returned  here. 
outputFrames 

On  return,  a  pointer  to  the  number  of  frames  written  into  the  buffer  pointed  to 
by  outputPtr. 

outputBytes 

On  return,  a  pointer  to  the  number  of  bytes  written  into  the  buffer  pointed  to 
by  outputPtr. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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Special  Considerations 

This  routine  can  be  called  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SoundConverterFillBuffer 


Provides  an  alternative  method  for  converting  sound  data  that  is  more  predictable 
and  flexible  than  using  SoundConverterConvertBuffer  (III— 1862). 


OSErr  SoundConverterFillBuffer  ( 
SoundConverter 

SoundConverterFill BufferDataUPP 
voi  d 
voi  d 

unsigned  long 
unsigned  long 
unsigned  long 
unsigned  long 


sc , 

f i 1 1 BufferDataUPP , 
♦fill BufferDataRefCon , 
♦outputBuffer , 
outputBufferByteSi ze , 
♦bytesWri tten , 

*f ramesWri tten , 
♦outputFl ags  )  ; 


sc 

The  sound  converter  identifier  returned  by  SoundConverterOpen  (III— 1867). 
f i 1 1 BufferDataUPP 

A  Universal  Procedure  Pointer  that  points  at  a 

SoundConverterFill  BufferDataProc  (III— 2148)  callback,  which  can  provide  data 
to  the  Sound  Converter.  See  "Universal  Procedure  Pointers"  (IV-2641). 
fill BufferDataRefCon 

A  pointer  that  is  passed  to  the  SoundConverterFi  1 1  BufferDataProc  (III— 2148) 
callback.  You  can  use  it  to  point  to  a  data  structure  that  the  callback  accesses. 

outputBuffer 

A  pointer  to  the  buffer  to  write  the  data  into. 
outputBufferByteSi ze 

The  size  of  outputBuffer  mbytes.  No  more  than  this  amount  will  be  written 
during  a  single  call  to  SoundConverterFi  1 1  Buffer. 
bytesWri tten 

On  return,  a  pointer  to  the  number  of  bytes  that  were  written  into  outBuffer. 
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f ramesWri tten 

On  return,  a  pointer  to  the  number  of  sample  frames  written  into  outBuffer. 
outputFl ags 

On  return,  a  pointer  to  a  set  of  bit  flags  (see  below)  that  indicate  the  state  of  the 
conversion  process.  These  are  advisor  flags  only;  they  don't  guarantee  any 
internal  data.  You  need  to  keep  track  of  your  data. 

function  result  This  function  can  return  any  Sound  Manager  error.  See  "Error 
Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

outputFlags  Constants 

kSoundConverterDi dntFillBuffer 

Set  if  the  converter  didn't  completely  fill  the  output  buffer. 
kSoundConverterHasLeftOverData 

Set  if  the  converter  still  has  more  data  to  deliver.  This  indicates  that  more  calls 
to  this  function  should  be  made  to  complete  the  conversion.  If  this  flag  is  not 
set,  it  doesn't  indicate  there  is  necessarily  more  data  in  the  pipeline. 

Discussion 

In  general,  working  with  this  function  is  much  like  working  with 
SoundConverterConvertBuf fer  (III— 1862).  The  differences  begin  with  how  the 
buffering  is  done.  This  function  will  do  as  much  or  as  little  work  as  is  required  to 
satisfy  a  given  request.  This  means  that  you  can  pass  in  buffers  of  any  size  and 
expect  that  the  Sound  Converter  will  only  give  you  that  amount,  at  most.  Moreover, 
the  SoundConverterFi 1 1  Buf  ferDataProc  (III— 2148)  callback  can  be  called  as  many 
times  as  necessary  to  fulfill  a  request.  This  means  that  the  callback  is  free  to  provide 
data  in  whatever  chunk  size  it  likes.  Of  course  with  both  sides,  the  buffer  sizes  will 
control  how  many  times  you  need  to  request  data  and  there  is  a  certain  amount  of 
overhead  for  each  call.  You  will  want  to  balance  this  against  the  performance  you 
require. 

Special  Considerations 

While  a  call  to  SoundConverterGetBufferSi  zes  (III— 1866)  is  not  required  to  use  this 
function,  it  is  useful  as  a  guide  for  non-VBR  formats. 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

See  SoundConverterConvertBuf  fer  (III — 1862). 


Inside  QuickTime:  Functions  R-Z 


III-1865 


SoundConverterGetBufferSizes 


SoundConverterGetBufferSizes 


Determines  actual  input  and  output  buffer  sizes  for  a  given  target  size  in  a  sound 
conversion  process. 


OSErr  SoundConverterGetBufferSizes  ( 


SoundConverter 
unsigned  long 
unsigned  long 
unsigned  long 
unsigned  long 


sc , 

i nputBytesTarget , 
*i  nputFrames , 

*i nputBytes , 
*outputBytes  ) ; 


sc 

The  sound  converter  identifier  returned  by  SoundConverterOpen  (III— 1867). 
i nputBytesTarget 

The  approximate  number  of  bytes  you  would  like  both  your  input  and  output 
buffers  to  be. 
i nputFrames 

A  pointer  to  the  actual  number  of  frames  your  input  buffer  must  hold, 
i nputBytes 

A  pointer  to  the  actual  number  of  bytes  your  input  buffer  must  hold. 
outputBytes 

On  return,  a  pointer  to  the  size  in  bytes  required  for  your  output  buffer. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  used  to  make  sure  your  sound  conversion  buffers  will  fit  the 
conversion  parameters  established  with  SoundConverterOpen  (III— 1867).  The 
returned  input  and  output  buffer  sizes  are  rounded  up,  depending  on  the  format, 
but  they  will  be  very  close  to  the  target  settings.  The  input  and  output  sizes  may  be 
very  different,  depending  on  the  input  and  output  formats  given  in 
SoundConverterOpen.  The  sizes  are  calculated  assuming  you  will  convert  all  data  in 
the  input  buffer  and  pass  it  to  the  output  buffer. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 
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SoundConverterGetlnfo 


Gets  information  from  a  sound  converter,  using  sound  information  selectors. 

OSErr  SoundConverterGetlnfo  ( 

SoundConverter  sc, 

OSType  selector, 

void  *infoPtr  ); 


sc 

The  sound  converter  identifier  returned  bySoundConverterOpen  (III— 1867). 
sel ector 

A  sound  information  selector  that  specifies  the  type  of  information  to  be 
retrieved.  See  "Sound  Information  Selectors"  (IV-2693). 
l nf oPtr 

On  return,  a  pointer  to  the  information.  If  the  information  associated  with  the 
sel  ector  parameter  occupies  4  or  fewer  bytes,  it  is  passed  on  the  stack,  in  the 
i  nf  oPtr  parameter  itself.  Otherwise,  the  i  nfoPtr  parameter  is  a  pointer  to  a 
SoundlnfoList  (IV-2453)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

For  the  corresponding  set  function,  see  SoundConverterSetlnfo  (III— 1868). 


SoundConverterOpen 


Opens  a  sound  converter  component  to  convert  sound  data  from  one  format  to 
another. 


OSErr  SoundConverterOpen  ( 
const  SoundComponentData 
const  SoundComponentData 
SoundConverter 


*1 nputFormat , 
*outputFormat , 
*sc  ) ; 
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i nputFormat 

A  pointer  to  a  SoundComponentData  (IV-2448)  structure  that  defines  the  input 
format. 
outputFormat 

A  pointer  to  a  SoundComponentData  (IV-2448)  structure  that  defines  the  desired 
output  format. 

sc 

On  return,  a  pointer  to  a  sound  converter  identifier  to  be  passed  to  other  sound 
converter  functions. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

During  the  conversion  process,  you  will  call  SoundConverterOpen, 

SoundConverterCl  ose  (III — 1861),  SoundConverterBegi  nConversi  on  (III — 1861)  and 
SoundConverterEndConversi  on  (III— 1863).  To  implement  the  conversion  process,  see 
SoundConverterConvertBuffer  (III — 1862),  SoundConverterFi  1 1  Buffer  (III — 1864),  and 
SoundConverterGetBufferSi zes  (III — 1866). 


SoundConverterSetlnfo 


Sets  the  configuration  of  a  sound  converter,  using  sound  information  selectors. 

OSErr  SoundConverterSetlnfo  ( 

SoundConverter  sc, 

OSType  selector, 

voi d  *1 nfoPtr  ) ; 


sc 

The  sound  converter  identifier  returned  by  SoundConverterOpen  (III— 1867). 
sel ector 

A  sound  information  selector  that  specifies  the  type  of  information  to  be  set.  See 
"Sound  Information  Selectors"  (IV-2693). 
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i nfoPtr 

A  pointer  to  the  information  to  be  set.  If  the  information  associated  with  the 
sel  ector  parameter  occupies  4  or  fewer  bytes,  pass  it  in  the  i  nf  oPtr  parameter 
itself.  Otherwise,  pass  a  pointer  to  a  SoundlnfoLi  st  (IV-2453)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

For  the  corresponding  get  function,  see  SoundConverterGetlnfo  (III— 1867). 


SoundManagerGetlnfo 


Retrieves  information  about  the  Sound  Manager. 

OSErr  SoundManagerGetlnfo  ( 

OSType  selector, 

void  *infoPtr  ); 

sel ector 

A  sound  information  selector  that  specifies  the  type  of  information  to  be 
retrieved.  See  "Sound  Information  Selectors"  (IV-2693). 

i nf oPtr 

On  return,  a  pointer  to  the  information.  If  the  information  associated  with  the 
sel  ector  parameter  occupies  4  or  fewer  bytes,  it  is  passed  on  the  stack,  in  the 
i  nfoPtr  parameter  itself.  Otherwise,  the  i  nfoPtr  parameter  is  a  pointer  to  a 
SoundlnfoLi  st  (IV-2453)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

For  the  corresponding  set  function,  see  SoundManagerSetlnfo  (III— 1870). 
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SoundManagerSetlnfo 


SoundManagerSetlnfo 


Sets  information  about  the  Sound  Manager. 

OSErr  SoundManagerSetlnfo  ( 

OSType  selector, 

const  void  *infoPtr  ); 

sel ector 

A  sound  information  selector  that  specifies  the  type  of  information  to  be  set.  See 
"Sound  Information  Selectors"  (IV-2693). 

i nfoPtr 

A  pointer  to  the  information  to  be  set.  If  the  information  associated  with  the 
sel  ector  parameter  occupies  4  or  fewer  bytes,  pass  it  in  the  i  nfoPtr  parameter 
itself.  Otherwise,  pass  a  pointer  to  a  SoundlnfoLi  st  (IV-2453)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

For  the  corresponding  get  function,  see  SoundManagerGetlnfo  (III— 1869). 


SPBBy  tesT  oMilliseconds 


Determines  the  maximum  duration  of  a  recording  that  can  fit  in  a  buffer  of  a  certain 
size. 

OSErr  SPBBytesToMi 1 1 iseconds  ( 
long  inRefNum, 

1 ong  *byteCount  ) ; 


i nRef Num 

The  device  reference  number  of  a  sound  input  device,  returned  by 
SPBOpenDevi  ce  (III — 1876). 
byteCount 

On  entry,  a  buffer  size  in  bytes.  On  return,  the  number  of  milliseconds  of 
recording  on  the  device  specified  by  the  inRefNum  parameter  that  would  be 
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SPBCloseDevice 


necessary  to  fill  a  buffer  of  such  a  size,  given  the  input  device's  current  sample 
rate,  sample  size,  number  of  channels,  and  compression  factor. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

You  can  call  this  function  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

Related  Java  Methods 

qui  ckti  me .  sound  .  SPBDevi  ce .  bytesToMi  1 1 i seconds ( ) 


SPBCloseDevice 


Closes  a  sound  input  device. 

OSErr  SPBCloseDevice  ( 
long  inRefNum  ); 

i nRef Num 

The  device  reference  number  of  a  sound  input  device,  returned  by 
SPBOpenDevi ce  (III — 1876). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

Because  this  function  moves  or  purges  memory,  you  should  not  call  it  at  interrupt 
time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SPBGetDevicelnfo 


Gets  information  about  the  settings  of  a  sound  input  device. 

OSErr  SPBGetDevicelnfo  ( 
long  inRefNum, 
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OSType  i nfoType, 

void  *infoData  ); 

i nRef Num 

The  device  reference  number  of  the  sound  input  device,  as  obtained  from 
SPBOpenDevi  ce  (III — 1876). 
i nfoType 

A  sound  input  device  information  selector  that  specifies  the  type  of  information 
you  need.  See  "Sound  Information  Selectors"  (IV-2693). 
i nfoData 

A  pointer  to  a  buffer  in  which  information  should  be  returned.  This  buffer  must 
be  large  enough  to  contain  the  type  of  information  specified  in  the  i  nfoType 
parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  uses  a  selector-based  interface  similar  to  SndGetlnfo  (III— 1833),  with 
the  same  sound  information  selectors. 

Special  Considerations 

Because  this  function  might  move  memory,  you  should  not  call  it  at  interrupt  time. 
Check  the  selector  description  of  the  selector  you  want  to  use,  to  see  if  it  moves 
memory,  before  calling  this  function.  Most  of  the  selectors  do  not  move  memory 
and  are  therefore  safe  to  use  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

Related  Java  Methods 

qu ickti me. sound. SPB Device. set  Level  Me terOnOff ( ) , 
qu ickti me. sound. SPB Device. get  Level  Me terOnOff ( ) , 
qu ickti me. sound. SPB Device. get  Level  Me ter  Level ( ) , 
qu ickti me. sound. SPB Device . set Automat i cGainControl ( ) , 
qu ickti me. sound. SPB Device. getAutomati cGainControl ( ) , 
qui cktime. sound. SPB De vice. setlnputGaint ) , 
qu ickti me. sound. SPB Device.getlnputGaint ) , 
quicktime.sound.SPBDevice.getlnputSourceO, 
qui cktime. sound . SPBDevi ce. set  Input Sour ce( ) , 
qu ickti me. sound. SPB De vice. getlnputSourceNamesO, 
qui cktime. sound. SPB Device.getChannel Available! ) , 
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qui ckti me . sound . SPBDevi ce . getNumberChannel  s ( ) , 

qui ckti me . sound . SPBDevi  ce . setNumberChannel s ( ) , 

qui ckti me . sound . SPBDevi ce . get PI ayThruOnOf f ( ) , 

qui ckti me . sound . SPBDevi ce . set Pi ayThruOnOf f ( ) , 

qui ckti me . sound . SPBDevi ce . setSampl e Rate O , 

qui ckti me . sound . SPBDevi ce . getSampl eRate( ) , 

qui ckti me . sound . SPBDevi ce . get Sampl eRateAvai 1 abl e( ) , 

qui ckti me . sound . SPBDevi ce . setSampl eSi ze( ) , 

qui ckti me . sound . SPBDevi ce . getSampl eSi ze( ) , 

qui ckti me . sound . SPBDevi ce . getSampl eSi zeAvai 1 abl e( ) , 

qui ckti me . sound . SPBDevi ce . s et Stereo  I nputGai n( ) , 

qui ckti me . sound . SPBDevi ce . get Stereo  I nputGai nLeft( ) , 

qui ckti me . sound . SPBDevi ce . get Stereo  I nputGai nRi ght( ) , 

qui ckti me . sound . SPBDevi ce . setCompressi onTypel ) , 

qui ckti me . sound . SPBDevi ce . getCompressi onTypel ) , 

qui ckti me . sound . SPBDevi ce . getCompressi onAvai  1  abl  e( ) , 

qui ckti me . sound . SPBDevi ce . ha sOpti onsDi a  1 og( ) , 

qui ckti me . sound . SPBDevi ce . showOpti onsDi al og( ) 

See  Also 

See  SndGetlnfo  (III— 1 833) .  For  the  corresponding  set  function,  seeSPBSetDevicelnfo 
(III— 1881). 

SPBGetlndexedDevice 


Helps  you  generate  a  list  of  sound  input  devices. 

OSErr  SPBGetlndexedDevice  ( 
short  count, 

Str255  deviceName, 

Handle  *devi celconHandl e  ); 

count 

The  index  number  of  the  sound  input  device  you  wish  to  obtain  information 
about. 

devi ceName 

On  return,  the  name  of  the  sound  input  device  specified  by  the  count 
parameter. 
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devi celconHandl e 

On  return,  a  handle  to  the  icon  of  the  sound  input  device  specified  by  the  count 
parameter.  The  memory  for  this  icon  is  allocated  automatically,  but  your 
application  must  dispose  of  it. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Returns  si  BadSoundlnDevi  ce  if  the  value  of  the  count  parameter  is 
greater  than  the  number  of  sound  input  devices. 

Discussion 

Your  application  can  create  a  list  of  sound  input  devices  by  calling  this  function 
with  the  count  parameter  set  to  1  and  incrementing  the  count  parameter  by  1  until 
the  function  returns  si  BadSoundlnDevi  ce. 

Special  Considerations 

Because  the  Sound  In  control  panel  allows  the  user  to  select  a  sound  input  device, 
most  applications  should  not  use  this  function.  Your  application  might  need  to  use 
this  function  if  it  allows  the  user  to  record  from  more  than  one  sound  input  device 
at  once.  This  function  allocates  memory,  so  you  should  not  call  it  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SPBGetRecordingStatus 


Obtains  recording  status  information  about  a  sound  input  device. 


OSErr  SPBGetRecordingStatus  ( 
long  InRefNum, 

short  *recordi ngStatus , 

short  *meterLevel , 

unsigned  long  *total Sampl esToRecord , 

unsigned  long  *numberOfSampl esRecorded , 

unsigned  long  *totalMsecsToRecord, 

unsigned  long  *numberOfMsecsRecorded  ); 


i nRef Num 

On  return,  a  pointer  to  the  device  reference  number  of  the  sound  input  device, 
returned  by  SPBOpenDevi  ce  (III— 1876). 
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recordi ngStatus 

On  return,  a  pointer  to  the  status  of  the  recording.  While  the  input  device  is 
recording,  this  parameter  is  set  to  a  number  greater  than  0.  When  a  recording 
terminates  without  an  error,  this  parameter  is  set  to  0.  When  an  error  occurs 
during  recording  or  the  recording  has  been  terminated  by  a  call  to 
SPBStopRecordi  ng  (III— 1883),  this  parameter  is  less  than  0  and  contains  an  error 
code. 

meterLevel 

On  return,  a  pointer  to  the  current  input  signal  level,  ranging  from  0  to  255. 
total Sampl esTo Record 

On  return,  a  pointer  to  the  total  number  of  samples  to  record,  including  those 
samples  already  recorded. 
numberOf Sampl es Recorded 

On  return,  a  pointer  to  the  number  of  samples  already  recorded, 
total MsecsTo Record 

On  return,  a  pointer  to  the  total  duration  of  recording  time,  including  recording 
time  already  elapsed,  in  milliseconds. 

numberOf Msecs  Recorded 

On  return,  a  pointer  to  the  amount  of  recording  time  that  has  elapsed,  in 
milliseconds. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

You  can  call  this  function  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

Related  Java  Methods 

qui cktime . sound . SPB . i s Recordi ng( ) ,  qui ckti me . sound . SPB .meterLevel ( ) 


SPBMillisecondsT  oBytes 


Determines  how  many  bytes  a  recording  of  a  certain  duration  will  occupy. 

OSErr  SPBMillisecondsToBytes  ( 
long  inRefNum, 

long  *mi 1 1 i seconds  ); 
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i  nRef  Num 

The  device  reference  number  of  the  sound  input  device,  returned  by 
SPBOpenDevi  ce  (III — 1876). 
mi  1 1  i seconds 

On  entry,  the  duration  of  the  recording  in  milliseconds.  On  return,  the  number 
of  bytes  that  sampled-sound  data  would  occupy  for  a  recording  of  the  specified 
duration  on  the  device  specified  by  the  i  nRef  Num  parameter,  given  the  input 
device's  current  sample  rate,  sample  size,  number  of  channels,  and 
compression  factor. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

You  can  call  this  function  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

Related  Java  Methods 

qu i c kt i me. sound. SPB Device. mill isecondsTo By test) 


SPBOpenDevice 


Opens  a  sound  input  device. 

OSErr  SPBOpenDevice  ( 

ConstStr255Param 
short 
1  ong 

devi ceName 

The  name  of  the  sound  input  device  to  open.  You  can  request  that  the  current 
default  sound  input  device  be  opened  by  passing  either  a  0-length  string  or  a 
NIL  string. 

permi ssi on 

A  flag  (see  below)  that  indicates  whether  subsequent  operations  with  that 
device  are  to  be  read /write  or  read-only.  If  the  device  is  not  already  in  use, 
read /write  permission  is  granted;  otherwise,  only  read-only  operations  are 
allowed. 


devi ceName , 
permi ssi on , 
*i nRef Num  ); 
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i nRef Num 

On  return,  if  the  function  is  successful,  a  device  reference  number  for  the  open 
sound  input  device. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

permission  Constants 

si ReadPermi ssi  on 

Open  device  for  reading  only, 
si Wri tePermi ssi on 

Open  device  for  reading  and  writing.  To  make  any  recording  requests  or  to  call 
SPBSetDevi  celnfo  (III— 1881),  read/write  permission  must  be  available. 

Discussion 

Generally,  you  should  open  the  default  device  unless  you  specifically  want  to  use 
some  other  device.  You  can  get  a  list  of  the  available  devices  by  calling 
SPBGetlndexedDevi  ce  (III— 1873).  If  only  one  sound  input  device  is  installed,  that 
device  is  opened. 

Special  Considerations 

Because  this  function  allocates  memory,  you  should  not  call  it  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

Related  Java  Methods 

qui ckti me . sound . SPBDevi ce . SPBDevi ce( ) 


SPBPauseRecording 

Pauses  recording  from  a  sound  input  device. 

OSErr  SPBPauseRecording  ( 
long  i nRef Num  ); 

i nRef Num 

The  device  reference  number  of  the  sound  input  device,  returned  by 
SPBOpenDevi ce  (III — 1876). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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Discussion 

This  function  pauses  recording  for  the  device  specified  by  the  i  nRef  Num  parameter. 
The  recording  must  be  asynchronous  for  this  call  to  have  any  effect. 

Special  Considerations 

You  can  call  this  function  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

Related  Java  Methods 

qu ickti me. sound. SPB. pause Record 1 n  g ( ) 


SPBRecord 


Records  sound  data  into  memory,  either  synchronously  or  asynchronously. 

OSErr  SPBRecord  ( 

SPBPtr  inParamPtr, 

Bool ean  asynchFl ag  ) ; 

i nParamPtr 

A  pointer  to  an  SPB  (IV-2456)  structure.  The  fields  of  this  structure  pass  data  in 
and  out  of  the  function  as  described  below. 

asynchFl ag 

A  Boolean  value  that  specifies  whether  the  recording  occurs  asynchronously 
(TRUE)  or  synchronously  (FALSE). 

function  result  This  function  returns  the  value  that  the  error  field  of  the  SPB 

(IV-2456)  structure  contains  when  recording  finishes.  See  "Error 
Codes"  (IV-2663).  It  returns  noErr  if  there  is  no  error. 

SPB  structure  fields 

1 nRef Num 

The  device  reference  number  of  the  sound  input  device,  as  obtained  from 
SPBOpenDevi  ce  (III — 1876). 
count 

On  input,  the  number  of  bytes  to  record.  If  this  field  indicates  a  longer 
recording  time  than  the  milliseconds  field,  then  the  milliseconds  field  is 
ignored.  On  output,  this  field  indicates  the  number  of  bytes  actually  recorded. 
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mi  1 1 i seconds 

On  input,  the  number  of  milliseconds  to  record.  If  this  field  indicates  a  longer 
recording  time  than  the  count  field,  then  the  count  field  is  ignored.  On  output, 
this  field  indicates  the  number  of  milliseconds  actually  recorded, 
but ferLength 

The  number  of  bytes  in  the  buffer  specified  by  the  bufferPtr  parameter.  If  this 
buffer  length  is  too  small  to  contain  the  amount  of  sampled-sound  data 
specified  in  the  count  field  and  the  milliseconds  field,  then  recording  time  is 
truncated  so  that  the  sampled-sound  data  fits  in  the  buffer. 

bufferPtr 

A  pointer  to  the  buffer  for  the  sampled-sound  data,  or  N I L  if  you  wish  to  record 
sampled-sound  data  without  saving  it.  On  return,  this  buffer  contains  the 
sampled-sound  data,  which  is  interleaved  for  stereo  sound  on  a  sample  basis 
(or  on  a  packet  basis  if  the  data  is  compressed).  This  buffer  contains  only 
sampled-sound  data,  so  if  you  need  a  sampled  sound  header,  you  should  set 
that  up  in  a  buffer  before  calling  this  function  and  then  record  into  the  buffer 
following  the  sound  header, 
comp! eti onRouti ne 

A  pointer  to  an  SICompI  eti  onProc  (III— 2146)  callback.  This  routine  is  called 
when  the  recording  terminates,  either  after  you  call  SPBStopRecordi  ng  (III— 1883) 
or  when  the  prescribed  limit  is  reached.  The  completion  routine  is  called  only 
for  asynchronous  recording, 
i nterruptRouti ne 

A  pointer  to  an  SI  InterruptProc  (III— 2147)  callback.  This  interrupt  routine  is 
called  by  asynchronous  recording  devices  when  their  internal  buffers  are  full. 

userLong 

A  long  integer;  it  can  be  a  pointer  to  a  data  structure  that  passes  data  to  your 
application's  SICompI  eti  onProc  or  SI  InterruptProc  callbacks, 
error 

On  return,  a  value  greater  than  0  while  recording  unless  an  error  occurs,  in 
which  case  it  contains  a  value  less  than  0  that  indicates  an  operating  system 
error.  Your  application  can  poll  this  field  to  check  on  the  status  of  an 
asynchronous  recording.  If  recording  terminates  without  an  error,  this  field 
contains  0. 
unusedl 

Reserved.  You  should  set  this  field  to  0  before  calling  this  function. 
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Discussion 

This  function  starts  recording  into  memory  from  a  device  specified  in  an  SPB 
(IV-2456)  structure.  The  sound  data  recorded  is  stored  in  the  buffer  specified  by  the 
b  u  f  f  e  r  P  t  r  and  b  u  f  f  e  r  L  e  n  g  t  h  fields  of  the  structure.  Recording  lasts  the  longer  of  the 
times  specified  by  the  count  and  milliseconds  fields  of  the  structure,  or  until  the 
buffer  is  filled.  Recording  is  asynchronous  if  the  asynchFl  ag  parameter  is  TRUE  and 
the  specified  sound  input  device  supports  asynchronous  recording. 

If  the  buf  f  erPtr  field  of  the  SPB  structure  contains  NIL,  then  the  count,  mi  1 1  i  seconds, 
and  bufferLength  fields  are  ignored,  and  the  recording  continues  indefinitely  until 
you  call  SPBStopRecordi  ng  (III— 1883).  In  this  case,  the  audio  data  is  not  saved 
anywhere;  this  feature  is  useful  only  if  you  want  to  do  something  in  your  interrupt 
routine  and  do  not  want  to  save  the  audio  data.  However,  if  the  recording  is 
synchronous  and  bufferPtr  is  NIL,  this  function  returns  the  result  code 
si NoBufferSpeci tied. 

Special  Considerations 

You  can  call  this  function  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

Related  Java  Methods 

quickti me. sound. SPB. record! ) 


SPBRecordToFile 


Obsolete. 

OSErr  SPBRecordToFile  ( 
short  fRefNum, 

SPBPtr  inParamPtr, 

Bool ean  asynchFl ag  ) ; 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier.  Macintosh  Note:  Not  supported  by 

CarbonLib. 

Programming  Info 

C  interface  file:  Sound .  h 
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SPBResumeRecording 


Resumes  recording  from  a  sound  input  device. 

OSErr  SPBResumeRecording  ( 
long  inRefNum  ); 

i nRef Num 

The  device  reference  number  of  the  sound  input  device,  returned  by 
SPBOpenDevi ce  (III — 1876). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Recording  on  the  device  specified  by  the  inRefNum  parameter  must  previously  have 
been  paused  by  a  call  to  SPBPauseRecordi  ng  (III— 1877)  for  this  function  to  have  any 
effect. 

Special  Considerations 

You  can  call  this  function  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

Related  Java  Methods 

qui ckti me . sound . SPB . resumeRecordi ng( ) 


SPBSetDevicelnfo 


Sets  information  in  a  sound  input  device. 

OSErr  SPBSetDevicelnfo  ( 
long  inRefNum, 

OSType  infoType, 

void  *infoData  ); 

i nRef Num 

The  device  reference  number  of  the  sound  input  device,  returned  by 
SPBOpenDevi  ce  (III — 1876). 

i nf oType 

A  sound  input  device  information  selector  that  specifies  the  type  of  information 
to  be  set.  See  "Sound  Information  Selectors"  (IV-2693). 


Inside  QuickTime:  Functions  R-Z 


III-1881 


SPBSignlnDevice 


i nfoData 

A  pointer  to  a  buffer.  This  buffer  can  contain  information  on  entry,  and 
information  might  be  returned  on  return.  This  buffer  must  be  large  enough  for 
the  type  of  information  specified  in  the  i  nf  oType  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

Because  this  function  might  move  memory,  you  should  be  careful  about  calling  it  at 
interrupt  time.  Check  the  selector  description  of  the  selector  you  want  to  use  to  see 
if  it  moves  memory.  Most  of  the  selectors  do  not  move  memory  and  are  therefore 
safe  to  use  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

For  the  corresponding  get  function,  see  SPBGetDevi  celnfo  (III— 1871). 


SPBSignlnDevice 

Registers  a  sound  input  device  with  the  Sound  Input  Manager. 

OSErr  SPBSignlnDevice  ( 

short  devi ceRef Num , 

ConstStr255Param  deviceName  ); 

devi ceRef Num 

The  device  driver  reference  number  of  the  sound  input  device  to  register, 
devi ceName 

The  device's  name  as  it  is  to  appear  to  the  user  in  the  Sound  In  control  panel. 
This  is  usually  not  the  name  of  the  driver  used  by  the  Device  Manager. 
Accordingly,  the  name  should  be  as  descriptive  as  possible. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  should  call  this  function  after  you  have  already  opened  your  driver  by  calling 
normal  Device  Manager  routines. 


III-1882 
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SPBSignOutDevice 


Special  Considerations 

Because  this  function  moves  or  purges  memory,  you  should  not  call  it  at  interrupt 
time.  You  can,  however,  call  it  at  system  startup  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SPBSignOutDevice 

Cancels  the  registration  of  a  device  you  have  previously  registered  with 
SPBSignlnDevi ce  (III — 1882). 

OSErr  SPBSignOutDevice  ( 

short  devi ceRef Num  ); 

devi ceRef Num 

The  driver  reference  number  of  the  device  you  wish  to  sign  out. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

When  this  function  cancels  the  registration  of  a  device,  the  device  is  unregistered 
from  the  Sound  Input  Manager's  list  of  available  sound  input  devices  and  no  longer 
appears  in  the  Sound  In  control  panel. 

Special  Considerations 

Ordinarily,  you  should  not  need  to  use  this  function.  You  might  use  it  if  your  device 
driver  detects  that  a  sound  input  device  is  not  functioning  correctly  or  has  been 
disconnected.  Because  this  function  moves  or  purges  memory,  you  should  not  call 
it  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


SPBStopRecording 

Ends  a  recording  session  from  a  sound  input  device. 
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SPBVersion 


OSErr  SPBStopRecordi ng  ( 

1 ong  i nRef Num  ) ; 

i nRef Num 

The  device  reference  number  of  the  sound  input  device,  returned  by 
SPBOpenDevI  ce  (III — 1876). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  recording  process  must  be  asynchronous  for  this  function  to  have  any  effect. 
When  you  call  this  function,  the  SICompI  eti  onProc  (III— 2146)  callback  specified  in 
the  compl  eti  onRouti  ne  field  of  the  SPB  (IV-2456)  structure  is  called  and  the  error 
field  of  that  structure  is  set  to  abortErr.  This  structure  was  set  up  by  the  previous 
call  to  SPBRecord  (III— 1878).  If  you  are  writing  a  device  driver,  you  will  receive  a 
Kill  10  status  call. 

Special  Considerations 

You  can  call  this  function  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 

Related  Java  Methods 

qu ickti me. sound. SPB. stop Record ing() 


SPBVersion 

Determines  the  version  of  the  sound  input  tools  available  on  the  user's  computer. 
NumVersion  SPBVersion  (  void  ); 

function  result  ANumVersion  (IV-2324)  structure  that  contains  Sound  Input  Manager 
version  information. 


Special  Considerations 

You  can  call  this  function  at  interrupt  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


III-1884 
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SpriteHitTest 


SpriteHitTest 

Determines  whether  a  location  in  a  sprite's  display  coordinate  system  intersects  the 
sprite. 

OSErr  SpriteH 
Spri te 
1  ong 
Poi  nt 
Bool ean 

theSpri te 

The  sprite  for  this  operation, 
fl  ags 

Specifies  flags  (see  below)  that  control  the  hit  testing  operation. 

1  oc 

A  point  in  the  sprite  world's  display  space  to  test  for  the  existence  of  a  sprite. 
You  should  apply  the  sprite  world's  matrix  to  the  point  before  passing  it  to  this 
function. 
wasHi t 

A  pointer  toaBoolean.  On  return,  the  value  of  the  Boolean  is  TRUE  if  the  sprite  is 
at  the  specified  location. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

flags  Constants 

spri teHi tTest Bounds 

The  specified  location  must  be  within  the  sprite's  bounding  box. 
spri teHi tTest Image 

If  both  this  flag  and  spriteHitTestBounds  are  set,  the  specified  location  must  be 
within  the  shape  of  the  sprite's  image, 
spri teHi tTestlnvi si bl  eSpri  tes 

This  flag  enables  invisible  sprites  to  be  hit  tested, 
spri teHi tTest I sCl  i  ck 

This  flag  is  for  codecs  that  want  mouse  events,  such  as  the  Ripple  codec, 
spri teHi tTest Loci nDi s pi ayCoordi  nates 

Set  this  flag  if  you  want  to  pass  a  display  coordinate  point  in  the  1  oc  parameter. 


i tTest  ( 
theSpri te , 
fl ags , 

1  oc , 

*wasHit  ); 
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SpriteMediaCountlmages 


Discussion 

This  function  is  useful  for  hit  testing  a  subset  of  the  sprites  in  a  sprite  world  and  for 
detecting  multiple  hits  for  a  single  location. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Creating  and  Manipulating  Sprites"  (V-2901) 

Related  Java  Methods 

qui cktime. std . anim. Spri te. hi tTest ( ) 


SpriteMediaCountlmages 


Retrieves  the  number  of  images  that  currently  exist  in  a  sprite  track. 

ComponentResul t  SpriteMediaCountlmages  ( 

MediaHandler  mh, 

short  *numlmages  ) ; 


mh 

The  sprite  media  handler  for  this  operation, 
numlmages 

A  pointer  to  a  short  integer.  On  return,  this  integer  contains  the  number  of 
images  for  the  sprite  media's  current  time. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

This  function  determines  the  number  of  images  that  currently  exist  based  on  the  key 
frame  that  is  in  effect. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Managing  Movie  Sprites"  (V-2902) 

Related  Java  Methods 

qui  cktime.  std.  mo  vies,  media.  SpriteMediaHandler.countlmagesO 


III-1886 
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SpriteMediaCountSprites 


SpriteMediaCountSprites 


Retrieves  the  number  of  sprites  that  currently  exist  in  a  sprite  track. 

ComponentResul t  SpriteMediaCountSprites  ( 

MediaHandier  mh, 

short  *numSprites  ); 


mh 

The  sprite  media  handler  for  this  operation. 
numSpri tes 

A  pointer  to  a  short  integer.  On  return,  this  integer  contains  the  number  of 
sprites  for  the  sprite  media's  current  time. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

This  function  determines  the  number  of  sprites  that  currently  exist  based  on  the  key 
frame  that  is  in  effect. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Managing  Movie  Sprites"  (V-2902) 

Related  Java  Methods 

qui  cktime .  std  .movi  es  .medi  a  .  Spri  teMedi  aHandler.countSpritesO 


SpriteMediaDisposeSprite 


Disposes  of  memory  allocated  for  a  sprite. 

ComponentResul t  SpriteMediaDisposeSprite  ( 
MediaHandier  mh, 

QTAtomID  spritelD  ); 


mh 

The  sprite  media  handler  for  this  operation, 
spri telD 

The  ID  of  the  sprite  for  this  operation. 
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SpriteMediaGetActionVariable 


function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es .  h 


SpriteMediaGet  Action  V  ariable 


Returns  the  value  of  the  sprite  track  variable  with  the  specified  ID. 

ComponentResul t  SpriteMediaGetActionVariable  ( 

MediaHandler  mh, 

QTAtomlD  variablelD, 

float  *value  ); 


mh 

The  sprite  media  handler  for  this  operation, 
vari abl elD 

A  variable  ID  of  the  sprite  variable, 
val  ue 

A  pointer  to  a  floating-point  value.  If  the  specified  variable  has  never  been  set, 
the  value  is  set  to  0  and  the  error  cannotFi  ndAtomErr  is  returned. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Wired  Sprites"  (V-2903) 

Related  Java  Methods 

qu ickti me. std. mo vies. media. Sprite MediaHandler. getActi onVariablet ) 


See  Also 

For  the  corresponding  set  function,  see  Spri  teMedi  aSetActi  onVari  abl  e  (III— 1901). 
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SpriteMediaGetActionVariableAsString 


SpriteMediaGetActionVariableAsString 


Undocumented 

ComponentResul t  Spri teMedi aGetActi onVari abl eAsString  ( 
Medi aHandl er  mh, 

QTAtomID  variablelD, 

Handle  *theCString  ); 


mh 

The  sprite  media  handler  for  this  operation, 
vari  abl  elD 

A  variable  ID  of  the  sprite  variable. 
theCStri ng 

A  pointer  to  a  handle  to  a  C  string. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


SpriteMediaGetDisplayedSampleNumber 


Retrieves  the  number  of  the  sprite  media  sample  that  is  currently  being  displayed. 

ComponentResul t  Spri teMedi aGetDi spl ayedSampl eNumber  ( 

MediaHandler  mh, 

long  *sampleNum  ); 


mh 

The  sprite  media  handler  for  this  operation, 
sampl eNum 

A  pointer  to  a  long  integer.  On  return,  this  integer  contains  the  number  of  the 
sample  that  is  currently  being  displayed. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 
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SpriteMediaGetlmageN  ame 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi es .  h 

Programming  summary:  "Managing  Movie  Sprites"  (V-2902) 

Related  Java  Methods 

quicktime.std.movies.media.SpriteMediaHandler.getDisplayedSampl e Number ( ) 


SpriteMediaGetlmageName 


Returns  the  name  of  the  image  with  the  specified  index  from  the  current  key  frame 
sample. 

ComponentResul t  SpriteMediaGetlmageName  ( 

MediaHandler  mh, 

short  imagelndex, 

Str255  i mageName  ) ; 


mh 

The  sprite  media  handler  for  this  operation, 
i magelndex 

The  index  of  the  image  whose  image  name  is  to  be  retrieved.  This  value  must 
be  between  1  and  the  number  of  available  images.  You  can  determine  how 
many  images  are  available  by  calling  Spri  teMedi  aCountlmages  (III— 1886). 

i mageName 

Returns  a  Pascal  string  with  the  image  name  of  the  image,  or  an  empty  string  if 
the  image  is  unnamed. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Managing  Movie  Sprites"  (V-2902) 

Related  Java  Methods 

qu i c kt i me. std. mo vies. media. SpriteMediaHandler.getlmageNameO 


III-1890 
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SpriteMediaGetlndlmageDescription 


SpriteMediaGetlndlmageDescription 


Retrieves  an  image  description  for  a  specified  image  in  a  sprite  track. 

ComponentResul t  Spri teMedi aGetlndlmageDescription  ( 

MediaHandler  mh, 

short  imagelndex, 

ImageDescri pti onHandl e  imageDescri pti on  ); 


mh 

The  sprite  media  handler  for  this  operation. 

Imagelndex 

The  index  of  the  image  whose  image  description  is  to  be  retrieved.  This  value 
must  be  between  1  and  the  number  of  available  images.  You  can  determine  how 
many  images  are  available  by  calling  Spri  teMedi  aCountlmages  (III— 1886). 
i mageDescri pti on 

Specifies  an  image  description  handle.  On  return,  this  handle  contains  the 
ImageDescri  pti  on  (IV-2285)  structure  that  describes  the  specified  image.  This 
handle  must  be  unlocked;  the  function  resizes  the  handle  if  necessary. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Managing  Movie  Sprites"  (V-2902) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Spri teMedi aHandl er. get  I nd I mageDescri pti  on () 


SpriteMediaGetlndlmageProperty 

Returns  a  property  value  for  a  sprite  image  specified  by  an  index. 


ComponentResul t  SpriteMediaGetlndlmageProperty  ( 
MediaHandler  mh, 
short  imagelndex, 

long  imagePropertyType , 

void  *imagePropertyVal ue  ); 
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SpriteMediaGetlndlmageProperty 


mh 

The  sprite  media  handler  for  this  operation, 
i magelndex 

The  index  of  the  image  whose  property  value  is  to  be  retrieved.  This  value  must 
be  between  1  and  the  number  of  available  images.  You  can  determine  how 
many  images  are  available  by  calling  Spri  teMedi  aCountlmages  (III— 1886). 

i mage Property Type 

The  property  whose  value  should  be  retrieved  (see  below). 
imageProperty Value 

A  pointer  to  a  variable  that  will  hold  the  selected  property  value  on  return. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

imagePropertyType  Constants 

kSpritePropertyMatrix 

The  propertyVal  ue  parameter  returns  the  sprite's  MatrixRecord  (IV-2304) 
structure. 

kSpritePropertylmageDescription 

The  propertyVal  ue  parameter  returns  an  ImageDescri  pti  onHandl  e,  which  is  a 
handle  to  the  sprite's  ImageDescri  pti  on  (IV-2285)  structure. 
kSpritePropertylmageDataPtr 

The  propertyVal  ue  parameter  returns  a  Ptr,  which  is  a  pointer  to  the  sprite's 
image  data. 

kSpriteProperty Visible 

The  propertyVal  ue  parameter  returns  a  Bool  ean  that  is  TRUE  if  the  sprite  is 
visible,  FALSE  otherwise. 

kSpri teP rope rty Layer 

The  propertyVal  ue  parameter  returns  the  sprite's  layer  number. 
kSpri teProperty Graphics Mode 

The  propertyVal  ue  parameter  returns  the  sprite's 
Modi  f  i  erT rackGraphi  csModeRecord  (IV-2311). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Managing  Movie  Sprites"  (V-2902) 
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SpriteMediaGetProperty 


Related  Java  Methods 

qui cktime . std .movi es .medi a . Spri teMedi aHandler. get  Spri  tel  mageGroupIDO, 
qui cktime . std .movi es .medi a . Spri teMedi aHandler. get Spri  telmageRegi  strati  onPoi 
nt( ) 


SpriteMediaGetProperty 

Gets  a  sprite  property;  superseded  by  Spri  teMedi  aGetSpri  teProperty  (III— 1896). 

ComponentResul t  SpriteMediaGetProperty  ( 

MediaHandler  mh, 
short  spritelndex, 

long  propertyType , 

void  *propertyVal ue  ); 

mh 

The  sprite  media  handler  for  this  operation, 
spri telndex 

The  index  of  the  sprite  for  this  operation. 
propertyType 

The  property  whose  value  should  be  retrieved  (see  below). 
propertyVal ue 

A  pointer  to  a  variable  that  will  hold  the  selected  property  value  on  return. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

propertyType  Constants 

kSpri tePropertyMatri x 

The  propertyVal  ue  parameter  returns  the  sprite's  MatrixRecord  (IV-2304) 
structure. 

kSpri teProperty ImageDescri  pti  on 

The  propertyVal  ue  parameter  returns  an  ImageDescri  pti  onHandl  e,  which  is  a 
handle  to  the  sprite's  ImageDescri  pti  on  (IV-2285)  structure. 

kSpri tePropertylmageDataPtr 

The  propertyVal  ue  parameter  returns  a  Ptr,  which  is  a  pointer  to  the  sprite's 
image  data. 


Inside  QuickTime:  Functions  R-Z 


III-1893 


SpriteMediaGetSpriteActionsForQTEvent 


kSpriteProperty Visible 

The  propertyVal  ue  parameter  returns  a  Bool  ean  that  is  TRUE  if  the  sprite  is 
visible,  FALSE  otherwise. 
kSpri teP rope rty Layer 

The  propertyVal  ue  parameter  returns  the  sprite's  layer  number. 
kSpri teProperty Graphics Mode 

The  propertyVal  ue  parameter  returns  the  sprite's 
Modi  f  i  erT rackGraphi  csModeRecord  (IV-2311). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi es .  h 

See  Also 

For  the  corresponding  set  function,  see  Spri  teMedi  aSetProperty  (III— 1903). 


SpriteMediaGetSpriteActionsForQTEvent 


Gets  the  sprite  action  atom  for  an  event. 


ComponentResul t  Spri teMedi aGetSpri teActi onsForQTEvent  ( 
MediaHandler  mh, 

QTEventRecordPtr  event, 

QTAtomID  spritelD, 

QTAtomContai ner  Container, 

QTAtom  *atom  ); 


mh 

The  sprite  media  handler  for  this  operation, 
event 

A  pointer  to  a  QTEventRecord  (IV-2353)  structure, 
spri telD 

The  ID  of  the  sprite  for  this  operation, 
contai ner 

A  pointer  to  a  QT  atom  container. 

atom 

A  pointer  to  a  QT  atom  in  the  container. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 


III-1894 
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SpriteMediaGetSpriteName 


(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


SpriteMediaGetSpriteName 


Returns  the  name  of  the  sprite  with  the  specified  ID  from  the  currently  displayed 
sample. 

ComponentResul t  SpriteMediaGetSpriteName  ( 

MediaHandler  mh, 

QTAtomID  spritelD, 

Str255  spriteName  ); 


mh 

The  sprite  media  handler  for  this  operation, 
spri telD 

The  sprite  ID  of  the  sprite  name, 
spri teName 

Returns  a  Pascal  string  with  the  name  of  the  sprite  or  an  empty  string  if  the 
sprite  is  unnamed. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Managing  Movie  Sprites"  (V-2902) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Spri teMedi aHandl er. get Spri teName () 
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SpriteMediaGetSpriteProperty 


SpriteMediaGetSpriteProperty 


Retrieves  the  value  of  the  specified  sprite  property. 

ComponentResul t  SpriteMediaGetSpriteProperty  ( 
MediaHandler  mh, 

QTAtomlD  spritelD, 

long  propertyType , 

void  *propertyVal ue  ); 


mh 

The  sprite  media  handler  for  this  operation, 
spri telD 

The  ID  of  the  sprite  for  this  operation. 
propertyType 

The  property  whose  value  should  be  retrieved  (see  below). 
propertyVal ue 

On  return,  a  pointer  to  the  value  of  the  property;  the  data  type  of  that  value 
depends  on  the  property. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

propertyType  Constants 

kSpritePropertyMatrix 

The  propertyVal  ue  parameter  returns  the  sprite's  MatrixRecord  (IV-2304) 
structure. 

kSpritePropertylmageDescription 

The  propertyVal  ue  parameter  returns  an  ImageDescri  pti  onHandl  e,  which  is  a 
handle  to  the  sprite's  ImageDescri  pti  on  (IV-2285)  structure. 
kSpritePropertylmageDataPtr 

The  propertyVal  ue  parameter  returns  a  Ptr,  which  is  a  pointer  to  the  sprite's 
image  data. 

kSpriteProperty Visible 

The  propertyVal  ue  parameter  returns  a  Bool  ean  that  is  TRUE  if  the  sprite  is 
visible,  FALSE  otherwise. 

kSpri teP rope rty Layer 

The  propertyVal  ue  parameter  returns  the  sprite's  layer  number. 
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SpriteMediaHitTestAllSprites 


kSpri tePropertyGraphi csMode 

The  propertyVal  ue  parameter  returns  the  sprite's 
ModifierTrackGraphi  csMode  Record  (IV-2311). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Managing  Movie  Sprites"  (V-2902) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Spri teMedi aHandl er . getMatrixC ) , 
qui cktime . std .movi es .medi a . Spri teMedi aHandl er . get Vi  si bl e( ) , 
qui cktime . std .movi es .medi a . Spri teMedi aHandl  er . get Layer ( ) , 
qui cktime . std .movi es .medi a . Spri teMedi aHandl er . getGraphi  csModeC ) , 
qui cktime . std .movi es .medi a . Spri teMedi aHandl er. get  I ma gel ndex() 

See  Also 

For  the  corresponding  set  function,  see  Spri  teMedi  aSetSpriteProperty  (III— 1904). 


SpriteMediaHitT  est  AllSprites 


Determines  whether  any  sprites  are  at  a  specified  location. 


ComponentResul t  Spri teMedi a H i tTestAl 1 Spri tes 
MediaHandler  mh, 
long  flags. 

Point  loc, 

QTAtomID  *spriteHitID  ); 


( 


mh 

The  sprite  media  handler  for  this  operation, 
fl  ags 

Specifies  flags  (see  below)  that  control  the  hit  testing  operation. 

1  oc 

A  point  in  the  coordinate  system  of  the  sprite  track's  movie  to  test  for  the 
existence  of  a  sprite, 
spri teHi tID 

A  pointer  to  a  short  integer.  On  return,  this  integer  contains  the  ID  of  the 
frontmost  sprite  at  the  location  specified  by  1  oc.  If  no  sprite  exists  at  the 
location,  the  function  sets  the  value  of  this  parameter  to  0. 
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SpriteMediaHitTestOneSprite 


function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

flags  Constants 

spriteHitTestBounds 

The  specified  location  must  be  within  the  sprite's  bounding  box. 
spriteHitTestlmage 

If  both  this  flag  and  spriteHitTestBounds  are  set,  the  specified  location  must  be 
within  the  shape  of  the  sprite's  image. 
spriteHitTestlnvisIbleSprites 

This  flag  enables  invisible  sprites  to  be  hit  tested. 
spriteHitTestlsClick 

This  flag  is  for  codecs  that  want  mouse  events,  such  as  the  Ripple  codec. 
spriteHitTestLocInDi splay Coordinates 

Set  this  flag  if  you  want  to  pass  a  display  coordinate  point  in  the  1  oc  parameter. 

Discussion 

You  call  this  function  to  determine  whether  any  sprites  exist  at  a  specified  location 
in  the  coordinate  system  of  a  sprite  track's  movie.  You  can  pass  flags  to  this  function 
to  control  the  hit  testing  operation  more  precisely.  For  example,  you  may  want  the 
hit  test  operation  to  detect  a  sprite  whose  bounding  box  contains  the  specified 
location. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Managing  Movie  Sprites"  (V-2902) 

Related  Java  Methods 

quicktime.std.movies.media.SpriteMediaHandler.hitTestAllSpritesO 


SpriteMediaHitT  estOneSprite 


Performs  a  hit  testing  operation  on  the  sprite  specified  by  a  s  p  r  i  t  e  I D . 


ComponentResul t  SpriteMediaHitTestOneSprite  ( 
MediaHandler  mh, 

QTAtomlD  spritelD, 

long  flags, 

Point  loc, 
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SpriteMediaHitTestOneSprite 


Boolean  *wasHit  ); 


mh 

The  sprite  media  handler  for  this  operation, 
sprl telD 

The  sprite  ID  of  the  sprite, 
fl  ags 

Flags  (see  below)  that  control  the  hit  testing  operation. 

1  oc 

A  point  to  test  for  the  existence  of  a  sprite.  The  point  should  be  defined  in  the 
local  coordinates  of  the  sprite  track,  unless  the 
spri  teH  i  tTest  Loci  nDispl  ay  Coordinates  flag  is  set. 

was  Hi t 

A  pointer  to  a  Bool  ean.  If  the  sprite  is  hit,  wasHi  t  is  set  to  TRUE;  otherwise,  it  is 
set  to  FALSE. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

flags  Constants 

spri teHi tTest Bounds 

The  specified  location  must  be  within  the  sprite's  bounding  box. 
spri teHi tTest Image 

If  both  this  flag  and  spriteHitTestBounds  are  set,  the  specified  location  must  be 
within  the  shape  of  the  sprite's  image. 

spri teHi tTestlnvi si bl eSpri tes 

This  flag  enables  invisible  sprites  to  be  hit  tested, 
spri teHi tTest I sCl  i  ck 

This  flag  is  for  codecs  that  want  mouse  events,  such  as  the  Ripple  codec, 
spri teHi tTest Loci nDi s pi ayCoordi  nates 

Set  this  flag  if  you  want  to  pass  a  display  coordinate  point  in  the  1  oc  parameter. 

Discussion 

This  routine  allows  you  to  hit  test  a  sprite  which  is  fully  or  partially  covered  by 
other  sprites. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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SpriteMediaHitTestSprites 


Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Managing  Movie  Sprites"  (V-2902) 

Related  Java  Methods 

quickti  me.  std.  mo  vies,  media.  SpriteMediaHandler.hltTestOneSpriteO 


SpriteMediaHitT  estSprites 

Undocumented 

ComponentResul 
Medi aHandl 
1  ong 
Poi  nt 
short 

mh 

The  sprite  media  handler  for  this  operation, 
fl  ags 

Flags  (see  below)  that  control  the  hit  testing  operation. 

1  oc 

A  point  to  test  for  the  existence  of  a  sprite, 
spri teHi tlndex 
Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

flags  Constants 

spri teHi tTestBounds 

The  specified  location  must  be  within  the  sprite's  bounding  box. 
spri teHi tTestl mage 

If  both  this  flag  and  spriteHitTestBounds  are  set,  the  specified  location  must  be 
within  the  shape  of  the  sprite's  image. 

spri teHi tTestlnvi si bleSprites 

This  flag  enables  invisible  sprites  to  be  hit  tested, 
spri teHi tTestlsClick 

This  flag  is  for  codecs  that  want  mouse  events,  such  as  the  Ripple  codec. 


t  SpriteMediaHitTestSprites  ( 
er  mh , 

fl ags , 

1  oc , 

*spri teHi tlndex  ) ; 
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spri teHi tTestLocInDi spl ayCoordi  nates 

Set  this  flag  if  you  want  to  pass  a  display  coordinate  point  in  the  1  oc  parameter. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


SpriteMediaNewSprite 


Creates  a  new  sprite. 

ComponentResul t  SpriteMediaNewSprite  ( 
MediaHandier  mh, 

QTRuntimeSpri teDescPtr  newSpri teDesc  ); 


mh 

The  sprite  media  handler  for  this  operation. 
newSpri teDesc 

A  pointer  to  a  QTRunti  meSpri  teDescStruct  (IV-2363)  structure. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


Spri  teMediaSet  Action  V  ariable 


Sets  the  value  of  a  sprite  track  variable  to  a  specified  value. 

ComponentResul t  Spri teMedi aSetActionVari abl e  ( 
MediaHandier  mh, 

QTAtomID  variablelD, 

const  float  *value  ); 


mh 

The  sprite  media  handler  for  this  operation. 
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SpriteMediaSetActionVariableToString 


vari abl elD 

A  variable  ID  of  the  sprite  name, 
val  ue 

A  pointer  to  a  floating-point  number.  The  value  is  passed  by  reference. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

This  function  is  specific  to  sprite  tracks  using  wired  sprites. 

Special  Considerations 

This  function  is  specific  to  sprite  tracks  using  wired  sprites. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  With  Wired  Sprites"  (V-2903) 

Related  Java  Methods 

qu ickti me. std. mo vies. media. SpriteMediaHandl er . set Act i onVariablet ) 


See  Also 

For  the  corresponding  get  function,  see  Spri  teMedi  aGetActi onVari  abl  e  (III— 1888). 


SpriteMediaSet  Action  V  ariableT  oString 


Undocumented 

ComponentResul t  Spri teMedi aSetActi onVari abl eToString  ( 
MediaHandler  mh, 

QTAtomlD  variablelD, 

Ptr  theCStri ng  ) ; 


mh 

The  sprite  media  handler  for  this  operation, 
vari abl elD 

A  variable  ID  of  the  sprite  variable. 
theCStri ng 

A  pointer  to  a  C  string. 

function  residt  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
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SpriteMediaSetProperty 


(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


SpriteMediaSetProperty 


Sets  a  sprite  property;  superseded  by  Spri  teMedi  aSetSpri  teProperty  (III— 1904). 

ComponentResul t  SpriteMediaSetProperty  ( 

MediaHandler  mh, 
short  spritelndex, 

long  propertyType , 

void  *propertyVal ue  ); 

mh 

The  sprite  media  handler  for  this  operation, 
spri telndex 

The  index  of  the  sprite  for  this  operation. 
propertyType 

The  property  whose  value  should  be  set  (see  below). 
propertyVal ue 

A  pointer  to  a  variable  that  contains  the  new  value  of  the  selected  property.  The 
type  of  data  you  pass  for  this  parameter  depends  on  the  property  type. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

propertyType  Constants 

kSpri tePropertyMatri x 

The  propertyVal  ue  parameter  returns  the  sprite's  MatrixRecord  (IV-2304) 
structure. 

kSpri teProperty ImageDescri  pti  on 

The  propertyVal  ue  parameter  returns  an  ImageDescri  pti  onHandl  e,  which  is  a 
handle  to  the  sprite's  ImageDescri  pti  on  (IV-2285)  structure. 
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SpriteMediaSetSpriteProperty 


kSpritePropertylmageDataPtr 

The  propertyVal  ue  parameter  returns  a  Ptr,  which  is  a  pointer  to  the  sprite's 
image  data. 

kSpriteProperty Visible 

The  propertyVal  ue  parameter  returns  a  Bool  ean  that  is  TRUE  if  the  sprite  is 
visible,  FALSE  otherwise. 

kSpri teP rope rty Layer 

The  propertyVal  ue  parameter  returns  the  sprite's  layer  number. 
kSpri teProperty Graphics Mode 

The  propertyVal  ue  parameter  returns  the  sprite's 
Modi  f  i  erT rackGraphi  csModeRecord  (IV-2311). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

See  Also 

For  the  corresponding  get  function,  see  Spri  teMedi  aGetProperty  (III— 1893). 


SpriteMediaSetSpriteProperty 


Sets  the  specified  property  of  a  sprite. 

ComponentResul t  SpriteMediaSetSpriteProperty  ( 
MediaHandler  mh, 

QTAtomlD  spritelD, 

long  propertyType , 

void  *propertyVal ue  ); 


mh 

The  sprite  media  handler  for  this  operation, 
spri telndex 

The  index  of  the  sprite  for  this  operation. 
propertyType 

The  property  whose  value  should  be  retrieved  (see  below). 
propertyVal ue 

A  pointer  to  the  new  value  of  the  selected  property.  The  type  of  data  you  pass 
for  this  parameter  depends  on  the  property  type. 
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SpriteMediaSetSpriteProperty 


function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

propertyType  Constants 

kSpri tePropertyMatri x 

The  propertyVal  ue  parameter  returns  the  sprite's  MatrixRecord  (IV-2304) 
structure. 

kSpri te Property ImageDescri pti on 

The  propertyVal  ue  parameter  returns  an  ImageDescri  pti  onHandl  e,  which  is  a 
handle  to  the  sprite's  ImageDescri  pti  on  (IV-2285)  structure. 
kSpri tePropertylmageDataPtr 

The  propertyVal  ue  parameter  returns  a  Ptr,  which  is  a  pointer  to  the  sprite's 
image  data. 

kSpri tePropertyVi si bl e 

The  propertyVal  ue  parameter  returns  a  Bool  ean  that  is  TRUE  if  the  sprite  is 
visible,  FALSE  otherwise. 
kSpri tePropertyLayer 

The  propertyVal  ue  parameter  returns  the  sprite's  layer  number. 
kSpri tePropertyGraphi csMode 

The  propertyVal  ue  parameter  returns  the  sprite's 
ModifierTrackGraphi  csMode  Record  (IV-2311). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Managing  Movie  Sprites"  (V-2902) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Spri teMedi aHandl er . setMatrix! ) , 
qui cktime . std .movi es .medi a . Spri teMedi aHandl er . set Vi  si bl e( ) , 
qui cktime . std .movi es .medi a . Spri teMedi aHandl  er . set Layer! ) , 
qui cktime . std .movi es .medi a . Spri teMedi aHandl er . setGraphi  csMode! ) , 
qui cktime . std .movi es .medi a . Spri teMedi aHandl er. s et I ma gel ndex!) 


See  Also 

For  the  corresponding  get  function,  see  Spri  teMedi  aGetSpri  teProperty  (III— 1896). 
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SpriteMediaSpritelDToIndex 


SpriteMediaSpritelDT  olndex 


Converts  a  sprite  ID  to  the  corresponding  sprite  index. 

ComponentResul t  SpriteMediaSpritelDToIndex  ( 
MediaHandler  mh, 

QTAtomlD  spritelD, 

short  *spritelndex  ); 


mh 

The  sprite  media  handler  for  this  operation, 
spri telD 

The  ID  of  the  sprite  for  this  operation, 
spri telndex 

On  return,  a  pointer  to  the  index  of  the  sprite. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Managing  Movie  Sprites"  (V-2902) 

Related  Java  Methods 

qu i c kti me. std. mo vies. media. SpriteMed iaHandler.spritelDt olndex () 


SpriteMediaSpritelndexT  oID 


Returns  the  ID  of  a  sprite  specified  by  a  sprite  index. 

ComponentResul t  Spri teMediaSpri telndexToID  ( 
MediaHandler  mh, 

short  spritelndex, 

QTAtomlD  *spriteID  ); 


mh 

The  sprite  media  handler  for  this  operation, 
spri telndex 

The  index  of  the  sprite  for  this  operation. 
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Sprite  WorldHitTest 


spri telD 

A  pointer  to  the  sprite  ID  corresponding  to  the  sprite  index.  If  a  sprite  with  the 
specified  index  does  not  exist,  the  error  paramErris  returned. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Managing  Movie  Sprites"  (V-2902) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Spri teMedi aHandler.spri telndexToIDi ) 


SpriteWorldHitTest 

Determines  whether  any  sprites  are  at  a  specified  location  in  a  sprite  world. 

OSErr  SpriteWorldHitTest  ( 

SpriteWorld  theSpri  teWorl  d  , 
long  flags. 

Point  loc. 

Sprite  *spriteHit  ); 

theSpri teWorl d 

The  sprite  world  for  this  operation, 
fl  ags 

Specifies  flags  (see  below)  that  control  the  hit  testing  operation. 

1  oc 

A  point  in  the  sprite  world's  display  space  to  test  for  the  existence  of  a  sprite, 
spri teHi t 

A  pointer  to  a  field  that  is  to  receive  a  sprite  identifier.  On  return,  this  field 
contains  the  identifier  of  the  frontmost  sprite  at  the  location  specified  by  the  1  oc 
parameter.  If  no  sprite  exists  at  the  location,  the  function  sets  the  value  of  this 
parameter  to  NIL. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 
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Sprite  Worldldle 


flags  Constants 

spriteHitTestBounds 

The  specified  location  must  be  within  the  sprite's  bounding  box. 
spriteHitTestlmage 

If  both  this  flag  and  spriteHitTestBounds  are  set,  the  specified  location  must  be 
within  the  shape  of  the  sprite's  image. 

spri teHi tTestlnvi si bl eSpri  tes 

This  flag  enables  invisible  sprites  to  be  hit  tested, 
spri teHi tTestlsClick 

This  flag  is  for  codecs  that  want  mouse  events,  such  as  the  Ripple  codec, 
spri teHi tTestLocInDi splay Coordinates 

Set  this  flag  if  you  want  to  pass  a  display  coordinate  point  in  the  1  oc  parameter. 

Discussion 

If  you  are  drawing  the  sprite  world  in  a  window,  you  should  convert  the  location 
to  your  window's  local  coordinate  system  before  passing  it  to  Spri  teWorl  dHi  tTest. 
A  hit  testing  operation  does  not  occur  unless  you  pass  either  spriteHitTestBounds 
or  spri  teHi  tTest  Image  in  the  flags  parameter.  You  can  add  other  flags  as  needed. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Working  with  Sprite  Worlds"  (V-2900) 

Related  Java  Methods 

qui cktime. std . anim. Spri teWorl d . hi tTest ( ) 


SpriteW  orldldle 


Allows  a  sprite  world  to  update  its  invalid  areas. 

OSErr  Spri teWorl dldl e  ( 

SpriteWorld  theSpri teWorl d , 

long  flagsln, 

long  *flagsOut  ); 


theSpri teWorl d 

The  sprite  world  for  this  operation. 
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SpriteWorldldle 


fl agsln 

Contains  flags  (see  below)  describing  actions  that  may  take  place  during  the 
idle.  For  the  default  behavior,  set  this  parameter  to  0. 
f 1 agsOut 

On  return,  a  pointer  to  flags  (see  below)  describing  actions  that  took  place 
during  the  idle  period.  This  parameter  is  optional;  if  you  do  not  need  the 
information,  set  it  to  N I L. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

flagsln  Constants 

kOnlyDrawToSpri teWorl d 

Set  this  flag  to  indicate  that  drawing  should  take  place  in  the  sprite  world  only; 
drawing  to  the  final  destination  should  be  suppressed. 
kSpri  teWorl  dPreFl  i  ght 

Set  this  flag  to  determine  whether  the  sprite  world  has  any  invalid  areas  that 
need  to  be  drawn.  If  so,  Spri  teWorl  dldle  returns  the  kSpri  teWorl  dNeedsToDr aw 
flag  in  the  f  1  agsOut  parameter. 

flagsOut  Constants 

kSpri teWorl d  D i dDraw 

If  set,  this  flag  indicates  that  Spri  teWorl  dldl  e  updated  the  sprite  world. 
kSpri teWorl dNeedsToDraw 

If  set,  this  flag  indicates  that  the  sprite  world  has  invalid  areas  that  need  to  be 
drawn. 

Discussion 

This  is  the  only  sprite  function  that  causes  drawing  to  occur;  you  should  call  it  as 
often  as  is  necessary.  Typically,  you  would  make  changes  in  perspective  for  a 
number  of  sprites  and  then  call  SpriteWorldldleto  redraw  the  changed  sprites. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  with  Sprite  Worlds"  (V-2900) 

Related  Java  Methods 

qui cktime . std . anim. Spri teWorl d . i d  1  e ( ) 
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StandardGetFilePreview 


StandardGetFilePreview 

Displays  file  previews  in  an  Open  dialog  box  using  a  standard  file  reply  structure. 

void  StandardGetFilePreview  ( 

Fi  1  eFi  1  terUPP  fileFilter, 

short  numTypes, 

ConstSFTypeLi stPtr  typeList, 

StandardFi 1 eReply  *reply  ); 

fileFilter 

Points  to  a  FileFilterProc  (III— 2082)  callback  that  filters  the  files  that  are 
displayed  to  the  user  in  the  dialog  box.  This  is  an  optional  function  provided  by 
your  application;  if  you  don't  want  to  supply  a  filter  function,  set  this  parameter 
to  NI L.  StandardGetFi  1  ePrevi  ew  uses  this  parameter  along  with  the  numTypes  and 
typeLi  st  parameters  to  determine  which  files  appear  in  the  dialog  box. 
numTypes 

The  number  of  file  types  in  the  array  specified  by  the  typeLi  st  parameter  (a 
number  between  1  and  4).  Set  this  parameter  to  -1  to  display  all  files. 

typeLi  st 

Specifies  an  array  of  file  types  to  be  displayed  to  the  user.  This  function  only 
displays  files  whose  type  matches  an  entry  in  this  array  (unless  you  set  the 
numTypes  parameter  to  -1;  in  this  case,  the  function  displays  all  files  to  the  user), 
reply 

A  pointer  to  the  StandardFi  1  eReply  (IV-2461)  structure  that  is  to  receive 
information  about  the  user's  selection. 

Discussion 

This  function  automatically  converts  files  to  movies  if  your  application  requests 
movies.  If  a  file  could  be  converted  into  a  movie  file  using  a  movie  import 
component,  then  the  file  is  shown  in  the  Standard  File  dialog  box.  The  following 
code  illustrates  a  typical  use  of  this  function: 

//  StandardGetFilePreview  coding  example 
//  See  “Discovering  QuickTime,”  page  385 
Movie  MyGetMovie  (void) 

{ 

OSErr  nErr; 

SFTypeList  types  =  {Movi eFi 1 eType ,  0,  0,  0 } ; 

StandardFi 1 eReply  sfr; 

Movie  movie  =  NIL; 

short  nFileRefNum; 
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StartMovie 


StandardGetFi 1 ePrevi ew( NI L,  1,  types,  &sfr); 
if  (sfr.sfGood)  { 

nErr  =  OpenMovi eFi 1 e(&sf r . sf Fi 1 e ,  &n Fi 1 eRefNum,  fsRdPerm); 
if  (nErr  ==  noErr)  { 

short  nResID  =  0;  //We  want  the  first  movie. 

Str255  strName; 

Boolean  bWasChanged; 

nErr  =  NewMovi eFromFi 1 e(&movi e ,  nFileRefNum,  &nResID,  strName, 

newMovi eActi ve ,  &bWasChanged ) ; 

Cl  oseMovi  eFi  1  e(nFi  1  eRefNum) ; 

} 

} 

return  movie; 

} 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Displaying  File  Previews"  (V-2758) 

Related  Java  Methods 

qui  cktime .  i  o .  QTFi  1  e .  StandardGetFi  1  ePrevi  ew( ) 


StartMovie 

Starts  the  movie  playing  from  the  current  movie  time. 

void  StartMovie  ( 

Movie  theMovie  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 
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StdPix 


Discussion 

You  are  not  required  to  call  this  function  to  start  a  movie.  It  is  included  in  the 
QuickTime  API  for  convenience.  Before  playing  the  movie,  the  Movie  Toolbox 
makes  the  movie  active,  prerolls  the  movie,  and  sets  the  movie  to  its  preferred 
playback  rate.  You  can  use  SetMovi  ePreferredRate  (III— 1626)  to  change  this  setting. 

Special  Considerations 

A  movie's  current  time  is  saved  when  a  movie  is  stored  in  a  movie  file.  Therefore, 
your  application  should  appropriately  position  a  movie  before  playing  the  movie. 
Use  GoToBegi  nni  ngOfMovi  e  (1-550)  to  set  a  movie  to  play  from  its  start. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Controlling  Movie  Playback"  (V-2717) 

Related  Java  Methods 

qui ckti me. std .movi es .Movi e. start ( ) 


StdPix 


Extends  the  grafProcs  field  of  the  CGrafPort  (IV-2168)  structure  to  support 
compressed  data,  mattes,  matrices,  and  pixel  maps,  letting  you  intercept  image  data 
in  compressed  form  before  it  is  decompressed  and  displayed. 


void  StdPix  ( 

Pi xMapPtr 
const  Rect 
Matri xRecordPtr 
short 
RgnHandl e 
Pi xMapPtr 
const  Rect 
short 


src , 

*srcRect , 
matri x , 
mode , 
mask , 
matte , 
*matteRect , 
f 1 ags  ) ; 


src 

Contains  a  pointer  to  a  Pi xMap  (IV-2332)  structure  containing  the  image  to 
draw.  Use  GetCompressedPixMapInfo  (1-397)  to  retrieve  information  about  this 
structure. 

srcRect 

Points  to  a  Rect  (IV-2399)  structure  that  defines  the  portion  of  the  image  to 
display.  This  rectangle  must  lie  within  the  boundary  rectangle  of  the 
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StdPix 


compressed  image  or  within  the  source  image.  If  this  parameter  is  set  to  N I L,  the 
entire  image  is  displayed. 

matri x 

Contains  a  pointer  toaMatrixRecord  (IV-2304)  structure  that  specifies  the 
mapping  of  the  source  rectangle  to  the  destination.  It  is  a  fixed-point,  3-by-3 
matrix. 

mode 

Specifies  the  transfer  mode  for  the  operation;  see  "Graphics  Transfer  Modes" 
(IV-2670).  Note  that  this  parameter  also  controls  the  accuracy  of  any 
decompression  operation  that  may  be  required  to  display  the  image.  If  bit  7 
(0x80)  of  the  mode  parameter  is  set  to  1,  the  StdPi x  function  sets  the 
decompression  accuracy  to  codecNormal  Qual  i  ty.  If  this  bit  is  set  to  0,  the 
function  sets  the  accuracy  to  codecHighQuality. 

mask 

Contains  a  handle  to  a  clipping  region  in  the  destination  coordinate  system.  If 
specified,  the  compressor  applies  this  mask  to  the  destination  image.  If  there  is 
no  mask,  this  parameter  is  set  to  NIL. 

matte 

Points  to  a  PixMap  (IV-2332)  structure  that  contains  a  blend  matte.  The  blend 
matte  causes  the  decompressed  image  to  be  blended  into  the  destination  pixel 
map.  The  matte  can  be  defined  at  any  supported  pixel  depth;  the  matte  depth 
need  not  correspond  to  the  source  or  destination  depths.  However,  the  matte 
must  be  in  the  coordinate  system  of  the  source  image.  If  there  is  no  matte,  this 
parameter  is  set  to  N I L 

matteRect 

Contains  a  pointer  to  a  Rect  (IV-2399)  structure  that  defines  a  portion  of  the 
blend  matte  to  apply.  This  parameter  is  set  to  N I L  if  there  is  no  matte  or  if  the 
entire  matte  is  to  be  used. 

flags 

Contains  control  flags  (see  below). 

flags  Constants 

cal  1  01  d  B i ts 

If  this  flag  is  set,  the  function  calls  QuickDraw's  bi tsProc  routine  with  the 
decompressed  image  data.  A  pointer  to  this  routine  is  located  in  the  bi  tsProc 
field  of  the  CQDProcs  (IV-2226)  structure.  If  the  bi  tsProc  routine  is  not 
customized,  it  is  not  called  unless  the  cal  1  StdBi  ts  flag  is  also  set. 
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StopMovie 


cal  1 StdBi ts 

If  this  flag  is  set,  the  cal  1 01  d B i  ts  flag  is  set,  and  the  CQDProcs  (IV-2226) 
structure's  bi  tsProc  field  is  set  to  the  Mac  OS  StdBi  ts  routine.  Then  the  StdBi  ts 
routine  is  called  with  the  decompressed  image  data. 
noDefaul tOpcodes 

If  this  flag  is  set  and  a  Picture  (IV-2331)  structure  is  open  for  writing,  the 
default  picture  opcodes  (for  displaying  a  warning  when  QuickTime  is  not 
installed)  are  not  added  to  the  output  structure.  This  can  be  useful  when  storing 
multiple  StdPi x  opcodes  in  a  single  structure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  the  StdPix  Function"  (V-2797) 


StopMovie 


Stops  the  playback  of  a  movie. 

void  StopMovie  ( 

Movi e  theMovi e  ) ; 


theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 


function  result  You  can  access  this  function's  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (1-494). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Controlling  Movie  Playback"  (V-2717) 

Related  Java  Methods 

qui ckti me. std .movi es .Movi e. stop ( ) 
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SubtractTime 


Subtracts  one  time  from  another. 

void  SubtractTime  ( 

TimeRecord  *dst, 

const  TimeRecord  *src  ); 


dst 

A  pointer  to  a  Ti  meRecord  (IV-2486)  structure.  This  time  structure  contains  one 
of  the  operands  for  the  subtraction.  This  function  returns  the  result  of  the 
subtraction  into  this  time  structure  as  a  duration. 

src 

A  pointer  to  a  Ti  meRecord  (IV-2486)  structure.  The  Movie  Toolbox  subtracts  this 
value  from  the  time  or  duration  specified  by  the  dst  parameter. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi  esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

If  the  two  times  are  relative  to  different  time  scales  or  time  bases,  this  function 
converts  the  times  as  appropriate  to  yield  reasonable  results.  However,  the  time 
bases  for  both  time  values  must  rely  on  the  same  time  source. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Times"  (V-2762) 

Related  Java  Methods 

qui ckti me . std . cl ocks .TimeRecord . SubtractTime! ) 


SysBeep 


Plays  the  system  alert  sound. 

void  SysBeep  ( 

short  duration  ); 
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TCFrameNumberToTimeCode 


durati on 

The  duration  in  sixtieths  of  a  second  (ticks)  of  the  resulting  sound.  This 
parameter  is  ignored  except  on  a  Macintosh  Plus,  Macintosh  SE,  or  Macintosh 
Classic  when  the  system  alert  sound  is  the  Simple  Beep.  The  recommended 
duration  is  30  ticks,  which  equals  one-half  second. 

function  result  You  can  access  error  returns  from  this  function  through 

GetMovi  esError  (1-492)  and  GetMovi esSti  ckyError  (1-494).  See  "Error 
Codes"  (IV-2663). 

Discussion 

This  function  causes  the  Sound  Manager  to  play  the  system  alert  sound  at  its  current 
volume.  If  necessary,  the  Sound  Manager  loads  into  memory  the  sound  resource 
containing  the  system  alert  sound  and  links  it  to  a  sound  channel.  The  Macintosh 
user  selects  a  system  alert  sound  in  the  Alert  Sounds  subpanel  of  the  Sound  control 
panel.  The  volume  of  the  sound  produced  depends  on  the  current  setting  of  the 
system  alert  sound  volume,  which  the  user  can  adjust  in  the  Alert  Sounds  subpanel 
of  the  Sound  control  panel.  The  system  alert  sound  volume  can  also  be  read  and  set 
by  calling  GetSysBeepVol  ume  (1-514)  and  SetSysBeepVol  ume  (III— 1647).  If  the  volume 
is  set  to  0  (silent)  and  the  system  alert  sound  is  enabled,  calling  SysBeep  causes  the 
menu  bar  to  blink  once. 

Special  Considerations 

Because  this  function  moves  memory,  you  should  not  call  it  at  interrupt  time 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Sound .  h 


TCFrameNumberT  oT  imeCode 


Converts  a  frame  number  into  its  corresponding  timecode  time  value. 

HandlerError  TCFrameNumberToTimeCode  ( 

MediaHandler  mh, 

long  frameNumber, 

TimeCodeDef  *tcdef, 
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TCGetCurrentTimeCode 


TimeCodeRecord  *tcrec  ); 


mh 

The  timecode  media  handler.  You  obtain  this  identifier  by  calling 
GetMedi  aHandl  er  (1-432). 

f rameNumber 

The  frame  number  that  is  to  be  converted, 
tcdef 

A  pointer  to  the  TimeCodeDef  (IV-2482)  structure  to  use  for  the  conversion, 
tcrec 

A  pointer  to  the  T i  meCodeRecord  (IV-2484)  structure  that  is  to  receive  the  time 
value. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Working  With  the  Timecode  Media  Handler"  (V-2870) 

Related  Java  Methods 

qui cktime . std . qt components . Ti meCoder . toT i meCode( ) 


TCGetCurrentTimeCode 


Retrieves  the  timecode  and  source  identification  information  for  the  current  movie 
time. 


HandlerError  TCGetCurrentTimeCode 


Medi aHandl er 
1  ong 

T i meCodeDef 
T i meCodeRecord 
UserData 


mh , 

*f rameNum, 
*tcdef , 
*tcrec , 
*srcRefH  ); 


( 


The  timecode  media  handler.  You  obtain  this  identifier  by  calling 
GetMedi  aHandl  er  (1-432). 
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TCGetDisplayOptions 


f rameNum 

A  pointer  to  a  field  that  is  to  receive  the  current  frame  number.  Set  this  field  to 
N I L  if  you  don't  want  to  retrieve  the  frame  number, 
tcdef 

A  pointer  to  a  Ti  meCodeDef  (IV-2482)  structure.  The  media  handler  returns  the 
movie's  timecode  definition  information.  Set  this  parameter  to  N I L  if  you  don't 
want  this  information. 

tcrec 

A  pointer  to  a  Ti  meCodeRecord  (IV-2484)  structure.  The  media  handler  returns 
the  current  time  value.  Set  this  parameter  to  N I L  if  you  don't  want  this 
information. 
srcRefH 

A  pointer  to  a  field  that  is  to  receive  a  handle  containing  the  source  information 
as  a  UserDataRecord  (IV-2496)  structure.  It  is  your  responsibility  to  dispose  of 
this  structure  when  you  are  done  with  it.  Set  this  field  to  N I L  if  you  don't  want 
this  information. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Working  With  the  Timecode  Media  Handler"  (V-2870) 

Related  Java  Methods 

qui ckti me . uti 1 . QTHandl e . f romT imeCoderCurrentt ) , 
qui ckti me . std . qt components .TimeCoder.getCurrentt ) 


TCGetDisplayOptions 


Retrieves  the  text  characteristics  that  apply  to  timecode  information  displayed  in  a 
movie. 

HandlerError  TCGetDisplayOptions  ( 

MediaHandler  mh, 

TCTextOpti onsPtr  textOptions  ); 


The  timecode  media  handler.  You  obtain  this  identifier  by  calling 
GetMedi  aHandl  er  (1-432). 
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TCGetSourceRef 


textOpti ons 

A  pointer  to  a  TCTextOpti  ons  (IV-2468)  structure.  This  structure  will  receive 
font  and  style  information. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Working  With  the  Timecode  Media  Handler"  (V-2870) 

Related  Java  Methods 

qui cktime . std . qt components . Ti meCoder . get Di  spl ay Opt i ons ( ) 


See  Also 

For  the  corresponding  set  function,  see  TCSetDi  spl  ayOpti  ons  (III— 1922). 


TCGetSourceRef 


Retrieves  the  source  information  from  the  timecode  media  sample  reference. 

HandlerError  TCGetSourceRef  ( 

MediaHandler  mh, 

T i meCodeDescri pti onHandl e  tcdH , 

UserData  *srefH  ); 


mh 

The  timecode  media  handler.  You  obtain  this  identifier  by  calling 
GetMedi  aHandl  er  (1-432). 

tcdH 

Specifies  a  handle  to  a  Ti  meCodeDescri  pti  on  (IV-2483)  structure  that  defines  the 
media  sample  reference  for  this  operation. 

srefH 

Specifies  a  pointer  to  a  handle  that  will  receive  the  source  information  as  a 
UserDataRecord  (IV-2496)  structure.  It  is  your  application's  responsibility  to 
dispose  of  this  structure  when  you  are  done  with  it. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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TCGetTimeCodeAtTime 


Programming  Info 

C  interface  file:  QuickTimeComponents.h 

Programming  summary:  "Working  With  the  Timecode  Media  Handler"  (V-2870) 

Related  Java  Methods 

qui ckti me . uti 1 .QTHandle.fromTimeCoderSourcet ) , 
qui ckti me . std . qt components .TimeCoder.getSourceReft ) 


See  Also 

For  the  corresponding  set  function,  see  TCSetSourceRef  (III— 1922). 


TCGetT  imeCode  AtT  ime 


Returns  a  track's  timecode  information  corresponding  to  a  specific  media  time. 


HandlerError  TCGetTimeCodeAtTime  ( 


Medi aHandl er 
TimeVal ue 
1  ong 

TimeCodeDef 

TimeCodeRecord 

UserData 


mh , 

mediaTime, 
*f rameNum , 
*tcdef , 
*tcdata , 
*srcRefH  ); 


mh 

The  timecode  media  handler.  You  obtain  this  identifier  by  calling 
GetMedi  aHandl  er  (1-432). 
medi aT i me 

A  time  value  for  which  you  want  to  retrieve  timecode  information.  This  time 
value  is  expressed  in  the  media's  time  coordinate  system. 

f rameNum 

A  pointer  to  a  field  that  is  to  receive  the  current  frame  number.  Set  this  field  to 
N I L  if  you  don't  want  to  retrieve  the  frame  number. 

tcdef 

A  pointer  to  a  Ti  meCodeDef  (IV-2482)  structure.  The  media  handler  returns  the 
movie's  timecode  definition  information.  Set  this  parameter  to  N I L  if  you  don't 
want  this  information, 
tcdata 

A  pointer  to  a  Ti  meCodeRecord  (IV-2484)  structure.  The  media  handler  returns 
the  current  time  value.  Set  this  parameter  to  N I L  if  you  don't  want  this 
information. 
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TCGetTimeCodeFlags 


srcRefH 

A  pointer  to  a  field  that  is  to  receive  a  handle  containing  the  source  information 
as  a  UserData Record  (IV-2496)  structure.  It  is  your  responsibility  to  dispose  of 
this  structure  when  you  are  done  with  it.  Set  this  field  to  N I L  if  you  don't  want 
this  information. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Working  With  the  Timecode  Media  Handler"  (V-2870) 

Related  Java  Methods 

qui cktime . uti 1 . QTHandl e . f romTi meCoderT ime( ) , 
qui cktime . std . qt components .Ti meCoder . getAtT ime( ) 


TCGetTimeCodeFlags 


Retrieves  the  timecode  control  flags. 

HandlerError  TCGetTimeCodeFlags  ( 
MediaHandler  mh, 

long  *flags  ); 


mh 

The  timecode  media  handler.  You  obtain  this  identifier  by  calling 
GetMedi  aHandl  er  (1-432). 

fl  ags 

A  pointer  to  a  field  that  is  to  receive  a  control  flag  (see  below). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  Constant 

tcdfShowTimeCode 

Controls  the  display  of  timecode  information.  If  this  flag  is  set  to  1,  the  timecode 
information  is  displayed  when  the  movie  is  played.  The  timecode  track  must  be 
enabled  in  order  for  the  timecode  information  to  be  displayed. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Functions  R-Z 


III-1921 


TCSetDisplayOptions 


Programming  Info 

C  interface  file:  QuickTimeComponents.h 

Programming  summary:  "Working  With  the  Timecode  Media  Handler"  (V-2870) 

Related  Java  Methods 

qui ckti me . std . qt components .Time Coder. getFlagst ) 


See  Also 

For  the  corresponding  set  function,  see  TCSetT i  meCodeFl  ags  (III— 1923). 


TCSetDisplayOptions 


Sets  the  text  characteristics  that  apply  to  timecode  information  displayed  in  a 
movie. 

H a n d 1 erError  TCSetDisplayOptions  ( 

Medi a  H  a  n  d 1 er  mh, 

TCTextOpti onsPtr  textOptions  ); 


mh 

The  timecode  media  handler.  You  obtain  this  identifier  by  calling 
GetMedi  aHandl  er  (1-432). 

textOpti ons 

A  pointer  to  a  TCTextOpti  ons  (IV-2468)  structure.  This  structure  contains  font 
and  style  information. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Working  With  the  Timecode  Media  Handler"  (V-2870) 

Related  Java  Methods 

qui ckti me . std . qt components . Time Coder. setDispl ay Options! ) 


See  Also 

For  the  corresponding  get  function,  see  TCGetDi  s pi  ayOpti  ons  (III— 1918). 


TCSetSourceRef 


Changes  the  source  information  in  the  timecode  media  sample  reference. 


III-1922 


Inside  QuickTime:  Functions  R-Z 


TCSetTimeCodeFlags 


HandlerError  TCSetSourceRef  ( 
Medi aHandl er 

T  i  meCodeDescri pti onHandl e 
UserData 


mh , 
tcdH , 
srefH  ); 


mh 

The  timecode  media  handler.  You  obtain  this  identifier  by  calling 
GetMedi  aHandl  er  (1-432). 

tcdH 

Specifies  a  handle  containing  the  timecode  media  sample  reference  that  is  to  be 
updated. 
srefH 

Specifies  a  handle  to  the  source  information  to  be  placed  in  the  sample  reference 
as  a  UserData  Record  (IV-2496)  structure.  It  is  your  application's  responsibility 
to  dispose  of  this  structure  when  you  are  done  with  it. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Working  With  the  Timecode  Media  Handler"  (V-2870) 

Related  Java  Methods 

qui cktime . std . qt components .Ti meCoder . set Source Ref ( ) 


See  Also 

For  the  corresponding  get  function,  see  TCGetSourceRef  (III— 1919). 


TCSetTimeCodeFlags 


Changes  the  flag  that  affects  how  the  toolbox  handles  timecode  information. 

HandlerError  TCSetTimeCodeFlags  ( 

MediaHandler  mh, 

long  flags, 

long  flagsMask  ); 


The  timecode  media  handler.  You  obtain  this  identifier  by  calling 
GetMedi  aHandl  er  (1-432). 


Inside  QuickTime:  Functions  R-Z 


III-1923 


TCTimeCodeToFrameNumber 


fl  ags 

The  new  flag  value, 
f  1  agsMask 

Specifies  which  of  the  flag  values  are  to  change.  The  media  handler  modifies 
only  those  flag  values  that  correspond  to  bits  that  are  set  to  1  in  this  parameter. 
Use  the  flag  values  from  the  flags  parameter.  To  turn  off  timecode  display,  set 
the  tcdfShowT i meCode  flag  to  1  in  the  f  1  agsMask  parameter  and  to  0  in  the  f  1  ags 
parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

flags  and  flagsMask  Constant 

tcdfShowT i meCode 

Controls  the  display  of  timecode  information.  If  this  flag  is  set  to  1,  the  timecode 
information  is  displayed  when  the  movie  is  played.  The  timecode  track  must  be 
enabled  in  order  for  the  timecode  information  to  be  displayed. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Working  With  the  Timecode  Media  Handler"  (V-2870) 

Related  Java  Methods 

qui ckti me . std . qt components . Time Coder. setFlagst ) 


See  Also 

For  the  corresponding  get  function,  see  TCGetTimeCodeFl  ags  (III— 1921). 


TCT  imeCodeT  oFrameNumber 


Converts  a  timecode  time  value  into  its  corresponding  frame  number. 


HandlerError  TCTimeCodeToFrameNumber  ( 
MediaHandler  mh, 

TimeCodeDef  *tcdef, 

TimeCodeRecord  *tcrec, 

1 ong  *f rameNumber  ) ; 


The  timecode  media  handler.  You  obtain  this  identifier  by  calling 
GetMedi  aHandl  er  (1-432). 


III-1924 


Inside  QuickTime:  Functions  R-Z 


T  CTimeCodeToString 


tcdef 

A  pointer  to  the  TimeCodeDef  (IV-2482)  structure  to  use  for  the  conversion, 
tcrec 

A  pointer  to  the  T i  meCodeRecord  (IV-2484)  structure  containing  the  time  value 
to  convert. 

f rameNumber 

A  pointer  to  a  field  that  is  to  receive  the  frame  number  that  corresponds  to  the 
time  value  in  the  tcrec  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Working  With  the  Timecode  Media  Handler"  (V-2870) 

Related  Java  Methods 

qui cktime . std . qt components . Ti meCoder . toFrameNumber( ) 


TCTimeCodeToString 


Converts  a  time  value  into  a  text  string  (HH:MM:SS:FF). 

HandlerError  TCTimeCodeToString  ( 

MediaHandler  mh, 

TimeCodeDef  *tcdef, 

TimeCodeRecord  *tcrec, 

StringPtr  tcStr  ); 


mh 

The  timecode  media  handler.  You  obtain  this  identifier  by  calling 
GetMedi  aHandl  er  (1-432). 

tcdef 

A  pointer  to  the  TimeCodeDef  (IV-2482)  structure  to  use  for  the  conversion, 
tcrec 

A  pointer  to  the  T i  meCodeRecord  (IV-2484)  structure  to  use  for  the  conversion. 
tcStr 

A  pointer  to  a  text  string  that  is  to  receive  the  converted  time  value. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Inside  QuickTime:  Functions  R-Z 


III-1925 


TerminateQHdr 


Discussion 

If  the  timecode  uses  the  dropframe  technique,  the  separators  are  semicolons  (;) 
rather  than  colons  (:). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Working  With  the  Timecode  Media  Handler"  (V-2870) 

Related  Java  Methods 

qui ckti me . std . qt components . Time Coder. timeCodeToStringt ) 


TerminateQHdr 

Terminates  a  Windows  QHdr  data  structure. 

void  TerminateQHdr  ( 

QHdr  *qhdr  ); 


qhdr 

qhdr 

Discussion 

The  Termi  nateQHdr  function  deallocates  the  data  structures  created  by 
Initial  i  zeQHdr  (11-756). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML.h 


TerminateQTML 

Terminates  the  QuickTime  Media  Layer, 
void  TerminateQTML  (  void  ); 


Discussion 

Use  Termi  nateQTML  to  terminate  a  QTML  session  after  calling  Exi  tMovi  es  (1-340). 
You  should  not  make  this  call  from  a  QuickTime  component,  such  as  an  image 
decompressor;  it  is  provided  only  for  host  applications. 


III-1926 


Inside  QuickTime:  Functions  R-Z 


TerminateQTS 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML .  h 

Related  Java  Methods 

qui cktime . QTSessi on . termi nate( ) 


TerminateQTS 

Terminates  the  QuickTime  Streaming  toolbox. 

OSErr  TerminateQTS  (  void  ); 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


Terminate  QT  VR 


Terminates  QuickTime  VR  when  you  have  finished  using  its  functions. 

OSErr  Termi nateQTVR  (  void  ); 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  must  use  the  Termi  nateQTVR  function  when  you  have  finished  using  the 
functions  of  QuickTime  VR.  Multiple  calls  to  Ini  ti  al  i  zeQTVR  (11-758)  and 
Termi  nateQTVR  can  be  either  nested  or  sequential,  but  there  must  be  at  least  one  call 
to  Termi  nateQTVR  corresponding  to  each  call  to  Ini  ti  al  i  zeQTVR. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

Programming  summary:  "Initializing  and  Terminating  QuickTime  VR"  (V-2904) 


Inside  QuickTime:  Functions  R-Z 


III-1927 


TextExportGetDisplayData 


Related  Java  Methods 

qui  ckti  me .  QTSessi  on  .  term'  nateVR( ) 


T  extExportGetDisplayData 


Retrieves  text  display  information  for  the  current  sample  in  the  specified  text  export 
component. 

ComponentResult  TextExportGetDisplayData  ( 

TextExportComponent  ci  , 

TextDispl ayData  *textDisplay  ); 


ci 

Specifies  the  text  export  component  for  this  operation.  Applications  can  obtain 
this  reference  from  OpenComponent  (11-1130)  or  OpenDef aid  tComponent  (11-1131). 
textDi spl ay 

Contains  a  pointer  to  a  TextDi  spl  ayData  (IV-2476)  structure.  On  return,  this 
structure  contains  the  display  settings  of  the  current  text  sample. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  call  this  function  to  retrieve  the  text  display  data  structure  for  a  text  sample. 
The  text  display  data  structure  contains  the  formatting  information  for  the  text 
sample.  When  the  text  export  component  exports  a  text  sample,  it  uses  the 
information  in  this  structure  to  generate  the  appropriate  text  descriptors  for  the 
sample.  Likewise,  when  the  text  import  component  imports  a  text  sample,  it  sets  the 
appropriate  fields  in  the  text  display  data  structure  based  on  the  sample's  text 
descriptors. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 
Programming  summary:  "Exporting  Text"  (V-2860) 


T  extExportGetSettings 

Retrieves  the  value  of  the  text  export  option  for  the  specified  text  export  component. 
ComponentResult  TextExportGetSettings  ( 


III-1928 


Inside  QuickTime:  Functions  R-Z 


TextExportGetTimeFraction 


TextExportComponent  ci  , 

long  *setting  ); 


ci 

Specifies  the  text  export  component  for  this  operation.  Applications  can  obtain 
this  reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
setti ng 

Contains  a  pointer  to  a  32-bit  integer.  On  return,  this  integer  contains  a  constant 
(see  below)  that  represents  the  current  value  of  the  text  export  option. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

setting  Constants 

kMovi e Export Text Only 

The  text  export  component  exports  text  without  time  descriptors  or  time 
stamps. 

kMovi eExportAbsol uteTi  me 

The  text  export  component  exports  text  along  with  its  text  descriptors  and  time 
stamps.  For  each  sample,  calculate  the  time  stamp  relative  to  the  start  of  the 
movie. 

kMovi eExportRel ati veTime 

The  text  export  component  exports  text  along  with  its  text  descriptors  and  time 
stamps.  For  each  sample,  calculate  the  time  stamp  relative  to  the  previous  time 
stamp. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui ckTi  meComponents  .  h 
Programming  summary:  "Exporting  Text"  (V-2860) 

See  Also 

For  the  corresponding  set  function,  see  TextExportSetSetti  ngs  (III— 1930). 


T  extExportGetT  imeFraction 


Retrieves  the  time  scale  the  specified  text  export  component  uses  to  calculate  time 
stamps. 

ComponentResul t  TextExportGetTimeFraction  ( 

TextExportComponent  ci  , 

long  *movieTimeFraction  ); 


Inside  QuickTime:  Functions  R-Z 


III-1929 


TextExportSetSettings 


ci 

Specifies  the  text  export  component  for  this  operation.  Applications  can  obtain 
this  reference  from  OpenComponent  (11-1130)  or  OpenDef aul  tComponent  (11-1131). 
movieTimeFraction 

Contains  a  pointer  to  a  32-bit  integer.  On  return,  this  integer  contains  the  time 
scale  used  in  the  fractional  part  of  time  stamps. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

You  call  this  function  to  retrieve  the  time  scale  used  by  the  text  export  component 
to  calculate  the  fractional  part  of  time  stamps.  You  set  a  text  component's  time  scale 
by  specifying  it  in  the  Text  Export  Settings  dialog  box  or  by  calling 
Text  Expo  rtSetT imeFracti on  (III — 1931). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 
Programming  summary:  "Exporting  Text"  (V-2860) 

See  Also 

For  the  corresponding  set  function,  see  Text  Expo  rtSetT  imeFracti  on  (III— 1931). 


T  extExportSetSettings 


Sets  the  value  of  the  text  export  option  for  the  specified  text  export  component. 

ComponentResul t  TextExportSetSettings  ( 

TextExportComponent  ci  , 

1 ong  setti ng  ) ; 


ci 

Specifies  the  text  export  component  for  this  operation.  Applications  can  obtain 
this  reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 
setti ng 

A  constant  (see  below)  that  specifies  the  new  value  of  the  text  export  option. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


III-1930 


Inside  QuickTime:  Functions  R-Z 


TextExportSetTimeFraction 


setting  Constants 

kMovi eExportTextOnly 

The  text  export  component  exports  text  without  time  descriptors  or  time 
stamps. 

kMovi eExportAbsol uteTi  me 

The  text  export  component  exports  text  along  with  its  text  descriptors  and  time 
stamps.  For  each  sample,  calculate  the  time  stamp  relative  to  the  start  of  the 
movie. 

kMovi eExportRel ati veTi  me 

The  text  export  component  exports  text  along  with  its  text  descriptors  and  time 
stamps.  For  each  sample,  calculate  the  time  stamp  relative  to  the  previous  time 
stamp. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 
Programming  summary:  "Exporting  Text"  (V-2860) 

See  Also 

For  the  corresponding  get  function,  see  TextExportGetSettings  (III— 1928). 


T  extExportSetT  imeFraction 


Sets  the  time  scale  the  specified  text  export  component  uses  to  calculate  time 
stamps. 

ComponentResul t  TextExportSetTimeFraction  ( 

TextExportComponent  ci  , 

long  movieTimeFraction  ); 


ci 

Specifies  the  text  export  component  for  this  operation.  Applications  can  obtain 
this  reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

movi eT i meFracti  on 

Specifies  the  time  scale  used  in  the  fractional  part  of  time  stamps.  The  value 
should  be  between  1  and  10000,  inclusive. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Inside  QuickTime:  Functions  R-Z 


III-1931 


TextMediaAddHiliteSample 


Discussion 

You  call  this  function  to  set  the  time  scale  used  by  the  text  export  component  to 
calculate  the  fractional  part  of  time  stamps.  You  can  also  set  a  text  component's  time 
scale  by  specifying  it  in  the  text  export  settings  dialog  box.  You  can  retrieve  a  text 
component's  time  scale  by  calling  Text  Expo  rtGetT  i  me  Fraction  (III— 1929). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 
Programming  summary:  "Exporting  Text"  (V-2860) 

See  Also 

For  the  corresponding  get  function,  see  Text  Expo rtGetTi  meFracti  on  (ill-1929). 


TextMediaAddHiliteSample 


Provides  dynamic  highlighting  of  text. 


Component Res ul t  TextMedi aAddHiliteSample 


Medi aHandl er 
short 
short 
RGBCol or 
TimeVal ue 
TimeVal ue 


mh , 

hi  1 i teStart , 
hi  1 i teEnd , 

*rgbHi 1 i teCol or , 
durati on , 

*sampl eT ime  ) ; 


( 


mh 

The  media  handler  for  the  text  media  obtained  by  GetMedi  aHandl  er  (1-432). 
hi  1 i teStart 

Indicates  the  beginning  of  the  text  to  be  highlighted, 
hi  1 i teEnd 

Indicates  the  ending  of  the  text  to  be  highlighted.  If  the  value  of  the  hiliteStart 
parameter  equals  that  of  the  hi  1  i  teEnd  parameter,  then  no  text  is  highlighted 
(that  is,  highlighting  is  turned  off  for  the  duration  of  the  specified  sample). 
rgbHi 1 i teCol or 

A  pointer  to  the  RGBCol  or  (IV-2403)  structure  that  defines  the  color  for 
highlighting.  If  this  parameter  is  not  N I L,  then  the  specified  color  is  used  when 
highlighting  the  text  indicated  by  the  hi  1  i  teStart  and  hi  1  i  teEnd  parameters. 
Otherwise,  the  default  system  highlight  color  is  used. 


III-1932 


Inside  QuickTime:  Functions  R-Z 


TextMediaAddTESample 


durati on 

Specifies  how  long  the  text  sample  should  last.  This  duration  is  expressed  in  the 
media's  time  base, 
sampl eTime 

A  pointer  to  a  time  value.  The  actual  media  time  at  which  the  sample  was 
added  is  returned  here. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movl  es  .  h 

Programming  summary:  "Text  Media  Handler  Functions"  (V-2756) 


T  extMedia  AddTESample 


Specifies  a  TextEdit  handle  to  be  added  to  a  specified  media. 
ComponentResul t  TextMediaAddTESample  ( 


Medi aHandl er 

mh , 

TEHandl e 

hTE, 

RGBCol or 

*backCol or , 

short 

textJusti fi cati on 

Rect 

*textBox, 

1  ong 

di  spl  ayFl  ags  , 

TimeVal ue 

scrol 1  Del  ay , 

short 

hi  1 i teSta rt , 

short 

hi  1 i teEnd  , 

RGBCol or 

*rgbHi 1 i teCol or , 

TimeVal ue 

durati on , 

TimeVal ue 

*sampl eTime  ); 

mh 

The  media  handler  for  the  text  media  obtained  by  GetMedi  aHandl  er  (1-432). 
hTE 

A  handle  to  a  TERec  (IV-2469)  structure. 
backCol or 

A  pointer  to  an  RGBCol  or  (IV-2403)  structure  specifying  the  text  background 
color.  Passing  N I L  for  this  parameter  in  defaults  to  white. 


Inside  QuickTime:  Functions  R-Z 


III-1933 


TextMediaAddTESample 


textJusti f i cati  on 

Indicates  the  justification  of  the  text  (see  below). 
textBox 

A  pointer  to  a  Rect  (IV-2399)  structure  that  defines  the  box  within  which  the 
text  is  to  be  displayed.  The  box  is  relative  to  the  track  bounds. 

di  spl ay  FI ags 

Contains  the  text  display  flags  (see  below), 
scrol 1  Del  ay 

Indicates  the  delay  in  scrolling  associated  with  the  setting  of  the  d  f  S  c  r  o  1 1 1  n  and 
dfScrollOut  display  flags.  If  the  value  of  the  scrollDelay  parameter  is  greater 
than  0  and  the  df  Scrol  1  In  flag  is  set,  the  text  pauses  when  it  has  scrolled  all  the 
way  in  for  the  amount  of  time  specified  by  scrol  1  Del  ay.  If  the  dfScrol  1  Out  flag 
is  set,  the  pause  occurs  first  before  the  text  scrolls  out.  If  both  these  flags  are  set, 
the  pause  occurs  at  the  midpoint  between  scrolling  in  and  scrolling  out. 
hi  1 i teStart 

The  beginning  of  the  text  to  be  highlighted, 
hi  1 i teEnd 

The  end  of  the  text  to  be  highlighted.  If  the  hi  1  i  teEnd  parameter  is  greater  than 
the  hi  1  i  teStart  parameter,  then  the  text  is  highlighted  from  the  selection 
specified  by  hi  1  i  teStart  to  hi  1  i  teEnd.  To  specify  additional  highlighting,  you 
can  use  TextMedi  aAddHi  1  i  teSampl  e  (III— 1932). 
rgbHi 1 i teCol or 

Contains  a  pointer  to  an  RGBCol  or  (IV-2403)  structure  that  defines  the  color  for 
highlighting.  If  this  parameter  is  not  N I L,  then  the  specified  color  is  used  when 
highlighting  the  text  indicated  by  the  hi  1  i  teStart  and  hi  1  i  teEnd  parameters. 
Otherwise,  the  default  system  highlight  color  is  used, 
durati on 

A  time  value  that  specifies  how  long  the  text  sample  should  last.  This  duration 
is  expressed  in  the  media's  time  base. 

sampl eT i me 

Contains  a  pointer  to  a  time  value.  The  actual  media  time  at  which  the  sample 
was  added  is  returned  here. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 
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TextMediaAddTESample 


textJustification  Constants 

teCenter 

Text  is  centered. 
teFl  ushRi  ght 

Text  is  lined  up  on  the  right. 
teFl  ushLeft 

Text  is  lined  up  on  the  left. 
teFl ushDefaul t 

Text  is  lined  up  left  or  right,  depending  on  the  script  being  used. 

displayFlags  Constants 

df DontDi spl ay 

Does  not  display  the  specified  sample, 
df DontAutoScal e 

Does  not  scale  the  text  if  the  track  bounds  increase. 
dfCl i pToTextBox 

Clips  to  the  text  box  only.  This  is  useful  if  the  text  overlays  the  video. 
dfShri nkTextBoxToFi t 

Recalculates  size  of  the  textBox  parameter  to  just  fit  the  given  text  and  stores 
this  rectangle  with  the  text  data. 

dfScrol 1  In 

Scrolls  the  text  in  until  the  last  of  the  text  is  in  view, 
df Scrol 1  Out 

Scrolls  text  out  until  the  last  of  the  text  is  out  of  view.  If  both  df  Scrol  1 1  n  and 
df  Scrol  1  Out  are  set,  the  text  is  scrolled  in,  then  out. 

df Hori zScrol 1 

Scrolls  a  single  line  of  text  horizontally.  If  the  dfHorizScroll  flag  is  not  set,  then 
the  scrolling  is  vertical. 

df ReverseScrol 1 

If  set,  scrolls  vertically  down,  rather  than  up.  If  not  set,  horizontal  scrolling 
proceeds  toward  the  left  rather  than  toward  the  right. 
dfConti nuousScrol 1 

If  this  flag  is  set,  the  text  media  handler  lets  new  samples  cause  previous 
samples  to  scroll  out.  You  must  also  set  dfScrollInor  df  Scrol  1  Out,  or  both,  for 
this  to  take  effect. 

df  FI  owHori  z 

If  this  flag  is  set,  the  text  media  handler  lets  horizontally  scrolled  text  flow 
within  the  text  box  instead  of  extending  to  the  right. 
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dfContinuous Karaoke 

If  this  flag  is  set,  the  text  media  handler  ignores  the  starting  offset  when 
highlighting  text.  Instead,  it  highlights  text  from  the  beginning  of  the  text 
sample  to  the  ending  offset, 
df DropShadow 

If  this  flag  is  set,  the  text  media  handler  displays  text  with  a  drop  shadow.  If  you 
use  Text  Med  i  aSetTextSampl  eData  (III— 1950),  the  position  and  translucency  of  the 
drop  shadow  is  under  your  application's  control. 

df Anti A1 i as 

If  this  flag  is  set,  the  text  media  handler  displays  text  with  anti-aliasing.  Note 
that  although  anti-aliased  text  looks  smoother,  anti-aliasing  can  slow  down 
performance. 
dfKeyedText 

If  this  flag  is  set,  the  text  media  handler  renders  text  over  the  background 
without  drawing  the  background  color.  This  technique  is  also  known  as 
"masked  text." 
df InverseHi 1 i te 

If  this  flag  is  set,  the  text  media  handler  highlights  text  using  inverse  video 
instead  of  the  highlight  color. 

dfTextCol orHi 1  i  te 

If  this  flag  is  set,  the  text  media  handler  highlights  text  by  changing  the  color  of 
the  text. 

Special  Considerations 

Be  sure  to  turn  on  the  dfDropShadow  display  flag  after  you  call  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Text  Media  Handler  Functions"  (V-2756) 


T  extMediaAddT  extSample 


Adds  a  single  block  of  styled  text  to  an  existing  media. 

ComponentResul t  TextMediaAddTextSample  ( 
MediaHandler  mh, 

Ptr  text, 

unsigned  long  size, 
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short 

f ontNumber , 

short 

f ontSi ze , 

Styl  e 

textFace , 

RGBCol or 

*textCol or , 

RGBCol or 

*backCol or , 

short 

textJusti f i cati on 

Rect 

*textBox, 

1  ong 

di  spl  ayFl  ags  , 

TimeVal ue 

scrol 1  Del  ay , 

short 

hil iteStart, 

short 

hi  1 i teEnd , 

RGBCol or 

*rgbHi 1 i teCol or , 

TimeVal ue 

durati on , 

TimeVal ue 

*sampleTime  ); 

mh 

The  media  handler  for  the  text  media  obtained  byGetMediaHandler  (1-432). 

text 

A  pointer  to  a  block  of  text. 

si  ze 

Indicates  the  size  of  the  text  block,  in  bytes, 
f ontNumber 

The  number  for  the  font  in  which  to  display  the  text, 
f ontSi ze 

Indicates  the  size  of  the  font. 
textFace 

Indicates  the  typeface  or  style  of  the  text  (that  is,  bold,  italic,  and  so  on). 
textCol or 

A  pointer  to  an  RGBCol  or  (IV-2403)  structure  specifying  the  color  of  the  text. 
Passing  N I L  for  this  parameter  in  defaults  to  black. 
backCol or 

A  pointer  to  an  RGBCol  or  (IV-2403)  structure  specifying  the  text  background 
color.  Passing  N I L  for  this  parameter  in  defaults  to  white. 
textJusti f i cati on 

Indicates  the  justification  of  the  text  (see  below). 
textBox 

A  pointer  to  a  Rect  (IV-2399)  structure  that  defines  the  box  within  which  the 
text  is  to  be  displayed.  The  box  is  relative  to  the  track  bounds, 
di  spl  ayFl  ags 

Contains  the  text  display  flags  (see  below). 
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scrol 1  Del  ay 

Indicates  the  delay  in  scrolling  associated  with  the  setting  of  the  d  f  S  c  r  o  1 1 1  n  and 
dfScrollOut  display  flags.  If  the  value  of  the  scrollDelay  parameter  is  greater 
than  0  and  the  df  Scrol  1  In  flag  is  set,  the  text  pauses  when  it  has  scrolled  all  the 
way  in  for  the  amount  of  time  specified  by  scrol  1  Del  ay.  If  the  dfScrol  1  Out  flag 
is  set,  the  pause  occurs  first  before  the  text  scrolls  out.  If  both  these  flags  are  set, 
the  pause  occurs  at  the  midpoint  between  scrolling  in  and  scrolling  out. 
hi  1 i teStart 

The  beginning  of  the  text  to  be  highlighted, 
hi  1 i teEnd 

The  end  of  the  text  to  be  highlighted.  If  the  hi  1  i  teEnd  parameter  is  greater  than 
the  hi  1  i  teStart  parameter,  then  the  text  is  highlighted  from  the  selection 
specified  by  hi  1  i  teStart  to  hi  1  i  teEnd.  To  specify  additional  highlighting,  you 
can  use  TextMedi  aAddHi  1  i  teSampl  e  (III— 1932). 
rgbHi 1 i teCol or 

Contains  a  pointer  to  an  RGBCol  or  (IV-2403)  structure  that  defines  the  color  for 
highlighting.  If  this  parameter  is  not  N I L,  then  the  specified  color  is  used  when 
highlighting  the  text  indicated  by  the  hi  1  i  teStart  and  hi  1  i  teEnd  parameters. 
Otherwise,  the  default  system  highlight  color  is  used, 
durati on 

A  time  value  that  specifies  how  long  the  text  sample  should  last.  This  duration 
is  expressed  in  the  media's  time  base. 

sampl eT i me 

Contains  a  pointer  to  a  time  value.  The  actual  media  time  at  which  the  sample 
was  added  is  returned  here. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

textJustification  Constants 

teCenter 

Text  is  centered. 
teFl  ushRi  ght 

Text  is  lined  up  on  the  right. 
teFl ushLeft 

Text  is  lined  up  on  the  left. 
teFl  ushDefaul  t 

Text  is  lined  up  left  or  right,  depending  on  the  script  being  used. 
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displayFlags  Constants 

df DontDi spl ay 

Does  not  display  the  specified  sample, 
df DontAutoScal e 

Does  not  scale  the  text  if  the  track  bounds  increase. 
dfCl i pToTextBox 

Clips  to  the  text  box  only.  This  is  useful  if  the  text  overlays  the  video. 
dfShri nkTextBoxToFi t 

Recalculates  size  of  the  textBox  parameter  to  just  fit  the  given  text  and  stores 
this  rectangle  with  the  text  data. 

dfScrol 1  In 

Scrolls  the  text  in  until  the  last  of  the  text  is  in  view, 
df Scrol 1  Out 

Scrolls  text  out  until  the  last  of  the  text  is  out  of  view.  If  both  df  Scrol  1 1  n  and 
df  Scrol  1  Out  are  set,  the  text  is  scrolled  in,  then  out. 
df Hori zScrol 1 

Scrolls  a  single  line  of  text  horizontally.  If  the  dfHorizScroll  flag  is  not  set,  then 
the  scrolling  is  vertical. 

df ReverseScrol 1 

If  set,  scrolls  vertically  down,  rather  than  up.  If  not  set,  horizontal  scrolling 
proceeds  toward  the  left  rather  than  toward  the  right. 
dfContinuousScroll 

If  this  flag  is  set,  the  text  media  handler  lets  new  samples  cause  previous 
samples  to  scroll  out.  You  must  also  set  dfScrollInor  df  Scrol  1  Out,  or  both,  for 
this  to  take  effect, 
df  FI  owHori  z 

If  this  flag  is  set,  the  text  media  handler  lets  horizontally  scrolled  text  flow 
within  the  text  box  instead  of  extending  to  the  right. 

dfContinuous Karaoke 

If  this  flag  is  set,  the  text  media  handler  ignores  the  starting  offset  when 
highlighting  text.  Instead,  it  highlights  text  from  the  beginning  of  the  text 
sample  to  the  ending  offset, 
df DropShadow 

If  this  flag  is  set,  the  text  media  handler  displays  text  with  a  drop  shadow.  If  you 
use  TextMedi  aSetTextSampl  eData  (III— 1950),  the  position  and  translucency  of  the 
drop  shadow  is  under  your  application's  control. 
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df Anti A1 i as 

If  this  flag  is  set,  the  text  media  handler  displays  text  with  anti-aliasing.  Note 
that  although  anti-aliased  text  looks  smoother,  anti-aliasing  can  slow  down 
performance. 
dfKeyedText 

If  this  flag  is  set,  the  text  media  handler  renders  text  over  the  background 
without  drawing  the  background  color.  This  technique  is  also  known  as 
"masked  text." 

df InverseHi 1 i te 

If  this  flag  is  set,  the  text  media  handler  highlights  text  using  inverse  video 
instead  of  the  highlight  color. 
dfTextCol orHi 1  i  te 

If  this  flag  is  set,  the  text  media  handler  highlights  text  by  changing  the  color  of 
the  text. 

Special  Considerations 

Be  sure  to  turn  on  the  dfDropShadow  display  flag  after  you  call  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi es .  h 

Programming  summary:  "Text  Media  Handler  Functions"  (V-2756) 

Related  Java  Methods 

qui ckti me . std .movi es .medi a .TextMedi aHandl er . addTextSampl e( ) 


T  extMediaDrawRaw 


Undocumented 

ComponentResul t  TextMediaDrawRaw  ( 


MediaHandler  mh, 

GWorldPtr  gw, 

GDHandle  gd, 

void  *data, 

long  dataSize, 

TextDescriptionHandl e  tdh  ); 


mh 

The  text  media  handler  obtained  by  GetMedi  aHandl  er  (1-432). 
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gw 

A  pointer  to  a  CGraf  Port  (IV-2168)  structure  that  defines  a  graphics  world, 
gd 

A  handle  to  a  graphics  device. 

data 

A  pointer  to  the  source  data. 
dataSi ze 

The  size  of  the  source  data. 

tdh 

A  handle  to  a  TextDescri  pti  on  (IV-2474)  structure. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


T  extMediaFindNextT  ext 


Searches  for  text  with  a  specified  media  handler  starting  at  a  given  time. 


Component  Res  ill  t  TextMedi  a  F  i  nd  Next  Text 


Medi aHandl er 
Ptr 
1  ong 
short 
TimeVal  lie 
TimeVal  lie 
TimeVal  lie 
1  ong 


mh , 
text , 
size, 

f  i ndFl  ags  , 
startTime, 
*foundTime, 

*f oundDurati on , 
*offset  ); 


( 


mh 

The  media  handler  for  the  text  media  obtained  by  GetMedi  aHandl  er  (1-432). 

text 

Points  to  the  text  to  be  found. 


si  ze 

The  length  of  the  text  to  be  found. 
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f  i  nd FI  ags 

Flags  (see  below)  that  determine  the  conditions  of  the  search. 
startTime 

Indicates  the  time  (expressed  in  the  movie  time  scale)  at  which  to  begin  the 
search. 

foundTime 

A  pointer  to  the  movie  time  at  which  the  text  sample  is  found  if  the  search  is 
successful.  Otherwise,  it  returns  -1. 
foundDurati on 

A  pointer  to  the  duration  of  the  sample  (in  the  movie  time  scale)  that  is  found 
if  the  search  is  successful, 
offset 

A  pointer  to  the  offset  of  the  found  text  from  the  beginning  of  the  text  portion 
of  the  sample. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

findFlags  Constants 

fi ndTextEdgeOK 

Okay  to  find  text  at  exactly  the  specified  sample  time, 
fi ndTextCaseSensi ti ve 
Case-sensitive  search, 
fi ndTextReverseSearch 

Search  from  start  time  backwards, 
fi ndTextWrapAround 

Wrap  search  when  beginning  or  end  of  movie  is  hit. 
fi ndTextUseOffset 

Begin  search  at  the  given  character  offset  into  sample  rather  than  edge. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Text  Media  Handler  Functions"  (V-2756) 

Related  Java  Methods 

quicktime.std.movies.media.TextMediaHandler.findNextTextt ) 
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T  extMediaGetT  extProperty 


Sets  properties  of  a  text  media. 


Component Res ul t  TextMedi aGetText Property 
Medi aHandl er  mh, 

TimeValue  atMediaTime, 

long  propertyType , 

void  *data, 

long  dataSize  ); 


( 


mh 

The  text  media  handler  obtained  by  GetMedi  aHandl  er  (1-432). 
atMedi aTi me 

The  media  time  of  the  text. 
propertyType 

A  constant  (see  below)  that  identifies  the  text  property  to  be  set. 

data 

A  pointer  to  text  data. 
dataSi ze 

The  size  of  the  data. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

propertyType  Constants 

kTextTextHandl e 

A  handle  to  the  text. 
kTextTextPtr 

A  pointer  to  the  text. 
kTextTEStyl e 

The  text  style. 
kTextSetSel ecti on 
The  text  selection. 
kTextBackCol  or 

The  text  background  color. 
kTextForeCol or 

The  text  foreground  color. 
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kTextFace 

The  text  face. 
kTextFont 

The  text  font. 
kTextSi ze 

The  text  size. 
kTextAl i gnment 

The  text  alignment. 
kTexttli  1 1  te 

The  text  highlighting. 
kTextDropShadow 

The  text  drop  shadow. 
kTextDi  spl  ayFl  ags 
Display  flags. 
kTextScrol 1 

The  text  scroll  position. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Movi es .  h 


TextMediaHiliteTextSample 


Specifies  selected  text  to  be  highlighted  for  a  given  text  media  handler. 


Component Res ul t  TextMedi aHi 1 i teTextSampl e 


Medi a  H  a  n  d 1 er 
TimeVal ue 
short 
short 
RGBCol or 


mh , 

sampl eTi me , 
hi  1 i teStart , 
hi  1 i teEnd , 

*rgbHi 1 i teCol  or  ); 


( 


mh 

The  text  media  handler  obtained  byGetMediahlandler  (1-432). 
sampl eT i me 

The  starting  time  in  the  sample. 
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hi  1 i teSta rt 

The  beginning  of  the  text  to  be  highlighted, 
hill teEnd 

The  end  of  the  text  to  be  highlighted.  If  the  hi  1  i  teEnd  parameter  is  greater  than 
the  hi  1  i  teStart  parameter,  then  the  text  is  highlighted  from  the  selection 
specified  by  hi  1  i  teStart  to  hi  1  i  teEnd. 

rgbHi 1 i teCol or 

Contains  a  pointer  to  an  RGBCol  or  (IV-2403)  structure  that  defines  the  color  for 
highlighting.  If  this  parameter  is  not  N I L,  then  the  specified  color  is  used  when 
highlighting  the  text  indicated  by  the  hi  1  i  teStart  and  hiliteEnd  parameters . 
Otherwise,  the  default  system  highlight  color  is  used. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Text  Media  Handler  Functions"  (V-2756) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . TextMedi aHandl er . hi  1  i teTextSampl  e( ) 


T  extMediaRawIdle 


Undocumented 


Component Res ul t  TextMedi aRawIdl e 


Medi aHandl er 
GWorl  dPtr 
GDHandl e 
TimeVal ue 
1  ong 
1  ong 


mh , 
gw, 
gd, 

samp! eTime, 
f 1 ags In , 
*flagsOut  ); 


( 


mh 

The  text  media  handler  obtained  by  GetMedi  aHandl  er  (1-432). 
gw 

A  pointer  to  a  CGraf  Port  (IV-2168)  structure  that  defines  a  graphics  world. 
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gd 

A  handle  to  a  graphics  device, 
sampl eT i me 

Undocumented 
fl agsln 

Undocumented 
f 1 agsOut 

Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

flagsln  Constants 

Undocumented 

Undocumented 

flagsOut  Constants 

Undocumented 

Undocumented 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es .  h 


TextMediaRawSetup 

Undocumented 


ComponentResul t  TextMediaRawSetup  ( 


Medi aHandl er 
GWorl dPtr 
GDHandl e 
voi  d 
1  ong 

TextDescri ptionHandle 
TimeVal ue 


mh , 
gw, 
gd, 

*data , 
dataSi ze , 
tdh , 

sampl eDurati on  ) ; 


mh 

The  text  media  handler  obtained  by  GetMedi  aHandl  er  (1-432). 
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gw 

A  pointer  to  a  CGraf  Port  (IV-2168)  structure  that  defines  a  graphics  world, 
gd 

A  handle  to  a  graphics  device. 

data 

A  pointer  to  data. 
dataSi ze 

The  size  of  the  data. 

tdh 

A  handle  to  a  TextDescri  pti  on  (IV-2474)  structure, 
sampl eDurati on 
Undocumented 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


T  extMediaSetT  extProc 


Specifies  a  custom  function  to  be  called  whenever  a  text  sample  is  displayed  in  a 
movie. 

ComponentResul t  TextMediaSetTextProc  ( 

MediaHandler  mh, 

TextMediaUPP  TextProc, 

long  ref con  ); 


mh 

The  text  media  handler  obtained  by  GetMedi  aHandl  er  (1-432). 

TextProc 

A  Universal  Procedure  Pointer  that  points  to  a  TextMedi  aProc  (III— 2150) 
callback. 
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refcon 

Indicates  a  reference  constant  that  will  be  passed  to  your  callback.  Use  this 
parameter  to  point  to  a  data  structure  containing  any  information  your  function 
needs.  Set  this  parameter  to  0  if  you  don't  need  it. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Text  Media  Handler  Functions"  (V-2756) 


T  extMediaSetT  extProperty 


Sets  properties  of  a  text  media. 


Component Res ul t  TextMedi a SetText Property 
MediaHandler  mh, 

TimeValue  atMedi aTi me , 

long  propertyType , 

void  Mata, 

1 ong  dataSi ze  ) ; 


( 


mh 

The  text  media  handler  obtained  by  GetMedi  aHandl  er  (1-432). 
atMedi aT i me 

The  media  time  of  the  text. 
propertyType 

A  constant  (see  below)  that  identifies  the  text  property  to  be  set. 

data 

A  pointer  to  text  data. 
dataSi ze 

The  size  of  the  data. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 
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propertyType  Constants 

kTextTextHandl e 

A  handle  to  the  text. 
kTextTextPtr 

A  pointer  to  the  text. 
kTextTEStyl e 

The  text  style. 
kTextSetSel ecti  on 
The  text  selection. 
kTextBackCol  or 

The  text  background  color. 
kTextForeCol  or 

The  text  foreground  color. 
kTextFace 

The  text  face. 
kTextFont 

The  text  font. 
kTextSi ze 

The  text  size. 
kTextAl i gnment 

The  text  alignment. 
kTextFli  1  i  te 

The  text  highlighting. 
kTextDropShadow 

The  text  drop  shadow. 
kTextDi  spl  ay  FI  ags 
Display  flags. 
kTextScrol 1 

The  text  scroll  position. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 
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T  extMediaSetT  extSampleData 


Sets  values  before  calling  TextMedi  aAddTextSampl  e  (III— 1936)  or 
TextMedi  aAddTESampl  e  (III — 1933). 

ComponentResul t  TextMediaSetTextSampleData  ( 

MediaHandler  mh, 

void  Mata, 

OSType  datatype  ) ; 


mh 

A  reference  to  the  text  media  handler.  You  obtain  this  reference  from 
GetMedi  aHandl  er  (1-432). 

data 

A  pointer  to  the  data,  defined  by  the  dataType  parameter. 
dataType 

The  type  of  data. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

The  following  code  sample  demonstrates  how  to  use  this  function: 

//  TextMediaSetTextSampleData  coding  example 
short  trans  =  127 ; 

Point  dropOffset; 

MediaHandler  mh; 

dropOffset. h  =  dropOffset. v  =  4 

TextMedi aSetTextSampl eData(mh,(void  *)&dropOffset , dropShadowOffsetType ) ; 
TextMedi aSetTextSampl eData(mh,(void  *)&trans , dropShadowT ransl ucencyType ) ; 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Text  Media  Handler  Functions"  (V-2756) 

Related  Java  Methods 

qui ckti me . std .movi es .medi a .TextMedi aHandl er . setDropShadowOffset ( ) , 
qui ckti me . std .movi es .medi a .TextMedi aHandl er . set DropShadowT ransl ucencyt ) 
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T  rackT  imeToMediaT  ime 


Converts  a  track's  time  value  to  a  time  value  that  is  appropriate  to  the  track's  media, 
using  the  track's  edit  list. 

TimeValue  TrackTimeToMediaTime  ( 

TimeValue  value. 

Track  theTrack  ); 

val  ue 

The  track's  time  value;  must  be  expressed  in  the  time  scale  of  the  movie  that 
contains  the  track. 

theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

function  result  The  track's  time  value,  but  in  the  media's  time  coordinate  system.  If 
the  track  time  corresponds  to  empty  space,  this  function  returns  a 
value  of  -1. 

Discussion 

This  function  maps  the  track  time  through  the  track's  edit  list  to  come  up  with  the 
media  time.  This  time  value  contains  the  track's  time  value  according  to  the  media's 
time  coordinate  system.  If  the  time  you  specified  lies  outside  of  the  movie's  active 
segment  or  corresponds  to  empty  space  in  the  track,  this  function  returns  a  value  of 
-1.  Hence  you  can  use  it  to  determine  whether  a  specified  track  edit  is  empty. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Working  With  Track  Time"  (V-2733) 

Related  Java  Methods 

qui ckt ime . std .movi es . Track. trackTi meToMedi aTime( ) 


TransformFixedPoints 


Transforms  a  set  of  fixed  points  through  a  specified  matrix. 

OSErr  TransformFixedPoints  ( 
const  MatrixRecord  *m, 

FixedPoint  *fpt. 
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1  ong  count  ) ; 

m 

A  pointer  to  the  transformation  matrix  for  this  operation. 

fpt 

A  pointer  to  the  first  fixed  point  to  be  transformed, 
count 

The  number  of  fixed  points  to  be  transformed.  These  points  must  be  stored 
immediately  following  the  point  specified  by  the  fpt  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Applying  Matrix  Transformations"  (V-2766) 

Related  Java  Methods 

quicktime.std.image.Matrix.transformDPointsO 


T  ransf  ormFixedRect 


Transforms  the  upper-left  and  lower-right  points  of  a  rectangle  through  a  matrix 
that  is  specified  by  fixed  points. 

Boolean  TransformFixedRect  ( 
const  MatrixRecord  *m, 

FixedRect  *fr, 

Fi xedPoi nt  *fpp  ) : 


m 

A  pointer  to  the  matrix  for  this  operation, 
fr 

A  pointer  to  the  Fi  xedRect  (IV-2260)  structure  that  defines  the  rectangle  to  be 
transformed.  T ransformFi  xedRect  returns  the  updated  coordinates  into  the 
structure  referred  to  by  this  parameter.  If  the  resulting  rectangle  has  been 
rotated  or  skewed  (that  is,  the  transformation  involves  operations  other  than 
scaling  and  translation),  the  function  sets  the  returned  Bool  ean  value  to  FALSE 
and  returns  the  coordinates  of  the  boundary  box  of  the  transformed  rectangle. 
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The  function  then  updates  the  points  specified  by  the  f  pp  parameter  to  contain 
the  coordinates  of  the  four  corners  of  the  transformed  rectangle. 

fpp 

A  pointer  to  an  array  of  four  fixed  points.  The  function  returns  the  coordinates 
of  the  four  corners  of  the  rectangle  after  the  transformation  operation.  If  you  do 
not  want  this  information,  set  this  parameter  to  NIL. 

function  result  If  the  resulting  rectangle  has  been  rotated  or  skewed  (that  is,  the 
transformation  involves  operations  other  than  scaling  and 
translation),  the  function  returns  FALSE,  updates  the  rectangle 
specified  by  the  f  r  parameter  to  define  the  boundary  box  of  the 
resulting  rectangle,  and  places  the  coordinates  of  the  comers  of  the 
resulting  rectangle  in  the  points  specified  by  the  fpp  parameter.  If  the 
transformed  rectangle  and  its  boundary  box  are  the  same,  the 
function  returns  TRUE. 

Discussion 

This  function  does  not  return  any  error  codes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Applying  Matrix  Transformations"  (V-2766) 

Related  Java  Methods 

qui ckti me . std . image . Matrix. transf ormDRect( ) 


T  ransf  ormPoints 


Transforms  a  set  of  QuickDraw  points  through  a  specified  matrix. 

OSErr  TransformPoints  ( 
const  MatrixRecord 
Poi  nt 
1  ong 

mp 

A  pointer  to  the  transformation  matrix  for  this  operation. 

ptl 

A  pointer  to  the  first  QuickDraw  point  to  be  transformed. 


*mp , 

*ptl , 
count  ); 
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count 

The  number  of  QuickDraw  points  to  be  transformed.  These  points  must  be 
stored  immediately  following  the  point  specified  by  the  ptl  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Applying  Matrix  Transformations"  (V-2766) 

Related  Java  Methods 

qui ckti me. std . image .Matrix. transformPoi nts ( ) 


TransformRect 

Transforms  the  upper-left  and  lower-right  points  of  a  rectangle  through  a  specified 

matrix. 

Boolean  TransformRect  ( 
const  MatrixRecord 
Rect 

Fi xedPoi nt 

m 

The  matrix  for  this  operation. 

r 

A  pointer  to  the  Rect  (IV-2399)  structure  that  defines  the  rectangle  to  be 
transformed.  The  function  returns  the  updated  coordinates  into  the  structure 
referred  to  by  this  parameter. 

fpp 

A  pointer  to  an  array  of  four  fixed  points.  The  TransformRect  function  returns 
the  coordinates  of  the  four  comers  of  the  rectangle  after  the  transformation 
operation.  If  you  do  not  want  this  information,  set  this  parameter  to  NIL. 

function  result  If  the  resulting  rectangle  has  been  rotated  or  skewed  (that  is,  the 
transformation  involves  operations  other  than  scaling  and 
translation),  the  function  returns  FALSE,  updates  the  rectangle 
specified  by  the  r  parameter  to  define  the  boundary  box  of  the 
resulting  rectangle,  and  places  the  coordinates  of  the  comers  of  the 
resulting  rectangle  in  the  points  specified  by  the  fpp  parameter.  If  the 


*m , 

*r , 

*fpp  ) ; 
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transformed  rectangle  and  its  boundary  box  are  the  same,  the 
function  returns  TRUE. 

Discussion 

This  function  does  not  return  any  error  codes. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Applying  Matrix  Transformations"  (V-2766) 

Related  Java  Methods 

qui ckti me . std . image . Matrix. transformRect( ) 


TransformRgn 

Applies  a  specified  matrix  to  a  region. 

OSErr  TransformRgn  ( 

MatrixRecordPtr  matrix, 

RgnHandie  rgn  ); 

matri x 

Points  to  the  matrix  for  this  operation.  The  TransformRgn  function  currently 
supports  only  translation  and  scaling  operations, 
rgn 

A  handle  to  the  MacRegi  on  (IV-2303)  structure  to  be  transformed.  The  function 
transforms  each  point  in  the  region  according  to  the  specified  matrix 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Applying  Matrix  Transformations"  (V-2766) 

Related  Java  Methods 

qui ckti me . std . image . Matrix. transformRgn( ) 
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TranslateMatrix 


T  ranslateMatrix 


Adds  a  translation  value  to  a  specified  matrix. 

void  TranslateMatrix  ( 

MatrixRecord  *m, 

Fixed  deltaH, 

Fi xed  del taV  ) ; 


m 

A  pointer  to  the  Matrix  Re  cord  (IV-2304)  structure  for  this  operation, 
del taH 

The  value  to  be  added  to  the  x  coordinate  translation  value, 
del taV 

The  value  to  be  added  to  the  y  coordinate  translation  value. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Managing  Matrices"  (V-2764) 

Related  Java  Methods 

qu ickti me. std.image.Matrix. translate!) 


Trimlmage 


Adjusts  a  compressed  image  to  the  boundaries  defined  by  a  specified  rectangle. 


OSErr  Trimlmage  ( 

ImageDescriptionHandle 
Ptr 
1  ong 

ICMDataProcRecordPtr 
Ptr 
1  ong 

ICMFlushProcRecordPtr 

Rect 

ICMProgressProcRecordPtr 


desc , 
i nData , 
i nBufferSi ze , 
dataProc , 
outData , 
outBufferSi ze , 
f 1 ushProc , 

*tri mRect , 
progressProc  ) ; 


III-1956 


Inside  QuickTime:  Functions  R-Z 


Trimlmage 


desc 

A  handle  to  the  ImageDescri  pti  on  (IV-2285)  structure  that  describes  the 
compressed  image.  On  return,  the  compressor  updates  this  structure  to 
describe  the  resized  image, 
i nData 

A  pointer  to  the  compressed  image  data.  This  pointer  must  contain  a  32-bit 
clean  address.  If  the  entire  compressed  image  cannot  be  stored  at  this  location, 
your  application  may  provide  an  ICMDataProc  callback  through  the  dataProc 
parameter. 

i nBuf f erSi ze 

The  size  of  the  buffer  to  be  used  by  the  data-loading  function  specified  by  the 
dataProc  parameter.  If  you  have  not  specified  a  data-loading  function,  this 
parameter  is  ignored. 
dataProc 

A  pointer  to  an  ICMDataProcRecord  (IV-2279)  structure  that  references  an 
ICMDataProc  (III— 2090)  callback.  If  there  is  not  enough  memory  to  store  the 
compressed  image,  the  compressor  calls  a  function  you  provide  that  loads  more 
compressed  data.  If  you  have  not  provided  such  a  data-loading  function,  set 
this  parameter  to  NIL.  In  this  case,  the  compressor  expects  that  the  entire 
compressed  image  is  in  the  memory  location  specified  by  the  i  nData  parameter 
outData 

A  pointer  to  a  buffer  to  receive  the  trimmed  image.  The  Image  Compression 
Manager  places  the  actual  size  of  the  resulting  image  into  the  dataSi  ze  field  of 
the  ImageDescri  pti  on  (IV-2285)  structure  referred  to  by  the  desc  parameter. 
This  pointer  must  contain  a  32-bit  clean  address.  Your  application  should 
create  a  destination  buffer  at  least  as  large  as  the  source  image.  If  there  is  not 
sufficient  memory  to  store  the  compressed  image,  you  may  choose  to  write  the 
compressed  data  to  mass  storage  during  the  compression  operation,  in  which 
case  you  use  the  flushProc  parameter  to  identify  your  data-unloading  function 
to  the  compressor. 
outBuf f erSi ze 

The  size  of  the  buffer  to  be  used  by  the  data-unloading  function  specified  by  the 
flushProc  parameter.  If  you  have  not  specified  a  data-unloading  function,  this 
parameter  is  ignored, 
f 1 ushProc 

A  pointer  to  an  ICMF1  ushProcRecord  (IV-2280)  structure  that  references  an 
ICMF1  ushProc  (III— 2091)  callback.  If  there  is  not  enough  memory  to  store  the 
compressed  image,  the  compressor  calls  a  function  you  provide  that  unloads 
some  of  the  compressed  data.  If  you  have  not  provided  such  a  data-unloading 
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function,  set  this  parameter  to  N I L.  In  this  case,  the  compressor  writes  the  entire 
compressed  image  into  the  memory  location  specified  by  the  data  parameter 

tri  mRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  defines  the  desired  image 
dimensions.  On  return,  the  function  adjusts  the  rectangle  values  so  that  they 
refer  to  the  same  rectangle  in  the  result  image.  This  is  necessary  whenever  data 
is  removed  from  the  beginning  or  left  side  of  the  image. 

progressProc 

A  pointer  to  an  ICMProgressProcRecord  (IV-2284)  structure  that  references  an 
ICMProgressProc  (III— 2093)  callback.  During  the  operation,  the  compressor  may 
occasionally  call  a  function  you  provide  in  order  to  report  its  progress.  If  you 
have  not  provided  such  a  progress  function,  set  this  parameter  to  NIL.  If  you 
pass  a  value  of  -1,  you  obtain  a  standard  progress  function. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

Programming  summary:  "Working  With  Pixel  Maps"  (V-2789) 

Related  Java  Methods 

qui ckti me . std . i mage . QT Image . tri m( ) 


TuneGetlndexedNoteChannel 


Determines  how  many  parts  a  tune  is  playing  and  which  instrument  is  assigned  to 
those  parts. 

ComponentResul t  TuneGetlndexedNoteChannel  ( 

TunePlayer  tp, 

1 ong  i  , 

NoteChannel  *nc  ) ; 


tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDef  aul  tComponent  (11-1131). 

i 

Note  channel  index,  or  0  to  get  the  number  of  parts. 
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nc 

A  pointer  to  an  allocated  initialized  note  channel. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  tune  player  allocates  note  channels  that  best  satisfy  the  requested  instrument  in 
the  tune  header.  The  application  can  use  this  call  to  determine  which  instrument 
was  actually  used  for  each  note  channel.  This  function  takes  the  tune  player  in  the 
tp  parameter  and  returns  the  number  of  parts  (l...n)  allocated  to  the  tune  player. 
You  can  then  pass  the  function  a  part  index  and  it  returns,  in  the  nc  parameter,  the 
note  channel  allocated  for  that  part. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

qui cktime . std .musi c .Tune PI ayer . getNumberOf NoteChannel  s ( ) , 
qui cktime . std .musi c .Tune PI ayer . get  Indexed NoteChannel ( ) 


TuneGetNoteAllocator 


Returns  the  instance  of  the  note  allocator  that  the  tune  player  is  using. 

NoteAl 1 ocator  TuneGetNoteAllocator  ( 

TunePlayer  tp  ); 


tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDefaul tComponent  (11-1131). 

function  result  A  note  allocator  or  an  error  code.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

qui cktime . std .musi c .Tune PI ayer . get NoteAl locator!) 
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TuneGetPartMix 

Gets  volume,  balance,  and  mixing  settings  for  a  specified  part  of  a  tune. 

ComponentResul t  TuneGetPartMix  ( 

TunePlayer  tp, 

unsigned  long  partNumber, 

long  *volumeOut, 

long  *balanceOut, 

1 ong  *mixFl agsOut  ) ; 

tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDef  aul  tComponent  (11-1131). 

partNumber 

The  part  number  for  this  request, 
vol umeOut 

Returns  the  volume  for  the  part, 
bal anceOut 

Returns  the  balance  for  the  part. 
mixFl agsOut 

Returns  flags  (see  below)  that  control  part  mixing. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

mixFIagsOut  Constants 

kT  uneMi xMute 

Disable  the  part  so  that  it  is  not  heard. 
kT  uneMi xSol o 

Include  only  soloed  parts  in  the  mix  if  any  parts  are  soloed. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

quicktime.std.music.TunePlayer.getPartMixO 

See  Also 

For  the  corresponding  set  function,  see  T uneSetPartMi  x  (III— 1970). 
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TuneGetStatus 


Returns  an  initialized  structure  describing  the  state  of  the  tune  player  instance. 

ComponentResul t  TuneGetStatus  ( 

TunePlayer  tp, 

TuneStatus  *status  ); 


tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 

status 

A  pointer  to  an  initialized  TuneStatus  (IV-2492)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusIc.h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

qui cktime . std .musi c .Tune PI ayer . get St at us ( ) 


TuneGetTimeBase 


Returns  the  time  base  of  the  tune  player. 

ComponentResul t  TuneGetTimeBase  ( 
TunePlayer  tp, 

TimeBase  *tb  ); 


tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 
tb 

A  pointer  to  a  time  base  identifier,  such  as  that  returned  by  NewT i meBase 
(11-1119).  On  return,  the  time  base  used  to  control  the  sequence  timing. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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Discussion 

The  sequence  can  be  controlled  in  several  ways  through  its  time  base.  The  rate  of 
playback  can  be  changed,  or  the  time  base  object  can  be  slaved  to  a  clock  or  time 
base  different  than  real  time. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

quicktime.std.music.TunePlayer.getTimeBaset ) , 
qui ckti me . std . cl ocks .Time Base . f romT unePl ayer ( ) , 
qui ckti me . std . cl ocks .Time Base . f romSequenceGrabber ( ) 


TuneGetTimeScale 


Returns  the  current  time  scale  for  a  specified  tune  player  instance. 

ComponentResul t  TuneGetTimeScale  ( 

TunePlayer  tp, 

TimeScale  *scale  ) ; 


tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDef  aul  tComponent  (11-1131). 
seal  e 

A  pointer  to  an  initialized  TimeScale  variable  that  indicates  the  tune  player's 
current  time  scale  in  units  per  second. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

quicktime.std.music.TunePlayer.getTimeScaleO 


See  Also 

For  the  corresponding  set  function,  see  T uneSetT i  meScal  e  (III— 1973). 


III-1962 


Inside  QuickTime:  Functions  R-Z 


TuneGetVolume 


TuneGetVolume 

Returns  the  volume  associated  with  an  entire  tune  sequence. 

ComponentResul t  TuneGetVolume  ( 

TunePlayer  tp  ); 


tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 

function  result  The  volume  as  a  value  from  0.0  to  1.0,  or  a  negative  result  code.  See 
"Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

qui cktime . std .musi c .Tune PI ayer . getVol ume( ) 


See  Also 

For  the  corresponding  set  function,  see  TuneSetVol  ume  (III— 1974). 


Tunelnstant 


Plays  a  particular  sequence  of  events  active  at  a  specified  position. 

ComponentResul t  Tunelnstant  ( 

TunePlayer  tp, 

unsigned  long  *tune, 

unsigned  long  tunePosition  ); 


tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 

tune 

A  pointer  to  tune  sequence  data. 
tunePosi ti on 

The  position  within  the  tune  sequence  data  in  time  units. 
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III-1963 


TunePreroll 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  plays  the  notes  that  are  "on"  at  the  point  specified  by  the  tunePosition 
parameter.  The  notes  are  started  and  then  left  playing  on  return.  The  notes  can  be 
silenced  by  calling  TuneStop  (III— 1975).  This  call  is  useful  for  enabling  user 
"scrubbing"  on  a  sequence. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

qui cktime. std .musi c. Tune PI ayer . i ns t ant ( ) 


TunePreroll 


Prepares  to  play  a  tune  player  sequence  data  by  attempting  to  reserve  note  channels 
for  each  part  in  the  sequence. 

ComponentResul t  TunePreroll  ( 

T unePl ayer  tp  ) ; 


tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDef  aul  tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

qui cktime. std .musi c. Tune PI ayer . prerol 1 ( ) 


TuneQueue 


Places  a  sequence  of  music  events  into  a  queue  to  be  played. 


III-1964 
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TuneQueue 


ComponentResul t  TuneQueue  ( 


TunePl  ayer 
unsigned  long 
Fi  xed 

unsigned  long 
unsigned  long 
unsigned  long 
TuneCal 1 BackUPP 
1  ong 


tp, 

*tune , 
tuneRate , 

tuneStartPosi ti on , 
tuneStopPosi ti on , 
queueFl ags , 
cal  1 BackProc , 
refCon  ); 


tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 

tune 

A  pointer  to  an  array  of  events,  terminated  by  a  marker  event  of  subtype 
kMarkerEventEnd.  See  "QTMA  Events"  (IV-2686). 

tuneRate 

Speed  at  which  to  play  the  sequence.  "Normal"  speed  is  0x00010000. 
tuneStartPosi ti on 

Sequence  starting  time. 
tuneStopPosi ti  on 

Sequence  stopping  time.  The  tuneStartPosi  ti  on  and  tuneStopPosi  ti  on 
parameters  specify,  in  time  units  numbered  from  0  for  the  beginning  of  the 
sequence,  which  part  of  the  queued  sequence  to  play.  To  play  all  of  it,  pass  0 
and  OxFFFFFFFF,  respectively. 

queueFl ags 

Flags  (see  below)  with  details  about  how  to  play  the  queued  tunes, 
cal  1 BackProc 

A  pointer  to  a  TuneCal  1  BackProc  (III— 2152)  callback. 
refCon 

A  reference  constant  to  be  passed  to  your  TuneCal  1  BackProc  callback.  Use  this 
parameter  to  point  to  a  data  structure  containing  any  information  your  function 
needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

queueFlags  Constants 

kTuneStartNow 

Play  even  if  another  tune  is  playing.  If  there  is  a  sequence  currently  playing,  the 
newly  queued  sequence  begins  as  soon  as  the  active  sequence  ends  unless  the 
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III-1965 


TuneSetBalance 


kTuneSta  rtNow  flag  is  set,  in  which  case  the  currently  playing  sequence  is 
immediately  terminated  and  the  new  one  started. 

kTuneDontClipNotes 

Allow  notes  to  finish  their  durations  outside  sample. 
kT  uneExcl udeEdgeNotes 

Don't  play  notes  that  start  at  the  end  of  the  tune. 
kTuneQuickStart 

Leave  all  the  controllers  where  they  are  and  ignore  the  start  time. 
kT  uneLoopUnti 1 

Loop  a  queued  tune  if  there  is  nothing  else  in  the  queue. 
kTuneSta rtNewMas ter 

Start  a  new  master  reference  timer. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

qu i ckti me. std. music. TunePl ay er. queue!) 


TuneSetBalance 


Modifies  the  pan  controller  setting  for  a  tune  player. 

ComponentResul t  TuneSetBalance  ( 

TunePlayer  tp, 

1 ong  bal ance  ) ; 


tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDef  aul  tComponent  (11-1131). 

bal ance 

A  new  pan  controller  setting.  Valid  values  are  from  -128  to  128  for  left-to-right 
balance. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


III-1966 
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TuneSetHeader 


Programming  Info 

C  interface  file:  QuickTimeMusIc.h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

qui cktime . std .  musi c .Tune PI ayer . setBal ance( ) 


TuneSetHeader 


Prepares  the  tune  player  to  accept  subsequent  music  event  sequences  by  defining 
one  or  more  parts  to  be  used  by  sequence  Note  events. 

ComponentResul t  TuneSetHeader  ( 

TunePlayer  tp, 

unsigned  long  *header  ); 


tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 

header 

A  pointer  to  a  list  of  instruments  that  will  be  used  in  subsequent  calls  to  the 

TuneQueue  function.  The  list  can  include  events  with  subtypes  of 

kGeneral EventNoteRequest,  kGeneral EventPartKey, 

kGeneral EventAtomi c Instrument,  kGeneral EventMIDIChannel,  and 

kGeneral  EventUsedNotes.  It  can  also  include  atomic  instruments.  The  list  is 

terminated  by  a  marker  event  of  subtype  kMarkerEventEnd.  See  "QTMA  Events" 

(IV-2686). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  the  first  QuickTime  music  architecture  call  to  play  a  music 
sequence.  The  header  parameter  points  to  one  or  more  initialized  General  events 
and  atomic  instruments.  Only  one  call  to  this  function  is  required.  Each  call  to  this 
function  resets  the  tune  player. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusIc.h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 
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III-1967 


TuneSetHeaderWithSize 


Related  Java  Methods 

quicktime.std.music.TunePlayer.setHeaderO 


See  Also 

See  TuneSetHeaderWithSize  (III — 1968)  and  TuneSetNoteChannels  (III — 1969). 


TuneSetHeaderWithSize 


Similar  to  TuneSetHeader  (III— 1967)  but  lets  you  specify  the  header  length. 

ComponentResul t  TuneSetHeaderWithSize  ( 

TunePlayer  tp, 

unsigned  long  *header, 

unsi gned  1 ong  size  ) ; 


tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDef  aul  tComponent  (11-1131). 

header 

A  pointer  to  a  list  of  instruments  that  will  be  used  in  subsequent  calls  to  the 

TuneQueue  function.  The  list  can  include  events  with  subtypes  of 

kGeneral EventNoteRequest,  kGeneral EventPartKey, 

kGeneral  EventAtomi  c Instrument,  kGeneral EventMIDIChannel,  and 

kGeneral  EventUsedNotes.  It  can  also  include  atomic  instruments.  The  list  is 

terminated  by  a  marker  event  of  subtype  kMarkerEventEnd.  See  "QTMA  Events" 

(IV-2686). 

si  ze 

The  size  of  the  header  in  bytes. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  resembles  T uneSetHeader  (III— 1967)  in  that  it  prepares  the  tune  player 
to  accept  subsequent  music  event  sequences  by  defining  one  or  more  parts  to  be 
used  by  sequence  Note  events.  But  unlike  TuneSetHeader,  it  allows  you  to  specify  the 
header  length  in  bytes.  This  prevents  the  call  from  parsing  off  the  end  if  the  music 
event  sequence  is  missing  an  end  marker. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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TuneSetNoteChannels 


Programming  Info 

C  interface  file:  QuickTimeMusIc.h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

qui cktime . std .  musi c .Tune PI ayer . setHeaderWi thSi ze( ) 


See  Also 

See  T uneSetHeader  (III — 1967)  and  T uneSetNoteChannel  s  (III — 1969). 


TuneSetNoteChannels 


Assigns  note  channels  to  a  tune  player. 


ComponentResul t  TuneSetNoteChannels  ( 


TunePl  ayer 
unsigned  long 
NoteChannel 
TunePl ayCal 1 BackUP P 
1  ong 


tp, 

count , 

*noteChannel Li st , 
pi ayCal 1 BackProc , 
refCon  ); 


tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 

count 

The  number  of  note  channels  to  assign. 
noteChannel Li st 

A  pointer  to  the  list  of  note  channels  to  assign.  The  parts  for  the  note  channels 
you  assign  are  numbered  from  1  to  the  value  of  the  count  parameter. 

pi ayCal 1 BackProc 

A  pointer  to  a  T unePl  ayCal  1  BackProc  (III— 2152)  callback  that  is  called  for  each 
event  whose  part  number  is  greater  than  the  value  of  the  count  parameter. 
Events  whose  part  numbers  are  less  than  or  equal  to  the  value  of  the  count 
parameter  are  passed  to  the  note  channel  rather  than  the  callback.  This  lets  you 
to  use  the  tune  player  as  a  general  purpose  timer/ sequencer. 

refCon 

A  reference  constant  to  be  passed  to  your  callback.  Use  this  parameter  to  point 
to  a  data  structure  containing  any  information  your  function  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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TuneSetPartMix 


Discussion 

When  you  call  this  function,  any  note  channels  that  were  previously  assigned  to  the 
tune  player  are  no  longer  used  and  are  disposed  of. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi c .  h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

quicktime.std.music.TunePlayer.setNoteChannelst) 


TuneSetPartMix 


Sets  volume,  balance,  and  mixing  settings  for  a  specified  part  of  a  tune. 

ComponentResul t  TuneSetPartMix  ( 

TunePlayer  tp, 

unsigned  long  partNumber, 
long  volume, 

long  balance, 

1  ong  mi  xFl  ags  ) ; 

tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDef  aul  tComponent  (11-1131). 
partNumber 

The  part  number  for  this  request, 
vol ume 

The  volume  for  the  part, 
bal ance 

The  balance  for  the  part, 
mi  xFl  ags 

Flags  (see  below)  that  control  part  mixing. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

mixFIags  Constants 

kT  uneMi xMute 

Disable  the  part  so  that  it  is  not  heard. 


III-1970 
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kTuneMixSol o 

Include  only  soloed  parts  in  the  mix  if  any  parts  are  soloed. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusIc.h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

qui cktime . std .musi c .Tune PI ayer . setPartMix( ) 


See  Also 

For  the  corresponding  get  function,  see  TuneGetPartMix  (III— 1960). 


T  uneSetPartT  ranspose 


Modifies  the  pitch  and  volume  of  every  note  of  a  tune. 

ComponentResul t  TuneSetPartTranspose  ( 

TunePlayer  tp, 

unsigned  long  part, 

long  transpose, 

long  vel  oci  tyShi  ft  ); 


tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 

part 

The  part  for  which  you  want  to  change  pitch  and  volume, 
transpose 

A  value  by  which  to  modify  the  pitch  of  the  note.  The  value  is  a  small  integer 
for  semitones  or  an  8.8  fixed-point  number  for  microtones, 
vel oci tyShi ft 

A  value  to  add  to  the  vel  oci  ty  parameter  passed  to  NAP1  ayNote  (11-1036). 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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TuneSetSofter 


Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

quicktime.std.rriusic.TiineP'layer.setPartTransposeO 


TuneSetSofter 


Adjusts  the  volume  a  tune  is  played  at  to  the  softer  volume  produced  by  QuickTime 

2.1. 

ComponentResul t  TuneSetSofter  ( 

TunePlayer  tp, 

1 ong  softer  ) ; 


tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDef  aul  tComponent  (11-1131). 

softer 

A  value  of  1  means  play  at  the  QuickTime  2.1  volume;  a  value  of  0  means  don't 
make  the  volume  softer. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  adjusts  the  volume  a  tune  is  played  at  to  the  softer  volume  produced 
by  QuickTime  2.1.  Files  imported  with  QuickTime  2.1  automatically  play  softer. 
Files  imported  with  QuickTime  2.5  or  later  play  at  the  new,  louder  volume. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

qui ckti me. std .musi c. Tune PI  ay er . set Softer ( ) 


TuneSetSoundLocalization 


Passes  sound  localization  data  to  a  tune  player. 


III-1972 
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TuneSetTimeScale 


ComponentResul t  TuneSetSoundLocal izati on  ( 
TunePlayer  tp. 

Handle  data  ); 


tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDefaul tComponent  (11-1131). 

data 

The  sound  localization  data  to  be  passed. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Q  u  i  c  kT i me  M  u  s i c .  h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

qui cktime . std .musi c .Tune PI ayer . s et Sound  Local izati on () 


TuneSetTimeScale 


Sets  the  time  scale  used  by  the  specified  tune  player  instance. 

ComponentResul t  TuneSetTimeScale  ( 

TunePlayer  tp, 

TimeScale  scale  ); 


tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 

scale 

The  time  scale  value  to  be  used,  in  units  per  second. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  sets  the  time  scale  data  used  by  the  tune  player's  sequence  data  when 
interpreting  time-based  events. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Functions  R-Z 


III-1973 


TuneSet  Volume 


Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

quicktime.std.music.TunePlayer.setTimeScaleO 


See  Also 

For  the  corresponding  get  function,  see  TuneGetTimeScal  e  (III— 1962). 


TuneSetVolume 


Sets  the  volume  for  an  entire  sequence. 

ComponentResul t  TuneSetVolume  ( 
TunePlayer  tp, 

Fi xed  vol ume  ) ; 


tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDef  aul  tComponent  (11-1131). 

vol ume 

The  volume  to  use  for  the  sequence.  The  value  is  a  fixed  16.16  number. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  sets  the  volume  level  of  the  active  sequence  to  the  value  of  the  vol  ume 
parameter,  ranging  from  0.0  to  1.0.  Individual  instruments  within  the  sequence  can 
maintain  independent  volume  levels. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

quicktime.std.music.TunePlayer.setVol ume( ) 


See  Also 

For  the  corresponding  get  function,  see  TuneGetVol  ume  (III— 1963). 
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TuneStop 


TuneStop 


Stops  a  currently  playing  sequence. 

ComponentResul t  TuneStop  ( 
TunePlayer  tp, 

long  stopFlags  ); 


tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 

stopFl ags 
Set  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

qui cktime . std .musi c .Tune PI ayer . stop( ) 


TuneTask 


Lets  a  tune  player  to  perform  tasks  it  must  perform  at  foreground  task  time. 

ComponentResul t  TuneTask  ( 

TunePlayer  tp  ); 


tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Call  this  function  periodically  to  allow  a  tune  player  to  perform  certain  operations 
it  can  performed  only  at  foreground  application  task  time.  Specifically,  the 
QuickTime  music  synthesizer  cannot  load  instruments  from  disk  at  interrupt  time. 
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TuneUnroll 


As  a  result,  embedded  program  changes  are  not  performed  until  this  function  is 
called. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

qui cktime. std .musi c. Tune PI ayer . task( ) 


TuneUnroll 


Releases  any  note  channel  resources  that  may  have  been  locked  down  by  previous 
calls  to  TunePreroll  (III— 1964)  for  this  tune  player. 

ComponentResul t  TuneUnroll  ( 

T unePl ayer  tp  ) ; 


tp 

A  tune  player  identifier,  obtained  from  OpenComponent  (11-1130)  or 
OpenDef  aul  tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 

Programming  summary:  "Using  the  Tune  Player"  (V-2914) 

Related  Java  Methods 

qu i c kt i me. std. music.TunePl ayer. unroll ( ) 


TweenerDoTween 


Performs  a  tween  operation. 

ComponentResul t  TweenerDoTween  ( 
TweenerComponent  tc, 

TweenRecord  *tr  ) ; 


III-1976 


Inside  QuickTime:  Functions  R-Z 


Tweenerlnitialize 


tc 

The  tween  component  for  this  operation, 
tr 

A  pointer  to  the  TweenRecord  (IV-2493)  structure  for  the  tween  operation. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

QuickTime  calls  this  function  to  interpolate  the  data  used  during  a  tween  operation. 
The  TweenRecord  (IV-2493)  structure  contains  complete  information  about  the  tween 
operation,  including  the  start  and  end  values  for  the  operation  and  a  percentage  that 
indicates  the  progress  towards  completion  of  the  tween  sample.  This  function 
should  use  the  information  in  the  tween  record  to  calculate  the  tweened  value,  and 
should  call  the  data  function  specified  in  the  tween  record,  passing  it  the  tweened 
value. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Tween  Component  Requirements"  (V-2876) 


T  weenerlnitialize 


Initializes  your  tween  component  for  a  single  tween  operation. 

ComponentResul t  Tweenerlnitialize  ( 

TweenerComponent  tc, 

QTAtomContai ner  container, 

QTAtom  tweenAtom, 

QTAtom  dataAtom  ); 


tc 

The  tween  component  for  this  operation, 
contai ner 

The  container  that  holds  the  atoms  specified  by  the  tweenAtom  and  dataAtom 
parameters. 

tweenAtom 

The  atom  that  contains  all  parameters  for  defining  this  tween.  This  includes  the 
data  atom  and  any  special  atoms,  such  as  an  atom  of  type  '  qd  rg '  (IV-2574),  that 
may  be  necessary. 


Inside  QuickTime:  Functions  R-Z 


III-1977 


TweenerReset 


dataAtom 

The  atom  that  contains  the  values  to  be  tweened.  This  atom  is  a  child  of  the 
atom  specified  by  the  tweenAtom  parameter.  This  parameter  is  provided  as  a 
convenience;  you  can  also  call  QT  atom  container  functions  to  locate  the  data 
atom  in  the  container. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  sets  up  the  tween  component  when  it  is  first  used.  In  your 
implementation  of  this  function,  you  can  allocate  storage  and  set  up  any  structures 
that  you  need  for  the  duration  of  a  tween  operation.  Although  the  container  that 
holds  the  data  atom  is  available  during  each  call  to  TweenerDoTween  (III— 1976),  you 
can  improve  the  performance  of  your  tween  component  by  extracting  the  data  to  be 
used  by  the  TweenerDoTween  function  in  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Tween  Component  Requirements"  (V-2876) 


TweenerReset 

Cleans  up  when  the  tween  operation  is  finished. 

ComponentResul t  TweenerReset  ( 
TweenerComponent  tc  ); 


tc 

The  tween  component  for  this  operation. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  releases  storage  allocated  by  the  tween  component  when  the 
component  is  no  longer  being  used.  It  should  release  any  storage  allocated  by  the 
Tweenerlni  ti  al  i  ze  (III— 1977)  function  and  close  or  release  any  other  resources  used 
by  the  component.  A  tween  component  may  receive  a  Tweenerlni  ti  al  i  ze  call  after 
being  reset. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


III-1978 


Inside  QuickTime:  Functions  R-Z 


UncaptureComponent 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Tween  Component  Requirements"  (V-2876) 


UncaptureComponent 

Uncaptures  a  previously  captured  component. 

OSErr  UncaptureComponent  ( 

Component  aComponent  ); 

aComponent 

The  component  identifier  of  the  component  to  be  uncaptured.  Your  component 
obtains  this  identifier  from  CaptureComponent  (1-74). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components  .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 


UnregisterComponent 

Removes  a  component  from  the  Component  Manager's  registration  list. 

OSErr  UnregisterComponent  ( 

Component  aComponent  ); 

aComponent 

A  component  identifier  that  specifies  the  component  to  be  removed. 
Applications  that  register  components  may  obtain  this  identifier  from 
Regi  sterComponent  (III — 1451)  or  Regi  sterComponentResource  (III — 1453).  The 
component  to  be  removed  from  the  registration  list  must  not  be  in  use  by  any 
applications  or  components. 


Inside  QuickTime:  Functions  R-Z 


III-1979 


UnsignedFixedMulDiv 


function  result  See  "Error  Codes"  (IV-2663).  If  there  are  open  connections  to  the 
component,  this  function  returns  a  negative  result  code.  Returns 
n o  E  r  r  if  there  is  no  error. 

Discussion 

Most  components  are  registered  at  startup  and  remain  registered  until  the 
computer  is  shut  down.  However,  you  may  want  to  provide  some  services 
temporarily.  In  that  case  you  dispose  of  the  component  that  provides  the  temporary 
service  by  using  this  function.  It  removes  the  component  with  the  specified 
component  identifier  from  the  list  of  available  components. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Components .  h 

Programming  summary:  "Functions  Used  By  Components"  (V-2782) 


UnsignedFixedMulDiv 


Performs  multiplications  and  divisions  on  unsigned  fixed-point  numbers. 

Unsi  gnedFi  xed  UnsignedFixedMulDiv  ( 

Unsi gnedFi xed  value, 

Unsi  gnedFi  xed  multiplier, 

Unsi gnedFi xed  divisor  ); 


val  ue 

The  value  to  be  multiplied  or  divided. 

mul ti pi i er 

The  multiplier  to  be  applied  to  the  value  in  the  value  parameter.  Pass 
0x00010000  if  you  do  not  want  to  multiply. 

di vi sor 

The  divisor  to  be  applied  to  the  value  in  the  value  parameter.  Pass  0x00010000 
if  you  do  not  want  to  divide. 

function  result  The  fixed-point  number  that  is  the  value  of  the  val  ue  parameter, 

multiplied  by  the  value  in  the  mul  ti  pi  i  er  parameter  and  divided  by 
the  value  in  the  divisor  parameter.  The  function  performs  both 
operations  before  returning. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


III-1980 


Inside  QuickTime:  Functions  R-Z 


UnsignedFixMulDiv 


Programming  Info 

C  interface  file:  Sound .  h 


UnsignedFixMulDiv 


Performs  multiplications  and  divisions  on  unsigned  fixed-point  numbers. 

Fixed  UnsignedFixMulDiv  ( 

Fixed  src, 

Fi xed  mul  , 

Fixed  divisor  ); 


src 

The  value  to  be  multiplied  or  divided, 
mul 

The  multiplier  to  be  applied  to  the  value  in  the  src  parameter.  Pass  0x00010000 
if  you  do  not  want  to  multiply. 

divisor 

The  divisor  to  be  applied  to  the  value  in  the  src  parameter.  Pass  0x00010000  if 
you  do  not  want  to  divide. 

function  result  The  fixed-point  number  that  is  the  value  of  the  src  parameter, 
multiplied  by  the  value  in  the  mul  parameter  and  divided  by  the 
value  in  the  divisor  parameter.  The  function  performs  both 
operations  before  returning. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


UpdateMovie 


Ensures  that  the  Movie  Toolbox  properly  displays  your  movie  after  it  has  been 
uncovered. 

OSErr  UpdateMovie  ( 

Movie  theMovie  ); 


Inside  QuickTime:  Functions  R-Z 


III-1981 


UpdateMovie 


theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

Your  application  should  call  this  function  during  window  updating.  Don't  call 
MoviesTask  (11-973)  at  this  time;  you  will  observe  better  display  behavior  if  you  call 
it  at  the  end  of  your  update  processing. 

This  function  does  not  actually  update  the  movie's  graphics  world.  Rather,  it 
invalidates  the  movie's  display  state  so  that  the  Movie  Toolbox  redraws  the  movie 
the  next  time  you  call  M  o  v  i  e  s  T  a  s  k .  If  you  need  to  force  a  movie  to  be  redrawn  outside 
of  a  window  update  sequence,  your  application  can  call  this  function  and  then  call 
Movi  esTas  k  to  service  the  movie.  The  Movie  Toolbox  determines  the  portion  of  the 
screen  to  update  by  examining  the  graphics  port's  visible  region. 

The  following  code  snippet  uses  this  function  in  a  Macintosh  Window  Manager 
update  sequence: 

//  UpdateMovie  coding  example 
^include  <Events.h> 

^include  <Tool Uti 1 s . h> 

^include  "Movies.h" 

void  DoUpdate  (WindowPtr  theWindow,  Movie  theMovie) 

{ 

BeginUpdate  (theWindow); 

UpdateMovie  (theMovie); 

EndUpdate  (theWindow); 

}  /*  DoUpdate  */ 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movies.h 

Programming  summary:  "Movies  and  Your  Event  Loop"  (V-2720) 


III-1982 


Inside  QuickTime:  Functions  R-Z 


UpdateMovieResource 


Related  Java  Methods 

qui ckti me . std .movi es . Movi e . update ( ) 


UpdateMovieResource 


Replaces  the  contents  of  a  movie  resource  in  a  specified  movie  file. 

OSErr  UpdateMovieResource  ( 

Movie  theMovie, 

short  resRefNum, 

short  resld, 

ConstStr255Param  resName  ); 

theMovi e 

The  movie  you  wish  to  place  in  the  movie  file.  Your  application  obtains  this 
movie  identifier  from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e 
(11-1080),  and  NewMovi  eFromHandl  e  (11-1084). 

resRefNum 

Identifies  the  movie  file  that  contains  the  resource  to  be  changed.  Your 
application  obtains  this  value  from  OpenMovi  eFi  1  e  (11-1133). 
resld 

The  resource  to  be  changed.  This  value  is  obtained  from  a  previous  call  to 
NewMovi  eFromFi  1  e  (11-1080),  NewMovieFromDataRef  (11-1078),  or  (eng>or-1078)  If 
you  specify  a  single-fork  movie  file  by  passing  the  movielnDataForkResID 
constant,  the  Movie  Toolbox  places  the  movie  resource  into  the  file's  data  fork. 

resName 

Points  to  a  new  name  for  the  resource.  If  you  don't  want  to  change  the 
resource's  name,  set  this  parameter  to  NIL. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Discussion 

You  specify  the  movie  that  is  to  be  placed  into  the  resource.  This  function  can 
accommodate  single-fork  movie  files.  After  updating  the  movie  file,  this  function 
clears  the  movie  changed  flag. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


Inside  QuickTime:  Functions  R-Z 


III-1983 


UseMovieEditState 


Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Saving  Movies"  (V-2715) 

Related  Java  Methods 

quickti  me.  std.  mo  vies.  Mo  vie.  update  Resourcet ) 


UseMovieEditState 


Returns  a  movie  to  the  condition  determined  by  an  edit  state  created  previously. 

OSErr  UseMovieEditState  ( 

Movie  theMovie, 

Movi eEdi tState  toState  ); 

theMovi e 

The  movie  for  this  operation.  Your  application  obtains  this  movie  identifier 
from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080),  and 
NewMovi  eFromHandl  e  (11-1084). 

toState 

The  edit  state  for  this  operation.  Your  application  obtains  this  edit  state 
identifier  when  you  create  the  edit  state  by  calling  NewMovi  eEdi  tState  (11-1073). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Undo  for  Movies"  (V-2748) 

Related  Java  Methods 

quickti me. std. mo vies. Mo vie. useEditStateO 


UseT  rackEditState 


Returns  a  track  to  the  condition  determined  by  an  edit  state  created  previously. 

OSErr  UseTrackEdi tState  ( 

Track  theTrack, 


III-1984 


Inside  QuickTime:  Functions  R-Z 


VDAddKeyColor 


TrackEdi tState  state  ); 
theT  rack 

The  track  for  this  operation.  Your  application  obtains  this  track  identifier  from 
such  functions  as  NewMovi  eT rack  (11-1092)  and  GetMovi  eT rack  (1-497). 

state 

The  edit  state  for  this  operation.  Your  application  obtains  this  edit  state 
identifier  when  you  create  the  edit  state  by  calling  NewT rackEdi  tState  (11-1119). 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  esError 
(1-492)  and  GetMovi  esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Undo  for  Tracks"  (V-2751) 

Related  Java  Methods 

qui ckti me . std .movi es .Track. use Edi tState ( ) 


VDAddKeyColor 


Adds  a  key  color  to  a  component's  list  of  active  key  colors. 

Vi deoDi gi ti zerError  VDAddKeyColor  ( 

VideoDigi tizerComponent  ci  , 

long  *index  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

i  ndex 

A  pointer  to  the  color  to  add  to  the  key  color  list.  The  value  of  the  i  ndex  field 
corresponds  to  a  color  in  the  current  color  lookup  table. 


Inside  QuickTime:  Functions  R-Z 


III-1985 


VDClearClipRgn 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Selectively  Displaying  Video"  (V-2852) 


VDClearClipRgn 


Disables  all  or  part  of  a  clipping  region  that  was  previously  set  with  VDSetCl  i  pRgn 
(III— 2032). 

Vi deoDi gi ti zerError  VDClearClipRgn  ( 

Vi  deoDi gi ti zerComponent  ci  , 

RgnHandle  clipRegion  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

cl i pRegi on 

A  handle  to  a  MacRegi  on  (IV-2303)  structure  that  defines  the  clipping  region  to 
clear.  This  region  must  correspond  to  all  or  part  of  the  clipping  region 
established  previously  with  VDSetCl  i  pRgn  (III— 2032). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 
Programming  summary:  "Video  Clipping"  (V-2853) 

Related  Java  Methods 

qui cktime. std . sg . Vi deoDi gi ti zer . cl earCl i pRgn( ) 


VDCompressDone 

Determines  whether  the  video  digitizer  has  finished  digitizing  and  compressing  a 
frame  of  image  data. 


III-1986 


Inside  QuickTime:  Functions  R-Z 


VDCompressDone 


VideoDigi tizerError  VDCompressDone  ( 


Vi deoDi gi ti zerComponent 

Bool ean 

Ptr 

1  ong 

UInt8 

T i meRecord 


ci  , 

*done , 
*theData , 
*dataSi ze , 
*si mi  1 ari ty , 
*t  ); 


ci 

Identifies  the  application's  connection  to  the  video  digitizer  component.  An 
application  obtains  this  value  from  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 

done 

A  pointer  to  a  Bool  ean  value.  Video  digitizers  set  this  value  to  TRUE  when  they 
are  done.  If  the  digitizer  is  not  yet  done,  it  sets  the  Boolean  value  to  FALSE.  In  this 
case,  the  digitizer  does  not  return  any  other  information.  The  digitizer  is  careful 
to  return  the  frames  in  temporal  order,  and  to  avoid  returning  two  frames  with 
the  same  time  value  (unless  the  rate  is  set  to  0). 
theData 

A  pointer  to  a  field  that  is  to  receive  a  pointer  to  the  compressed  image  data. 
The  digitizer  returns  a  pointer  that  is  valid  in  the  application's  current  memory 
mode. 
dataSi ze 

A  pointer  to  a  field  to  receive  a  value  indicating  the  number  of  bytes  of 
compressed  image  data. 

si  mi  1 ari ty 

A  pointer  to  a  field  to  receive  an  indication  of  the  relative  similarity  of  this 
image  to  the  previous  image  in  a  sequence.  A  value  of  0  indicates  that  the 
current  frame  is  a  key  frame  in  the  sequence.  A  value  of  255  indicates  that  the 
current  frame  is  identical  to  the  previous  frame.  Values  from  1  through  254 
indicate  relative  similarity,  ranging  from  very  different  (1)  to  very  similar  (254). 
This  field  is  only  filled  in  if  the  temporal  quality  passed  in  with 
VDSetCompressi  on  (III— 2034)  is  not  0;  that  is,  if  it  is  not  frame-differenced, 
t 

A  pointer  to  a  Ti  meRecord  (IV-2486)  structure.  When  the  operation  is  complete, 
the  digitizer  fills  in  this  structure  with  information  indicating  when  the  frame 
was  grabbed.  The  time  value  stored  in  this  structure  is  in  the  time  base  that  the 
application  sets  with  VDSetTimeBase  (III— 2054). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Inside  QuickTime:  Functions  R-Z 


III-1987 


VDCompressOneFrameAsync 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Compressed  Source  Devices"  (V-2846) 


VDCompressOneFrameAsync 

Instructs  the  video  digitizer  to  digitize  and  compress  a  single  frame  of  image  data. 

Vi deoDi gi ti zerError  VDCompressOneFrameAsync  ( 

Vi deoDi gi ti zerComponent  ci  ); 


ci 

Identifies  the  application's  connection  to  the  video  digitizer  component.  An 
application  obtains  this  value  from  OpenComponent  (11-1130)  or 
OpenDef  aul  tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Unlike  VDGrabOneFrameAsync  (III— 2025),  this  function  causes  the  video  digitizer  to 
handle  all  details  of  managing  data  buffers. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Controlling  Compressed  Source  Devices"  (V-2846) 


VDDone 


Determines  if  VDGrabOneFrameAsync  (III— 2025)  is  finished  with  a  specific  output 
buffer. 

Vi deoDi gi ti zerError  VDDone  ( 

Vi deoDi gi ti zerComponent  ci  , 

short  buffer  ) ; 


III-1988 


Inside  QuickTime:  Functions  R-Z 


VDGetActiveSrcRect 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef aul  tComponent  (11-1131). 
buffer 

Identifies  the  buffer  for  the  operation.  The  value  of  this  parameter  must 
correspond  to  a  valid  index  into  the  list  of  buffers  you  supply  when  your 
application  calls  VDSetupBuffers  (III— 2055).  This  value  is  zero-based;  that  is,  you 
must  set  this  parameter  to  0  to  refer  to  the  first  buffer  in  the  buffer  list. 

function  result  Returns  a  long  integer  indicating  whether  the  specified 

asynchronous  frame  grab  is  complete.  If  the  returned  value  is  0,  the 
video  digitizer  component  is  still  working  on  the  frame.  If  the 
returned  value  is  nonzero,  the  digitizer  component  is  finished  with 
the  frame  and  the  application  can  perform  its  processing. 

Discussion 

Applications  can  determine  whether  a  video  digitizer  component  supports 
asynchronous  frame  grabbing  by  examining  the  output  capability  flags  of  the 
digitizer  component,  using  VDGetCurrentFl  ags  (III— 1996).  Specifically,  if  the 
digiOutDoesAsyncGrabs  flag  is  set  to  1,  the  digitizer  component  supports  both  this 
function  and  VDGrabOneFrameAsync  (III— 2025). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Controlling  Digitization"  (V-2848) 


VDGetActiveSrcRect 


Obtains  size  and  location  information  for  the  active  source  rectangle  used  by  a 
video  digitizer  component. 

Vi deoDi gi ti zerError  VDGetActiveSrcRect  ( 

Vi deoDi gi ti zerComponent  ci  , 

short  inputStd, 

Rect  *acti veSrcRect  ); 


The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
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VDGetBlackLevelValue 


i nputStd 

A  short  integer  that  specifies  the  input  video  signal  associated  with  this 
maximum  source  rectangle, 
acti veSrcRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  is  to  receive  the  size  and  location 
information  for  the  active  source  rectangle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

All  video  digitizer  components  must  support  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Setting  Source  Characteristics"  (V-2843) 


VDGetBlackLevelValue 


Returns  the  current  black  level  value. 

Vi deoDi gi ti zerError  VDGetBlackLevelValue  ( 

Vi deoDi gi ti zerComponent  ci  , 

unsigned  short  *blackLevel  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

bl ackLevel 

A  pointer  to  an  integer  field  that  is  to  receive  the  current  black  level  value.  Black 
level  values  range  from  0  to  65,535,  where  0  represents  the  maximum  black 
value  and  65,535  represents  the  minimum  black  value. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Controlling  Analog  Video"  (V-2850) 


III-1990 


Inside  QuickTime:  Functions  R-Z 


VDGetBrightness 


See  Also 

For  the  corresponding  set  function,  see  VDSetBl  ackLevel  Val  ue  (III— 2031). 


VDGetBrightness 


Returns  the  current  brightness  value. 

Vi deoDi gi ti zerError  VDGetBrightness  ( 
VideoDigi ti zerComponent  ci , 

unsigned  short  brightness  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
bri ghtness 

A  pointer  to  an  integer  field  that  is  to  receive  the  current  brightness  value. 
Brightness  values  range  from  0  to  65,535,  where  0  is  the  darkest  possible  setting 
and  65,535  is  the  lightest  possible  setting. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Controlling  Analog  Video"  (V-2850) 

See  Also 

For  the  corresponding  set  function,  see  VDSetBri  ghtness  (III— 2032). 


VDGetClipState 


Determines  whether  clipping  is  enabled. 

Vi deoDi gi ti zerError  VDGetClipState  ( 

VideoDigi ti zerComponent  ci  , 

short  *clipEnable  ); 


The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
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VDGetCLUTInUse 


cl i pEnabl e 

A  pointer  to  a  short  integer  field  that  is  to  receive  a  value  indicating  whether 
clipping  is  enabled.  The  video  digitizer  component  places  0  into  the  field  if 
clipping  is  disabled,  and  1  if  it  is  enabled. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 
Programming  summary:  "Video  Clipping"  (V-2853) 

Related  Java  Methods 

quicktime.std.sg.VideoDigitizer.getClipStateO 


See  Also 

For  the  corresponding  set  function,  see  VDSetCl  i  pState  (III— 2033). 


VDGetCLUTInUse 


Obtains  the  color  lookup  table  used  by  a  video  digitizer  component. 

Vi deoDI gi ti zerError  VDGetCLUTInUse  ( 

Vi  deoDi gi ti zerComponent  ci  , 

CTabHandle  *col orTabl eHandl e  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

col orTabl eHandl e 

A  pointer  to  a  field  that  is  to  receive  a  handle  to  a  Col  orTabl  e  (IV-2210) 
structure.  The  video  digitizer  component  returns  a  handle  to  its  color  lookup 
table.  Applications  can  then  set  the  destination  to  use  this  returned  Col  orTabl  e 
structure.  Your  application  is  responsible  for  disposing  of  this  handle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 
Programming  summary:  "Controlling  Color"  (V-2849) 


III-1992 


Inside  QuickTime:  Functions  R-Z 


VDGetCompressionTime 


VDGetCompressionTime 


Confirms  or  quantifies  a  video  digitizer's  compression  settings. 


VideoDigi tizerError  VDGetCompressionTime  ( 
Vi deoDi gi ti zerComponent  ci , 


OSType 

short 

Rect 

CodecQ 

CodecQ 

unsigned 


1  ong 


compressi onType , 
depth , 

*srcRect, 

*spati al Qual i ty , 
*temporal Qual i ty , 
*compressTime  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
compressi onType 

A  compressor  type.  This  value  corresponds  to  the  component  subtype  of  the 
compressor  component.  See  "Codec  Identifiers"  (IV-2655). 
depth 

The  depth  at  which  the  image  is  to  be  compressed.  Values  of  1,  2, 4,  8, 16,  24, 
and  32  indicate  the  number  of  bits  per  pixel  for  color  images.  Values  of  33, 34, 
36,  and  40  indicate  1-bit,  2-bit,  4-bit,  and  8-bit  grayscale,  respectively,  for 
grayscale  images. 
srcRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  defines  the  portion  of  the  source 
image  to  compress, 
spati al Qual i ty 

A  pointer  to  a  field  containing  the  desired  compressed  image  quality  (see 
below).  The  compressor  sets  this  field  to  the  closest  actual  quality  that  it  can 
achieve.  A  value  of  N I L  indicates  that  the  client  does  not  want  this  information. 

temporal Qual i ty 

A  pointer  to  a  field  containing  the  desired  sequence  temporal  quality  (see 
below).  The  compressor  sets  this  field  to  the  closest  actual  quality  that  it  can 
achieve.  A  value  of  N I L  indicates  that  the  client  does  not  want  this  information. 
compressTime 

A  pointer  to  a  field  to  receive  the  compression  time,  in  milliseconds.  Your 
component  should  return  a  long  integer  indicating  the  maximum  number  of 
milliseconds  it  would  require  to  compress  the  specified  image.  If  your 
component  cannot  determine  the  amount  of  time  required  to  compress  the 
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VDGetCompressionTypes 


image,  set  this  field  to  0.  A  value  of  N I L  indicates  that  the  client  does  not  want 
this  information. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

spatialQuality  and  temporalQuality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics, 
codec Normal  Qua  1 i ty 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 

codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field. 
codecLosslessQuality 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

Discussion 

The  sequence  grabber's  video  compression  settings  dialog  box  uses  this  function  to 
snap  the  quality  slider  to  the  correct  value  when  working  with  a  compression  type 
that  is  specified  by  the  video  digitizer. 

Version  Notes 

In  QuickTime  1.5,  video  digitizers  could  provide  compressed  data  directly  to 
clients;  however,  there  was  no  way  to  preflight  the  settings  for  compression.  In 
QuickTime  2.1,  this  function  was  added  to  allow  the  video  digitizer  to  quantify  the 
compression  time  for  the  actual  quality  levels  that  will  be  used. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Compressed  Source  Devices"  (V-2846) 


VDGetCompressionTypes 

Determines  the  image-compression  capabilities  of  the  video  digitizer. 
Vi deoDi gi ti zerError  VDGetCompressionTypes  ( 


III-1994 


Inside  QuickTime:  Functions  R-Z 


VDGetContrast 


Vi deoDi gi ti zerComponent  ci  , 

VDCompressi onLi stHandl e  h  ); 


ci 

Identifies  an  application's  connection  to  the  video  digitizer  component.  An 
application  obtains  this  value  from  OpenComponent  (11-1130)  or 
OpenDefaul tComponent  (11-1131). 
h 

A  handle  to  receive  the  compression  information  in  one  or  more 
VDCompressi  on  Li  st  (IV-2497)  structures.  If  the  digitizer  supports  more  than  one 
compression  type,  it  creates  an  array  of  structures  in  this  handle.  The  video 
digitizer  returns  information  about  its  capabilities  by  formatting  these 
structures. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

There  must  be  a  decompressor  component  of  the  appropriate  type  available  in  the 
system  if  an  application  is  to  display  images  from  a  compressed  image  sequence. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Controlling  Compressed  Source  Devices"  (V-2846) 


VD  GetContrast 


Returns  the  current  contrast  value. 

Vi deoDi gi ti zerError  VDGetContrast  ( 
VideoDigi ti zerComponent  ci  , 

unsigned  short  *contrast  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

contrast 

A  pointer  to  an  integer  field  that  is  to  receive  the  current  contrast  value.  The 
contrast  value  ranges  from  0  to  65,535,  where  0  represents  no  change  to  the 
basic  image  and  larger  values  increase  the  contrast  of  the  video  image  (they 
increase  the  slope  of  the  transform). 
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VDGetCurrentFlags 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Analog  Video"  (V-2850) 

See  Also 

For  the  corresponding  set  function,  see  VDSetContrast  (III— 2036). 


VDGetCurrentFlags 


Returns  status  information  about  a  specified  video  digitizer  component. 

Vi deoDi gi ti zerError  VDGetCurrentFlags  ( 

Vi deoDi gi ti zerComponent  ci  , 

long  *i nputCurrentFl ag , 

long  *outputCurrentFl ag  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 
i nputCurrentFl ag 

A  pointer  to  a  long  integer  that  is  to  receive  the  current  input  state  flags  for  the 
video  digitizer  component;  see  "Video  Digitizer  Capabilities"  (IV-2696). 

outputCurrentFl ag 

A  pointer  to  a  long  integer  that  is  to  receive  the  current  output  state  flags  for  the 
video  digitizer  component;  see  "Video  Digitizer  Capabilities"  (IV-2696). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  often  more  convenient  than  VDGetDigitizerlnfo  (III— 1998).  For 
example,  this  function  provides  a  simple  mechanism  for  determining  whether  a 
video  digitizer  is  receiving  a  valid  input  signal.  An  application  can  retrieve  the 
current  input  state  flags  and  test  the  high-order  bit  by  examining  the  sign  of  the 
returned  value.  If  the  value  is  negative  (that  is,  the  high-order  bit,  di  gi  I  nSi  gnal  Lock, 
is  set  to  1),  the  digitizer  component  is  receiving  a  valid  input  signal. 

Special  Considerations 

All  video  digitizer  components  must  support  this  function. 
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VDGetDataRate 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Getting  Information  About  Video  Digitizer 
Components"  (V-2843) 

See  Also 

You  can  also  use  VDGetDi  gi  ti  zerlnfo  (III— 1998)  in  your  application  to  retrieve 
capability  and  current  status  information  about  a  video  digitizer  component. 


VDGetDataRate 


Retrieves  information  that  describes  the  performance  capabilities  of  a  video 
digitizer. 

Vi deoDi gi ti zerError  VDGetDataRate  ( 

VideoDigi ti zerComponent  ci  , 

long  *mi 1 1 i SecPerFrame , 

Fixed  *f ramesPerSecond , 

long  *bytesPerSecond  ); 

ci 

Identifies  the  application's  connection  to  the  video  digitizer  component.  An 
application  obtains  this  value  from  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 

mi  1 1 i SecPerFrame 

A  pointer  to  a  long  integer.  The  video  digitizer  returns  a  value  that  indicates  the 
number  of  milliseconds  of  synchronous  overhead  involved  in  digitizing  a 
single  frame.  This  value  includes  the  average  delay  incurred  between  the  time 
when  the  digitizer  requests  a  frame  from  its  associated  device,  and  the  time  at 
which  the  device  delivers  the  frame. 

f ramesPerSecond 

A  pointer  to  a  fixed  value.  The  video  digitizer  supplies  the  maximum  rate  at 
which  it  can  capture  video.  Note  that  this  value  may  differ  from  the  rate  that 
the  application  set  with  VDSetFrameRate  (III— 2041). 
bytesPerSecond 

A  pointer  to  a  long  integer.  Video  digitizers  that  can  return  compressed  image 
data  return  a  value  that  indicates  the  approximate  number  of  bytes  per  second 
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VDGetDigitizerlnfo 


that  the  digitizer  is  generating  compressed  data,  given  the  current  compression 
and  frame  rate  settings. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Digitization"  (V-2848) 

See  Also 

For  the  corresponding  set  function,  see  VDSetDataRate  (III— 2037). 


VDGetDigitizerlnfo 


Returns  capability  and  status  information  about  a  specified  video  digitizer 
component. 

Vi deoDi gi ti zerError  VDGetDigitizerlnfo  ( 

Vi deoDi gi ti zerComponent  ci  , 

Di gi ti zerlnfo  *info  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

i  nfo 

A  pointer  to  a  Digi  ti  zerlnfo  (IV-2234)  structure.  The  function  returns 
information  describing  the  capabilities  of  the  specified  video  digitizer  into  this 
structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

All  video  digitizer  components  must  support  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Getting  Information  About  Video  Digitizer 
Components"  (V-2843) 


III-1998 


Inside  QuickTime:  Functions  R-Z 


VDGetDigitizerRect 


Related  Java  Methods 

qui ckti me . std . sg . Vi deoDi gi ti zer . getDi gi ti zer Inf o( ) 


VDGetDigitizerRect 


Returns  the  current  digitizer  rectangle. 

Vi deoDi gi ti zerError  VDGetDigitizerRect  ( 
VideoDigi ti zerComponent  ci  , 

Rect  *di gi ti zerRect  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef aul  tComponent  (11-1131). 
di gi ti zerRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  is  to  receive  the  size  and  location 
information  for  the  current  digitizer  rectangle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

All  video  digitizer  components  must  support  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Setting  Source  Characteristics"  (V-2843) 

See  Also 

For  the  corresponding  set  function,  see  VDSetDi  gi  ti  zerRect  (III— 2038). 


VDGetDMADepths 


Determines  which  pixel  depths  a  digitizer  supports. 

Vi deoDi gi ti zerError  VDGetDMADepths  ( 

VideoDigi ti zerComponent  ci  , 

long  *depthArray, 

long  *preferredDepth  ); 


Inside  QuickTime:  Functions  R-Z 


III-1999 


VDGetDMADepths 


ci 

Identifies  the  application's  connection  to  the  video  digitizer  component.  An 
application  obtains  this  value  from  OpenComponent  (11-1130)  or 
OpenDef  aul  tComponent  (11-1131). 
depthArray 

A  pointer  to  a  long  integer.  The  video  digitizer  returns  a  value  that  indicates  the 
depths  it  can  support.  Each  depth  is  represented  by  a  single  bit  in  this  field. 
More  than  one  bit  may  be  set  to  1. 

preferredDepth 

A  pointer  to  a  long  integer.  Video  digitizers  that  have  a  preferred  depth  value 
return  that  value  in  this  field,  using  one  of  the  possible  values  of  the  depthArray 
parameter.  Digitizers  that  do  not  prefer  any  given  value  set  this  field  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  flags  returned  by  this  function  augment  the  information  that  an  application  can 
obtain  from  the  digitizer's  output  capability  flags  in  the  Di  gi  ti  zerlnfo  (IV-2234) 
structure.  If  a  digitizer  does  not  support  this  function  but  does  support  DMA,  an 
application  may  assume  that  the  digitizer  can  handle  offscreen  buffers  at  all  of  the 
depths  indicated  in  its  output  capabilities  flags.  Applications  may  use  the  following 
enumerators  to  set  bits  in  the  field  referred  to  by  the  depthArray  parameter. 

enum  { 


dmaDepthl 

=  1 

/* 

supports 

bl 

ack 

and  white 

*/ 

dmaDepth2 

=  2 

/* 

supports 

2- 

bi  t 

color  */ 

dmaDepth4 

=  4 

/* 

supports 

4- 

bi  t 

color  */ 

dmaDepth8 

=  8 

/* 

supports 

8- 

bi  t 

color  */ 

dmaDepthl6 

=  16 

/* 

supports 

16 

-bit 

color  */ 

dmaDepth32 

=  32 

/* 

supports 

32 

-bit 

color  */ 

dmaDepth2Gray 

=  64 

/* 

supports 

2- 

bi  t 

grayscal e 

*/ 

dmaDepth4Gray 

=  128 

/* 

supports 

4- 

bi  t 

grayscal e 

*/ 

dmaDepth8Gray 

=  256 

/* 

supports 

8- 

bi  t 

grayscal  e 

*/ 

}; 

Special  Considerations 

Before  a  program  that  uses  a  video  digitizer  creates  an  offscreen  buffer,  it  should 
call  the  this  function  to  determine  the  pixel  depths  supported  by  the  digitizer.  If 
possible,  the  program  should  use  the  preferred  depth,  in  order  to  obtain  the  best 
possible  display  performance. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 
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VDGetFieldPreference 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 
Programming  summary:  "Controlling  Color"  (V-2849) 


VDGetFieldPreference 


Determines  which  field  is  being  used  in  cases  where  the  image  is  vertically  scaled 
to  half  its  original  size. 

Vi deoDi gi ti zerError  VDGetFieldPreference  ( 

VideoDigi ti zerComponent  ci  , 

short  *fieldFlag  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef aul  tComponent  (11-1131). 
f  i  el  d FI  ag 

Points  to  a  field  that  is  to  receive  a  value  (see  below)  indicating  which  field  is 
being  used. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

fieldFlag  Constants 

vdUseAnyFi el d 

Digitizer  component  decides  which  field  to  use. 
vdUseOddFi  el  d 

Digitizer  component  uses  odd  field. 
vdUseEvenFi el d 

Digitizer  component  uses  even  field. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Video  Digitizer  Utilities"  (V-2853) 

See  Also 

For  the  corresponding  set  function,  see  VDSetFi  el  dPreference  (III— 2040). 


Inside  QuickTime:  Functions  R-Z 


III-2001 


VDGetHue 


VDGetHue 


Returns  the  current  hue  value. 

( 

ci  , 

*hue  )  ; 


Vi deoDi gi ti zerError  VDGetHue 
Vi deoDi gi ti zer Component 
unsigned  short 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

hue 

A  pointer  to  an  integer  that  is  to  receive  the  current  hue  value.  Hue  is  similar  to 
the  tint  control  on  a  television,  and  it  is  specified  in  degrees  with 
complementary  colors  set  180  degrees  apart  (red  is  0  degrees,  green  is  +120 
degrees,  and  blue  is  -120  degrees).  Video  digitizer  components  support  hue 
values  that  range  from  0  (-180  degrees  shift  in  hue)  to  65,535  (+179  degrees  shift 
in  hue),  where  32,767  represents  a  0  degree  shift  in  hue. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Analog  Video"  (V-2850) 

See  Also 

For  the  corresponding  set  function,  see  VDSetHue  (III— 2041). 


VDGetlmageDescription 


Retrieves  an  ImageDescription  (IV-2285)  structure  from  a  video  digitizer. 

Vi deoDi gi ti zerError  VDGetlmageDescription  ( 

Vi  deoDi gi ti zerComponent  ci  , 

ImageDescri pti onHandl e  desc  ); 


Identifies  the  application's  connection  to  the  video  digitizer  component.  An 
application  obtains  this  value  from  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 


III-2002 


Inside  QuickTime:  Functions  R-Z 


VDGetlnput 


desc 

A  handle.  The  video  digitizer  fills  this  handle  with  an  ImageDescri  pti  on 
(IV-2285)  structure  containing  information  about  the  digitizer's  current 
compression  settings.  The  digitizer  resizes  the  handle  appropriately.  It  is  the 
application's  responsibility  to  dispose  of  this  handle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Controlling  Compressed  Source  Devices"  (V-2846) 


VDGetlnput 


Returns  data  that  identifies  the  currently  active  input  video  source. 

Vi deoDi gi ti zerError  VDGetlnput  ( 

VideoDigi ti zerComponent  ci  , 

short  *input  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
i  nput 

A  pointer  to  a  short  integer  that  is  to  receive  the  identifier  for  the  currently 
active  input  video  source.  Video  digitizer  components  number  video  sources 
sequentially,  starting  at  0.  So,  if  the  first  source  is  active,  this  function  sets  the 
field  referred  to  by  the  input  parameter  to  0. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

All  video  digitizer  components  must  support  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Selecting  an  Input  Source"  (V-2844) 


Inside  QuickTime:  Functions  R-Z 


III-2003 


VDGetlnputColorSpaceMode 


Related  Java  Methods 

quicktime.std.sg.VideoDigitizer.getlnputt) 

See  Also 

For  the  corresponding  set  function,  see  VDSetlnput  (III— 2042). 


VDGetlnputColorSpaceMode 


Determines  whether  a  digitizer  is  operating  in  color  or  grayscale  mode. 

Vi deoDi gi ti zerError  VDGetlnputColorSpaceMode  ( 

Vi deoDi gi ti zerComponent  ci  , 

short  *col orSpaceMode  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

col orSpaceMode 

A  pointer  to  a  value  that  indicates  whether  the  digitizer  is  operating  in  color  (1) 
or  grayscale  (0)  mode. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Applications  can  determine  whether  a  digitizer  component  supports  grayscale  or 
color  digitization  by  examining  the  digitizer  component's  input  capability  flags. 
Specifically,  if  the  digilnDoesColor  flag  is  set  to  1 ,  the  digitizer  component  supports 
color  digitization.  Similarly,  if  the  di  gi  InDoesBW  flag  is  set  to  1,  the  digitizer 
component  supports  grayscale  digitization.  Applications  can  use 
VDGetCurrentFl  ags  (III— 1996)  to  obtain  the  input  capability  flags  of  a  digitizer 
component. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 
Programming  summary:  "Controlling  Color"  (V-2849) 

See  Also 

For  the  corresponding  set  function,  see  VDSetlnputCol  orSpaceMode  (III— 2043). 


III-2004 


Inside  QuickTime:  Functions  R-Z 


VDG  etlnputF  ormat 


VD  GetlnputFormat 


Determines  the  format  of  the  video  signal  provided  by  a  specified  video  input 
source. 

Vi deoDi gi ti zerError  VDGetlnputFormat  ( 

VideoDigi ti zerComponent  ci  , 

short  input, 

short  *format  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
i  nput 

The  input  video  source  for  this  request.  Video  digitizer  components  number 
video  sources  sequentially,  starting  at  0.  So,  to  request  information  about  the 
first  video  source,  an  application  sets  this  parameter  to  0.  Applications  can  get 
the  number  of  video  sources  supported  by  a  video  digitizer  component  by 
calling  VDGetNumberOf  Inputs  (III— 2013). 
format 

A  pointer  to  a  short  integer  that  is  to  receive  a  constant  (see  below)  that  specifies 
the  video  format  of  the  specified  input  source. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

format  Constants 

composi teln 

The  input  video  signal  is  in  composite  format. 
sVi deoln 

The  input  video  signal  is  in  s-video  format. 
rgbComponentln 

The  input  video  signal  is  in  RGB  component  format. 

Discussion 

All  video  digitizer  components  must  support  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Selecting  an  Input  Source"  (V-2844) 


Inside  QuickTime:  Functions  R-Z 


III-2005 


VDGetlnputGammaRecord 


VDGetlnputGammaRecord 


Retrieves  a  pointer  to  the  active  input  VDGamma Record  (IV-2498)  structure  for  a  video 
digitizer. 

Vi deoDi gi ti zerError  VDGetlnputGammaRecord  ( 

Vi deoDi gi ti zerComponent  ci  , 

VDGamRecPtr  *i nputGammaPtr  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

i nputGammaPtr 

A  pointer  to  a  field  that  is  to  receive  a  pointer  to  an  input  VDGamma  Record 
(IV-2498)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Gamma  structures  give  applications  complete  control  over  color  filtering 
transforms  and  are  therefore  more  precise  than  the  gamma  values  that  can  be  set  by 
calling  VDSetlnputGammaVal  ue  (III-2044). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

See  Also 

For  the  corresponding  set  function,  see  VDSetlnputGammaRecord  (III-2044). 


VDGetlnputGammaValue 


Returns  the  current  gamma  values. 

Vi deoDi gi ti zerError  VDGetlnputGammaValue  ( 
Vi deoDi gi ti zerComponent  ci  , 

Fixed  *channell, 

Fixed  *channel2, 

Fi xed  *channel 3  ) ; 


III-2006 


Inside  QuickTime:  Functions  R-Z 


VDGetlnputName 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
channel  1 

A  pointer  to  a  fixed  integer  field  that  is  to  receive  the  gamma  value  for  the  red 
component  of  the  input  video  signal. 

channel  2 

A  pointer  to  a  fixed  integer  field  that  is  to  receive  the  gamma  value  for  the  green 
component  of  the  input  video  signal, 
channel  3 

A  pointer  to  a  fixed  integer  field  that  is  to  receive  the  gamma  value  for  the  blue 
component  of  the  input  video  signal. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Controlling  Analog  Video"  (V-2850) 

See  Also 

For  the  corresponding  set  function,  see  VDSetlnputGammaValue  (III-2044). 


VDGetlnputName 


Gets  the  name  of  a  video  input. 

Vi deoDi gi ti zerError  VDGetlnputName  ( 
VideoDigi ti zerComponent  ci  , 

1  ong  vi deolnput , 

Str255  name  ); 


ci 

Specifies  the  video  digitizer  component  for  this  operation.  Applications  can 
obtain  this  reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent 
(11-1131). 

vi deolnput 

The  input  video  source  for  this  request.  Video  digitizer  components  number 
video  sources  sequentially,  starting  at  0.  So,  to  request  information  about  the 
first  video  source,  an  application  sets  this  parameter  to  0.  Applications  can  get 


Inside  QuickTime:  Functions  R-Z 


III-2007 


VDGetKeyColor 


the  number  of  video  sources  supported  by  a  video  digitizer  component  by 
calling  VDGetNumberOf Inputs  (III— 2013). 

name 

The  video  input  source's  name  string. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


VDGetKeyColor 


Obtains  the  index  value  of  the  active  key  color. 

Vi deoDi gi ti zerError  VDGetKeyColor  ( 

Vi deoDi gi ti zerComponent  ci  , 

1 ong  *i ndex  ) ; 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

i  ndex 

A  pointer  to  a  field  that  is  to  receive  the  index  of  the  key  color.  This  index  value 
identifies  the  key  color  within  the  currently  active  color  lookup  table.  If  there 
are  several  active  key  colors,  the  video  digitizer  returns  the  first  color  from  the 
key  color  list.  Subsequently,  applications  use  VDGetNextKeyCol  or  (III— 2013)  to 
obtain  other  colors  from  the  list.  If  there  is  no  active  key  color,  the  function  sets 
the  field  to  -1. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Special  Considerations 

All  video  digitizer  components  that  support  key  colors  must  support  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Selectively  Displaying  Video"  (V-2852) 


III-2008 


Inside  QuickTime:  Functions  R-Z 


VDGetKeyColorRange 


See  Also 

For  the  corresponding  set  function,  see  VDSetKeyCol  or  (III— 2046). 


VD  GetKey  ColorRange 


Obtains  the  currently  defined  key  color  range. 

Vi deoDi gi ti zerError  VDGetKeyColorRange  ( 
VideoDigi ti zerComponent  ci  , 

RGBColor  *minRGB, 

RGBColor  *maxRGB  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

mi  nRGB 

A  pointer  to  a  field  that  is  to  receive  the  lower  bound  of  the  key  color  range.  The 
video  digitizer  component  places  the  RGBColor  (IV-2403)  structure  that 
corresponds  to  the  lower  end  of  the  range  in  the  field  referred  to  by  this 
parameter. 

maxRGB 

A  pointer  to  a  field  that  is  to  receive  the  upper  bound  of  the  key  color  range.  The 
video  digitizer  component  places  the  RGBColor  (IV-2403)  structure  that 
corresponds  to  the  upper  end  of  the  range  in  the  field  referred  to  by  this 
parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Selectively  Displaying  Video"  (V-2852) 

See  Also 

For  the  corresponding  set  function,  see  VDSetKeyCol  orRange  (III— 2046). 


VD  GetMaskand  V  alue 


Obtains  the  appropriate  alpha  channel  or  blend  mask  value  for  a  desired  level  of 
video  blending. 


Inside  QuickTime:  Functions  R-Z 


III-2009 


VDGetMaskandValue 


Vi deoDi gi ti zerError  VDGetMaskandValue  ( 

Vi deoDi gi ti zerComponent  ci  , 
unsigned  short  blendLevel, 

long  *mask, 

1 ong  *val ue  ) ; 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 
bl endLevel 

The  desired  blend  level.  Valid  values  range  from  0  to  65,535,  where  0 
corresponds  to  no  video  and  65,535  corresponds  to  all  video. 

mask 

A  pointer  to  a  field  that  is  to  receive  a  value  indicating  which  bits  are 
meaningful  in  the  data  returned  for  the  value  parameter.  The  video  digitizer 
component  sets  to  1  the  bits  that  correspond  to  meaningful  bits  in  the  data 
returned  for  the  value  parameter. 

val  ue 

A  pointer  to  a  field  that  is  to  receive  data  that  can  be  used  to  obtain  the  desired 
blend  level.  The  data  returned  for  the  mask  parameter  indicates  which  bits  are 
valid  in  the  data  returned  for  this  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  information  returned  by  the  digitizer  component  differs  based  on  the  type  of 
blending  supported  by  the  component.  In  all  cases,  however,  the  returned  value  of 
the  value  parameter  contains  the  value  for  the  desired  blend  level,  and  the  returned 
value  of  the  mask  parameter  indicates  which  bits  in  the  value  parameter  are 
meaningful.  Bits  in  the  returned  mask  parameter  value  that  are  set  to  1  correspond 
to  meaningful  bits  in  the  returned  value  parameter  value. 

For  example,  if  an  application  requests  a  50  percent  video  blend  level  from  a 
digitizer  that  supports  8-bit  alpha  channels,  the  digitizer  component  might  return 
OxFFOOOOOOin  the  mask  parameter,  identifying  a  full  upper  byte  as  the  alpha  channel, 
and  0x80000000  in  the  value  parameter,  specifying  a  50  percent  blend  level. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Selectively  Displaying  Video"  (V-2852) 


III-2010 


Inside  QuickTime:  Functions  R-Z 


VDGetMaskPixMap 


VD  GetMaskPixMap 


Retrieves  the  pixel  map  data  for  a  component's  blend  mask. 

Vi deoDi gi tl zerError  VDGetMaskPixMap  ( 

VideoDigi ti zerComponent  ci  , 

PixMapHandle  maskPixMap  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

maskPi xMap 

A  handle  to  a  Pi  xMap  (IV-2332)  structure.  The  video  digitizer  component 
returns  the  pixel  map  data  for  its  blend  mask  into  the  P  i  xM  a  p  (IV-2332)  structure 
specified  by  this  parameter.  The  video  digitizer  component  resizes  the  handle 
as  appropriate.  Your  application  is  responsible  for  disposing  of  this  handle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  supported  only  by  digitizer  components  that  support  blend  masks. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Selectively  Displaying  Video"  (V-2852) 


VD  GetMax  AuxBuf  f  er 


Obtains  access  to  buffers  that  are  located  on  special  hardware. 

Vi deoDi gi ti zerError  VDGetMaxAuxBuf fer  ( 

VideoDigi ti zerComponent  ci  , 

PixMapHandle  *pm, 

Rect  *r  ); 


The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 


Inside  QuickTime:  Functions  R-Z 


III-2011 


VDGetMaxSrcRect 


pm 

A  pointer  to  a  handle  to  a  Pi  xMap  (IV-2332)  structure.  The  video  digitizer 
component  returns  a  handle  to  the  destination  P  i  xM  a  p  (IV-2332)  structure  in  the 
field  referred  to  by  this  parameter.  Do  not  dispose  of  this  structure.  If  the 
digitizer  component  cannot  allocate  a  buffer,  this  handle  is  set  to  NIL. 
r 

A  pointer  to  a  Rect  (IV-2399)  structure.  The  video  digitizer  component  places 
the  coordinates  of  the  largest  output  rectangle  it  can  support  into  the  structure 
referred  to  by  this  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Setting  Video  Destinations"  (V-2845) 


VDGetMaxSrcRect 


Returns  the  maximum  source  rectangle. 

Vi deoDi gi ti zerError  VDGetMaxSrcRect  ( 

Vi deoDi gi ti zerComponent  ci  , 

short  inputStd, 

Rect  *maxSrcRect  ) ; 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

i nputStd 

A  short  integer  that  specifies  the  input  video  signal  associated  with  this 
maximum  source  rectangle. 
maxSrcRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  is  to  receive  the  size  and  location 
information  for  the  maximum  source  rectangle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

All  video  digitizer  components  must  support  this  function. 


III-2012 


Inside  QuickTime:  Functions  R-Z 


VDGetN  extKeyCol  in¬ 


version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui ckTi  meComponents  .  h 

Programming  summary:  "Setting  Source  Characteristics"  (V-2843) 


VD  GetN  extKeyColor 


Obtains  the  index  value  of  the  active  key  colors  in  cases  where  the  digitizer 
component  supports  multiple  key  colors. 

Vi deoDi gi ti zerError  VDGetNextKeyCol or  ( 

VideoDigi ti zerComponent  ci  , 

long  index  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef aul  tComponent  (11-1131). 

i  ndex 

A  field  that  is  to  receive  the  index  of  the  next  key  color.  This  index  value 
identifies  the  key  color  within  the  currently  active  color  lookup  table.  If  there 
are  no  more  colors  left  in  the  list,  the  digitizer  component  sets  the  field  referred 
to  by  the  index  parameter  to  -1. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

All  video  digitizer  components  that  support  multiple  key  colors  must  support  this 
function 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Selectively  Displaying  Video"  (V-2852) 


VDGetNumberOflnputs 

Returns  the  number  of  input  video  sources  that  a  video  digitizer  component 
supports. 


Inside  QuickTime:  Functions  R-Z 


III-2013 


VDGetPlayThruDestination 


Vi deoDi gi ti zerError  VDGetNumberOf Inputs  ( 
Vi  deoDi  gi ti zerComponent  ci  , 

short  *i nputs  )  ; 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 
i nputs 

A  pointer  to  an  integer  that  is  to  receive  the  number  of  input  video  sources 
supported  by  the  specified  component.  Video  digitizer  components  number 
video  sources  sequentially,  starting  at  0.  So,  if  a  digitizer  component  supports 
two  inputs,  this  function  sets  the  field  referred  to  by  the  inputs  parameter  to  1. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

All  video  digitizer  components  must  support  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Selecting  an  Input  Source"  (V-2844) 

Related  Java  Methods 

quicktime.std.sg.VideoDigitizer. get Number Of Inputs ( ) 


VDGetPlayThruDestination 

Obtains  information  about  the  current  video  destination. 


Vi deoDi giti zerError  VDGetPl ayThruDesti nation 
Vi deoDi gi ti zerComponent  ci  , 
PixMapHandle  *dest, 

Rect  *destRect, 

MatrixRecord  *m, 

RgnHandl e  *mask  ) ; 


( 


The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 


III-2014 


Inside  QuickTime:  Functions  R-Z 


VDGetPLLFilterType 


dest 

A  pointer  to  a  handle  to  a  Pi  xMap  (IV-2332)  structure.  The  video  digitizer 
component  returns  a  handle  to  the  destination  P  i  xMa  p  (IV-2332)  structure  in  the 
field  referred  to  by  this  parameter.  It  is  the  caller's  responsibility  to  dispose  of 
the  PixMap  structure. 
destRect 

A  pointer  to  a  Rect  (IV-2399)  structure.  The  video  digitizer  component  places 
the  coordinates  of  the  output  rectangle  into  the  structure  referred  to  by  this 
parameter.  If  there  is  no  output  rectangle  defined,  the  component  returns  an 
empty  rectangle. 

m 

A  pointer  to  a  Mat  ri  xRecord  (IV-2304)  structure.  The  video  digitizer  component 
places  the  transformation  matrix  into  the  structure  referred  to  by  this 
parameter. 

mask 

A  pointer  to  a  handle  to  a  MacRegi  on  (IV-2303)  structure.  The  video  digitizer 
component  places  a  handle  to  the  mask  region  into  the  field  referred  to  by  this 
parameter.  Applications  can  use  masks  to  control  the  video  into  the  destination 
rectangle.  If  there  is  no  mask  region  defined,  the  digitizer  component  sets  this 
returned  handle  to  NI L.  The  caller  is  responsible  for  disposing  of  the  MacRegi  on 
structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

All  video  digitizer  components  must  support  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Setting  Video  Destinations"  (V-2845) 

See  Also 

For  the  corresponding  set  function,  see  VDSetPl  ayThruDesti  nati  on  (III— 2048). 


VD  GetPLLFilterT  ype 

Determines  which  phase  locked  loop  (PLL)  mode  is  currently  active  for  a  video 
digitizer. 


Inside  QuickTime:  Functions  R-Z 


III-2015 


VDGetPreferredlmageDimensions 


Vi deoDi gi ti zerError  VDGetPLLFi 1 terType  ( 

Vi  deoDi gi ti zerComponent  ci  , 

short  *pl 1  Type  ) ; 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 
pi  1  Type 

Points  to  a  field  that  is  to  receive  a  value  indicating  which  PLL  mode  is  active. 
Values  are  0  for  broadcast  mode  and  1  for  videotape  recorder  mode. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Video  Digitizer  Utilities"  (V-2853) 

See  Also 

For  the  corresponding  set  function,  see  VDSetPLLFi  1  terType  (III— 2051). 


VDGetPreferredlmageDimensions 


Gets  the  preferred  image  dimensions  for  a  video  digitizer. 

Vi deoDi gi ti zerError  VDGetPreferredlmageDimensions  ( 

Vi deoDi gi ti zerComponent  ci  , 

long  *width, 

1 ong  *hei ght  ) ; 


ci 

Specifies  the  video  digitizer  component  for  this  operation.  Applications  can 
obtain  this  reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent 
(11-1131). 

wi  dth 

A  pointer  to  the  preferred  image  width, 
hei ght 

A  pointer  to  the  preferred  image  height. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


III-2016 


Inside  QuickTime:  Functions  R-Z 


VDGetPreferredTimeScale 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

See  Also 

For  the  corresponding  set  function,  see  V  DSet  Prefer  red  I  mageDi  men  si  on  s  (III— 2051). 


VD  GetPref  erredT  imeScale 


Determines  a  digitizer's  preferred  time  scale. 

Vi deoDi gi ti zerError  VDGetPreferredTimeScale  ( 
VideoDigi ti zerComponent  ci  , 

TimeScale  *preferred  ); 


ci 

Identifies  the  application's  connection  to  the  video  digitizer  component.  An 
application  obtains  this  value  from  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 

preferred 

A  pointer  to  a  time  scale.  The  video  digitizer  returns  information  about  its 
preferred  time  scale  in  this  structure. 

function  result  If  the  digitizer  does  not  have  a  preferred  time  scale,  it  returns  a  result 
code  of  di  gi  UnimpErr.  See  "Error  Codes"  (IV-2663).  Returns  noErr  if 
there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Video  Digitizer  Utilities"  (V-2853) 


VD  GetSaturation 


Returns  the  current  saturation  value. 

Vi deoDi gi ti zerError  VDGetSaturati on  ( 
VideoDigi  ti  zerComponent  ci  , 

unsigned  short  *saturation  ); 


Inside  QuickTime:  Functions  R-Z 


III-2017 


VDGetSharpness 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 
saturati on 

A  pointer  to  an  integer  that  is  to  receive  the  current  saturation  value.  The 
saturation  value  controls  color  intensity.  For  example,  at  high  saturation  levels, 
red  appears  to  be  red;  at  low  saturation,  red  appears  as  pink.  Valid  saturation 
values  range  from  0  to  65,535,  where  0  is  the  minimum  saturation  value  and 
65,535  specifies  maximum  saturation. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Analog  Video"  (V-2850) 

See  Also 

For  the  corresponding  set  function,  see  VDSetSaturati  on  (III— 2053). 


VDGetSharpness 


Returns  the  current  sharpness  value. 

Vi deoDi gi ti zerError  VDGetSharpness  ( 

Vi deoDi gi ti zerComponent  ci  , 

unsigned  short  *sharpness  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

sharpness 

A  pointer  to  an  integer  that  is  to  receive  the  current  sharpness  value.  The 
sharpness  value  ranges  from  0  to  65,535,  where  0  represents  no  sharpness 
filtering  and  65,535  represents  full  sharpness  filtering.  Higher  values  result  in  a 
visual  impression  of  increased  picture  sharpness. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


III-2018 


Inside  QuickTime:  Functions  R-Z 


VDGetSoundlnputDriver 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Controlling  Analog  Video"  (V-2850) 

See  Also 

For  the  corresponding  set  function,  see  VDSetSharpness  (III— 2053). 


VD  GetSoundlnputDriver 


Retrieves  information  about  a  video  digitizer's  sound  input  driver. 

Vi deoDi gi ti zerError  VDGetSoundlnputDriver  ( 

VideoDigi ti zerComponent  ci  , 

Str255  soundDri verName  ); 


ci 

Identifies  the  application's  connection  to  the  video  digitizer  component.  An 
application  obtains  this  value  from  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 

soundDri verName 

A  pointer  to  a  string.  The  video  digitizer  returns  the  name  of  its  sound  input 
driver.  If  the  digitizer  does  not  have  an  associated  driver,  it  returns  a  result  code 
of  di  gi  UnimpErr. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Video  Digitizer  Utilities"  (V-2853) 


VD  GetSoundlnputSource 


Instructs  your  video  digitizer  component  to  return  the  sound  input  source 
associated  with  a  particular  video  input. 

Vi deoDi gi ti zerError  VDGetSoundlnputSource  ( 

VideoDigi ti zerComponent  ci  , 

long  videoinput, 

long  *sound!nput  ); 


Inside  QuickTime:  Functions  R-Z 


III-2019 


VDGetTimeCode 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 
vi deolnput 

The  input  video  source  for  this  request.  Video  digitizer  components  number 
video  sources  sequentially,  starting  at  0.  So,  to  request  information  about  the 
first  video  source,  an  application  sets  this  parameter  to  0.  Applications  can  get 
the  number  of  video  sources  supported  by  a  video  digitizer  component  by 
calling  VDGetNumberOf  Inputs  (III— 2013). 

soundlnput 

The  sound  input  index  to  use  with  the  sound  input  driver  returned  by 
VDGetSoundlnputDri ver  (III — 2019). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Some  video  digitizers  may  associate  different  sound  inputs  with  each  video  input. 
VDGetSoundlnputDri  ver  (III— 2019)  returns  the  name  of  the  sound  input  driver  that 
the  sound  input  is  associated  with. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Compressed  Source  Devices"  (V-2846) 


VDGetTimeCode 


Instructs  your  video  digitizer  component  to  return  timecode  information  for  the 
incoming  video  signal. 


Vi deoDi gi ti zerError  VDGetTimeCode  ( 

Vi deoDi gi ti zerComponent  ci , 

TimeRecord  *atTime, 

void  *ti meCodeFormat , 

void  *ti meCodeTi me  ); 


The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 


III-2020 


Inside  QuickTime:  Functions  R-Z 


VDGetVBlankRect 


atT i me 

A  pointer  to  a  Ti  meRecord  (IV-2486)  structure  to  receive  the  QuickTime  movie 
time  value  corresponding  to  the  timecode  information, 
ti meCodeFormat 

A  pointer  to  a  Ti  meCodeDef  (IV-2482)  structure.  Your  video  digitizer  component 
returns  the  movie's  timecode  definition  information  in  this  structure. 

timeCodeTime 

A  pointer  to  a  Ti  meCodeRecord  (IV-2484)  structure.  Your  video  digitizer 
component  returns  the  time  value  corresponding  to  the  movie  time  contained 
in  this  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Typically,  this  function  is  called  once,  at  the  beginning  of  a  capture  session.  The  use 
of  this  function  assumes  that  the  timecoding  for  the  entire  capture  session  will  be 
continuous. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Controlling  Digitization"  (V-2848) 


VD  GetVBlankRect 


Returns  the  vertical  blanking  rectangle. 

Vi deoDi gi ti zerError  VDGetVBlankRect  ( 
VideoDigi ti zerComponent  ci  , 

short  inputStd, 

Rect  *vBlankRect  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

i nputStd 

A  short  integer  (see  below)  that  identifies  the  signaling  standard  used  in  the 
source  video  signal. 


Inside  QuickTime:  Functions  R-Z 


III-2021 


VDGetVideoDefaults 


vBl ankRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  is  to  receive  the  size  and  location 
information  for  the  vertical  blanking  rectangle. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inputStd  Constants 

ntscln 

Input  video  signal  to  digitize  is  in  NTSC  format, 
pal  In 

Input  video  signal  to  digitize  is  in  PAL  format, 
secamln 

Input  video  signal  to  digitize  is  in  SECAM  format. 

Discussion 

All  video  digitizer  components  must  support  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Setting  Source  Characteristics"  (V-2843) 


VDGetVideoDefaults 


Returns  the  recommended  values  for  many  of  the  analog  video  parameters  that 
may  be  set  by  applications. 


Vi deoDi gl ti zerError  VDGetVideoDefaults  ( 


Vi deoDi gi ti zer Component 


unsi  t 
unsi 
unsi 
unsi 
unsi 
unsi 
unsigned  short 


igned  short 
igned  short 
igned  short 
igned  short 
igned  short 
igned  short 


c  i  , 

*bl ackLevel , 
*whi teLevel , 
*bri ghtness , 
*hue , 

*saturati on , 
*contrast , 
*sharpness  ) ; 


The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef aul  tComponent  (11-1131). 


III-2022 


Inside  QuickTime:  Functions  R-Z 


VDGetVideoDefaults 


bl  ackLevel 

A  pointer  to  an  integer  that  is  to  receive  the  default  black  level  value.  Black  level 
values  range  from  0  to  65,535,  where  0  represents  the  maximum  black  value 
and  65,535  represents  the  minimum  black  value, 
whi teLevel 

A  pointer  to  an  integer  that  is  to  receive  the  default  white  level  value.  White 
level  values  range  from  0  to  65,535,  where  0  represents  the  minimum  white 
value  and  65,535  represents  the  maximum  white  value. 

bri ghtness 

A  pointer  to  an  integer  that  is  to  receive  the  default  brightness  value. 
Brightness  values  range  from  0  to  65,535,  where  0  is  the  darkest  possible  setting 
and  65,535  is  the  lightest  possible  setting, 
hue 

A  pointer  to  an  integer  that  is  to  receive  the  default  hue  value.  Hue  is  similar  to 
the  tint  control  on  a  television,  and  it  is  specified  in  degrees  with 
complementary  colors  set  180  degrees  apart  (red  is  0  degrees,  green  is  +120 
degrees,  and  blue  is  -120  degrees).  Video  digitizer  components  support  hue 
values  that  range  from  0  (-180  degrees  shift  in  hue)  to  65,535  (+179  degrees  shift 
in  hue),  where  32,767  represents  a  0  degree  shift  in  hue. 
saturati on 

A  pointer  to  an  integer  that  is  to  receive  the  default  saturation  value.  The 
saturation  value  controls  color  intensity.  For  example,  at  high  saturation  levels, 
red  appears  to  be  red;  at  low  saturation,  red  appears  as  pink.  Valid  saturation 
values  range  from  0  to  65,535,  where  0  is  the  minimum  saturation  value  and 
65,535  specifies  maximum  saturation. 

contrast 

A  pointer  to  an  integer  that  is  to  receive  the  default  contrast  value.  The  contrast 
value  ranges  from  0  to  65,535,  where  0  represents  no  change  to  the  basic  image 
and  larger  values  increase  the  contrast  of  the  video  image  (they  increase  the 
slope  of  the  transform), 
sharpness 

A  pointer  to  an  integer  that  is  to  receive  the  default  sharpness  value.  The 
sharpness  value  ranges  from  0  to  65,535,  where  0  represents  no  sharpness 
filtering  and  65,535  represents  full  sharpness  filtering.  Higher  values  result  in  a 
visual  impression  of  increased  picture  sharpness. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

All  video  digitizer  components  must  support  this  function. 


V 


Inside  QuickTime:  Functions  R-Z 


III-2023 


VDGetWhiteLevelValue 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Analog  Video"  (V-2850) 


VDGetWhiteLevelValue 


Returns  the  current  white  level  value. 

Vi deoDi gi ti zerError  VDGetWhiteLevelValue  ( 

Vi  deoDi gi ti zerComponent  ci  , 

unsigned  short  *whiteLevel  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

whi teLevel 

A  pointer  to  an  integer  that  is  to  receive  the  current  white  level  value.  White 
level  values  range  from  0  to  65,535,  where  0  represents  the  minimum  white 
value  and  65,535  represents  the  maximum  white  value. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Controlling  Analog  Video"  (V-2850) 

See  Also 

For  the  corresponding  set  function,  see  VDSetWhi  teLevel  Val  ue  (III— 2055). 


VDGrabOneFrame 

Instructs  the  video  digitizer  component  to  digitize  a  single  frame  of  source  video. 

Vi deoDi gi ti zerError  VDGrabOneFrame  ( 

Vi deoDi gi ti zerComponent  ci  ); 


III-2024 


Inside  QuickTime:  Functions  R-Z 


VDGrabOneFrameAsync 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef aul  tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

If  the  specified  digitizer  component  is  already  digitizing  continuously  when  the 
application  calls  this  function,  the  digitizer  component  returns  the  next  digitized 
frame  and  then  stops.  If  the  digitizer  component  is  stopped,  the  component 
digitizes  a  single  frame  and  then  stops.  To  resume  continuous  digitization, 
applications  should  call  VDSetPl  ayThruOnOff  (III— 2050). 

Special  Considerations 

This  function  supports  synchronous  single-frame  video  digitization;  that  is,  the 
digitizer  component  does  not  return  control  to  your  application  until  it  has 
successfully  processed  the  next  video  frame.  Some  video  digitizer  components  may 
also  support  asynchronous  single-frame  digitization.  Applications  can  request 
asynchronous  digitization  by  calling  VDGrabOneFrameAsync  (III— 2025). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Controlling  Digitization"  (V-2848) 


VD  GrabOneFrame  Async 


Instructs  the  video  digitizer  component  to  start  to  digitize  asynchronously  a  single 
frame  of  source  video. 

Vi deoDi gi ti zerError  VDGrabOneFrameAsync  ( 

VideoDigi ti zerComponent  ci  , 

short  buffer  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

buffer 

Identifies  the  next  output  buffer.  The  value  of  this  parameter  must  correspond 
to  a  valid  index  into  the  list  of  buffers  that  you  supply  when  your  application 


Inside  QuickTime:  Functions  R-Z 


III-2025 


VDPreflightDestination 


calls  VDSetupBuffers  (III— 2055).  Note  that  this  value  is  zero-based  (that  is,  you 
must  set  this  parameter  to  0  to  refer  to  the  first  buffer  in  the  buffer  list). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

When  calling  this  function,  the  application  specifies  the  next  destination  video 
buffer,  allowing  the  digitizer  component  to  quickly  switch  from  the  current  buffer 
to  the  next  buffer.  In  this  manner,  your  application's  ability  to  grab  video  at  high 
frame  rates  is  enhanced.  If  the  specified  digitizer  component  is  already  digitizing 
continuously  when  the  application  calls  this  function,  the  digitizer  component 
returns  the  next  digitized  frame  and  then  stops.  If  the  digitizer  component  is 
stopped,  the  component  digitizes  a  single  frame  and  then  stops.  To  resume 
continuous  digitization,  applications  should  call  VDSetPl  ayThruOnOff  (III— 2050). 

This  function  also  allows  applications  to  use  more  than  one  destination  buffer  for 
the  digitized  video.  The  application  defines  these  buffers  by  calling  VDSetupBuffers 
(III— 2055).  The  application  specifies  one  of  these  destination  buffers  for  the  digitized 
frame  when  it  calls  VDSetPl  ayThruDesti  nati  on  (III— 2048)  or 
VDSetPl  ayThruGl  obal  Rect  (III — 2049). 

Special  Considerations 

Applications  can  determine  whether  a  video  digitizer  component  supports 
asynchronous  frame  grabbing  by  using  VDGetCurrentFlags  (III— 1996)  to  retrieve  the 
digitizer  component's  output  capability  flags.  If  the  digiOutDoesAsyncGrabs  flag  is 
set  to  1,  the  digitizer  component  supports  both  this  function  and  VDDone  (III— 1988). 
If  a  video  digitizer  component  does  not  support  asynchronous  digitization, 
applications  must  use  VDGrabOneFrame  (III— 2024)  to  perform  single-frame 
digitization. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Digitization"  (V-2848) 


VDPreflightDestination 

Verifies  that  a  video  digitizer  component  can  support  a  set  of  destination  settings 
intended  for  use  with  VDSetPl  ayThruDesti  nati  on  (III— 2048). 

Vi deoDi gi ti zerError  VDPreflightDestination  ( 

Vi deoDi gi ti zerComponent  ci , 


III-2026 
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VDPreflightDestination 


Rect 
Pi xMap 
RectPtr 

Matri xRecordPtr 


*di gi ti zerRect , 
**dest , 
destRect , 
m  ) ; 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

di gi ti zerRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  contains  the  size  and  location 
information  for  the  digitizer  rectangle.  The  coordinates  of  this  rectangle  must 
be  relative  to  the  maximum  source  rectangle.  In  addition,  the  digitizer  rectangle 
must  be  within  the  maximum  source  rectangle.  For  a  discussion  of  the 
relationship  between  these  rectangles,  see  "Video  Digitizer  Components"  in 
Inside  Macintosh:  QuickTime  Components  (listed  in  the  bibliography).  If  the 
video  digitizer  component  cannot  accommodate  the  specified  rectangle,  it 
changes  the  coordinates  in  this  structure  to  specify  a  rectangle  that  it  can 
support  and  sets  the  result  to  qtParamErr. 

dest 

A  handle  to  the  destination  Pi  xMap  (IV-2332)  structure. 
destRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  specifies  the  size  and  location  of  the 
video  destination.  This  is  an  optional  parameter.  Applications  may  specify  a 
transformation  matrix  to  control  the  placement  and  scaling  of  the  video  image 
in  the  destination  Pi  xMap  (IV-2332)  structure.  In  this  case,  the  destRect 
parameter  is  set  to  N I L  and  the  m  parameter  specifies  the  matrix.  The  destination 
rectangle  must  be  in  the  coordinate  system  of  the  destination  Pi  xMap  structure 
specified  by  the  dest  parameter.  If  the  video  digitizer  component  cannot 
accommodate  this  rectangle,  it  changes  the  coordinates  in  the  structure  to 
specify  a  rectangle  that  it  can  support  and  sets  the  result  to  qtParamErr. 

m 

A  pointer  to  a  Matri  xRecord  (IV-2304)  structure  containing  the  transformation 
matrix  for  the  destination  video  image.  This  is  an  optional  parameter. 
Applications  may  specify  a  destination  rectangle  to  control  the  placement  and 
scaling  of  the  video  image  in  the  destination  Pi  xMap  (IV-2332)  structure.  In  this 
case,  the  m  parameter  is  set  to  NI L  and  the  destRect  parameter  specifies  the 
destination  rectangle.  If  the  destRect  parameter  is  NIL,  you  can  determine  the 
destination  rectangle  for  simple  matrices  by  calling  T ransf  ormRect  (III— 1954) 
using  the  current  digitizer  rectangle  and  this  matrix.  If  the  video  digitizer 
component  cannot  accommodate  this  matrix,  it  changes  the  values  in  the 
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III-2027 


VDPreflightGlobalRect 


structure  to  define  a  matrix  that  it  can  support  and  sets  the  result  toqtParamErr. 
Applications  can  determine  the  capabilities  of  a  video  digitizer  component  by 
calling  VDGetDi gi ti zerlnfo  (III— 1998). 

function  result  The  application  provides  the  desired  settings  as  parameters  to  this 
function.  The  video  digitizer  component  then  examines  those 
settings.  If  the  digitizer  component  can  support  the  specified 
settings,  it  sets  the  result  code  to  noErr.  If  the  digitizer  component 
cannot  support  the  settings,  it  alters  the  input  settings  to  reflect 
values  that  it  can  support  and  returns  a  result  code  of  qtPa  ramErr.  See 
"Error  Codes"  (IV-2663). 

Discussion 

All  video  digitizer  components  must  support  this  function.  Applications  should  use 
this  function  to  test  destination  settings  whenever  a  video  digitizer  component 
cannot  support  arbitrary  scaling. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Setting  Video  Destinations"  (V-2845) 

See  Also 

Applications  can  determine  the  capabilities  of  a  video  digitizer  component  by 
examining  the  output  capability  flags,  using  VDGetCurrentFl  ags  (III— 1996). 
Specifically,  if  the  di  gi  Out  Does  St  retch  and  di  gi  OutDoesShri  nk  flags  are  set  to  1  in  the 
output  capability  flag,  the  digitizer  component  supports  arbitrary  scaling. 


VDPreflightGlobalRect 


Verifies  that  a  video  digitizer  component  can  support  a  set  of  destination  settings 
intended  for  use  with  VDSetPl  ayThruGl  obal  Rect  (III— 2049). 

Vi deoDi gi ti zerError  VDPreflightGlobalRect  ( 

Vi deoDi gi ti zerComponent  ci  , 

GrafPtr  theWindow, 

Rect  *globalRect  ); 


The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef aul  tComponent  (11-1131). 


III-2028 
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VDReleaseAsyncBuffers 


theWi ndow 

A  pointer  to  the  destination  window, 
gl  obal Rect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  specifies  the  size  and  location  of  the 
video  destination.  This  rectangle  must  be  in  the  coordinate  system  of  the 
destination  window  specified  by  the  theWi  ndow  parameter.  If  the  video  digitizer 
component  cannot  accommodate  this  rectangle,  it  changes  the  coordinates  in 
the  structure  to  specify  a  rectangle  that  it  can  support  and  sets  the  result  to 
qtParamErr. 

function  result  Returns  qtParamErr  if  the  video  digitizer  component  cannot 

accommodate  the  destination  rectangle.  Returns  di  gi  Uni mpErr  if  the 
video  digitizer  component  does  not  support  placing  destination 
video  into  a  rectangle  that  crosses  screens.  See  "Error  Codes" 
(IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

Applications  should  use  this  function  to  determine  whether  a  video  digitizer 
supports  placing  destination  video  into  a  rectangle  that  crosses  screens.  Digitizers 
that  do  not  support  this  capability  return  a  result  of  di  gi  Uni  mpErr. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Setting  Video  Destinations"  (V-2845) 

See  Also 

See  VDPref  1  i  ghtDesti  nati  on  (III — 2026). 


VDReleaseAsyncBuffers 

Releases  the  buffers  that  were  allocated  with  VDSetupBuffers  (III— 2055). 

VideoDigi ti zerError  VDReleaseAsyncBuffers  ( 

Vi deoDi gi ti zerComponent  ci  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 
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VDReleaseCompressBuffer 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Digitization"  (V-2848) 


VDReleaseCompressBuffer 


Frees  a  buffer  received  from  VDCompressDone  (III— 1986). 

Vi deoDi gi ti zerError  VDReleaseCompressBuffer  ( 

Vi  deoDi gi ti zerComponent  ci  , 

Ptr  bufferAddr  ) ; 


ci 

Identifies  the  application's  connection  to  the  video  digitizer  component.  An 
application  obtains  this  value  from  OpenComponent  (11-1130)  or 
OpenDef  aul  tComponent  (11-1131). 

bufferAddr 

Points  to  the  location  of  the  buffer  to  be  released.  This  address  must  correspond 
to  a  buffer  address  that  the  application  obtained  from  VDCompressDone 
(III— 1986). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Controlling  Compressed  Source  Devices"  (V-2846) 


VDResetCompressSequence 


Forces  the  video  digitizer  to  insert  a  key  frame  into  a  temporally  compressed  image 
sequence. 

Vi deoDi gi ti zerError  VDResetCompressSequence  ( 

Vi deoDi gi ti zerComponent  ci  ); 


III-2030 
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VDSetBlackLevelValue 


ci 

Identifies  the  application's  connection  to  the  video  digitizer  component.  An 
application  obtains  this  value  from  OpenComponent  (11-1130)  or 
OpenDefaul tComponent  (11-1131). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Controlling  Compressed  Source  Devices"  (V-2846) 


VD  SetBlackLevel  V  alue 


Sets  the  current  black  level  value. 

Vi deoDi gi ti zerError  VDSetBlackLevelValue  ( 
VideoDigi ti zerComponent  ci  , 

unsigned  short  *blackLevel  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 
bl  ackLevel 

A  pointer  to  an  integer  that  contains  the  new  black  level  value.  Black  level 
values  range  from  0  to  65,535,  where  0  represents  the  maximum  black  value 
and  65,535  represents  the  minimum  black  value.  The  digitizer  component 
returns  the  new  value,  so  that  the  application  can  avoid  using  unsupported 
values  in  future  requests. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Controlling  Analog  Video"  (V-2850) 

See  Also 

For  the  corresponding  get  function,  see  VDGetBl  ackLevel  Value  (III— 1990). 
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VDSetBrightness 


VDSetBrightness 


Sets  the  current  brightness  value. 

Vi deoDi gi ti zerError  VDSetBrightness  ( 

Vi deoDi gi ti zerComponent  ci  , 

unsigned  short  brightness  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

bri ghtness 

A  pointer  to  an  integer  that  contains  the  new  brightness  value.  Brightness 
values  range  from  0  to  65,535,  where  0  is  the  darkest  possible  setting  and  65,535 
is  the  lightest  possible  setting.  The  digitizer  component  returns  the  new  value, 
so  that  the  application  can  avoid  using  unsupported  values  in  future  requests. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Analog  Video"  (V-2850) 

See  Also 

For  the  corresponding  get  function,  see  VDGetBri  ghtness  (III— 1991). 


VDSetClipRgn 


Defines  a  clipping  region  for  a  video  digitizer. 

Vi deoDi gi ti zerError  VDSetClipRgn  ( 

Vi deoDi gi ti zerComponent  ci , 

RgnHandle  clipRegion  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 
cl i pRegi on 

A  handle  to  a  MacRegi  on  (IV-2303)  structure  that  defines  the  clipping  region. 


III-2032 
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VDSetClipState 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 
Programming  summary:  "Video  Clipping"  (V-2853) 

Related  Java  Methods 

qui ckti me . std . sg . Vi deoDi gi ti zer . setCl i p  Rg  n ( ) 


VDSetClipState 


Controls  whether  clipping  is  enabled. 

Vi deoDi gi ti zerError  VDSetClipState  ( 
VideoDigi ti zerComponent  ci  , 

short  clipEnable  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

cl  i  pEnabl e 

Controls  whether  clipping  is  enabled.  Place  0  into  the  short  integer  if  clipping 
is  disabled,  and  1  if  it  is  enabled. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 
Programming  summary:  "Video  Clipping"  (V-2853) 

Related  Java  Methods 

qui ckti me . std . sg .Vi deoDi gi ti zer . setCl i pStatel ) 


See  Also 

For  the  corresponding  get  function,  see  VDGetClipState  (III— 1991). 
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VDSetCompression 


Specifies  certain  compression  parameters. 


Vi deoDi gi ti zerError  VDSetCompression  ( 
Vi deoDi gi ti zerComponent  ci , 
OSType 
short 
Rect 
CodecQ 
CodecQ 
1  ong 


compressType , 
depth , 

*bounds , 
spati al Qual i ty  , 
temporal Qual i ty , 
keyFrameRate  ) ; 


ci 

Identifies  the  application's  connection  to  the  video  digitizer  component.  An 
application  obtains  this  value  from  OpenComponent  (11-1130)  or 
OpenDef  aul  tComponent  (11-1131). 
compressType 

A  compressor  type.  This  value  corresponds  to  the  component  subtype  of  the 
compressor  component;  see  "Codec  Identifiers"  (IV-2655). 
depth 

The  depth  at  which  the  image  is  likely  to  be  viewed.  Compressors  may  use  this 
as  an  indication  of  the  color  or  grayscale  resolution  of  the  image.  Values  of  1, 2, 
4, 8, 16, 24,  and  32  indicate  the  number  of  bits  per  pixel  for  color  images.  Values 
of  33,  34,  36,  and  40  correspond  to  1-bit,  2-bit,  4-bit,  and  8-bit  grayscale  images, 
bounds 

A  pointer  to  a  Rect  (IV-2399)  structure  that  defines  the  desired  boundaries  of 
the  compressed  image, 
spati al Qual i ty 

A  constant  (see  below)  that  indicates  the  desired  image  quality  for  each  frame 
in  the  sequence. 

temporal Qual i ty 

A  constant  (see  below)  that  indicates  the  desired  temporal  quality  for  the 
sequence  as  a  whole. 
keyFrameRate 

The  maximum  number  of  frames  to  allow  between  key  frames.  This  value 
defines  the  minimum  rate  at  which  key  frames  are  to  appear  in  the  compressed 
sequence;  however,  the  video  digitizer  may  insert  key  frames  more  often  than 
an  application  specifies.  If  the  application  requests  no  temporal  compression 


III-2034 
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VDSetCompressionOnOff 


(that  is,  the  application  set  the  temporal Qual  i  ty  parameter  to  0),  the  video 
digitizer  ignores  this  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

spatialQuality  and  temporalQuality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 
codecNormal Quality 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 

codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field, 
codec Los  si  ess Qual i ty 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Controlling  Compressed  Source  Devices"  (V-2846) 


VDSetCompressionOnOff 


Allows  an  application  to  start  and  stop  compression  by  video  digitizers  that  can 
deliver  either  compressed  or  uncompressed  image  data. 

Vi deoDi gi ti zerError  VDSetCompressionOnOff  ( 

VideoDigi ti zerComponent  ci  , 

Boolean  state  ); 
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VDSetContrast 


ci 

Identifies  the  application's  connection  to  the  video  digitizer  component.  An 
application  obtains  this  value  from  OpenComponent  (11-1130)  or 
OpenDef  aul  tComponent  (11-1131). 
state 

A  Bool  ean  value  that  indicates  whether  to  enable  or  disable  compression. 
Applications  set  this  parameter  to  TRUE  to  enable  compression.  Setting  it  to 
FALSE  disables  compression. 

function  result  Digitizers  that  only  provide  compressed  data  have  their 

di  gi  OutDoesCompressOnly  flag  set  to  1,  rather  than  0.  These  digitizers 
may  either  ignore  this  function  or  return  a  nonzero  result  code.  See 
"Error  Codes"  (IV-2663).  Return  noErr  if  there  is  no  error. 

Discussion 

Applications  must  call  this  function  before  they  call  either  VDSetCompressi  on 
(III— 2034)  or  VDCompressOneFrameAsync  (III— 1988).  This  allows  the  video  digitizer  to 
prepare  for  the  operation. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Compressed  Source  Devices"  (V-2846) 


VDSetContrast 


Sets  the  current  contrast  value. 

Vi deoDi gi ti zerError  VDSetContrast  ( 

Vi deoDi gi ti zerComponent  ci  , 

unsigned  short  *contrast  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

contrast 

A  pointer  to  an  integer  that  contains  the  new  contrast  value.  The  contrast  value 
ranges  from  0  to  65,535,  where  0  represents  no  change  to  the  basic  image  and 
larger  values  increase  the  contrast  of  the  video  image  (they  increase  the  slope 
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VDSetDataRate 


of  the  transform).  The  digitizer  component  returns  the  new  value,  so  that  the 
application  can  avoid  using  unsupported  values  in  future  requests. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Controlling  Analog  Video"  (V-2850) 

See  Also 

For  the  corresponding  get  function,  see  VDGetContrast  (III— 1995). 


VDSetDataRate 


Instructs  your  video  digitizer  component  to  limit  the  rate  at  which  it  delivers 
compressed,  digitized  video  data. 

Vi deoDi gi ti zerError  VDSetDataRate  ( 

VideoDigi ti zerComponent  ci  , 

long  bytesPerSecond  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

bytesPerSecond 

The  maximum  data  rate  requested  by  the  application,  in  bytes  per  second.  This 
parameter  is  set  to  0  to  remove  any  data-rate  restrictions. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  function  is  valid  only  for  video  digitizer  components  that  can  deliver 
compressed  video;  that  is,  components  that  support  the  VDCompressOneFrameAsync 
(III— 1988)  function.  Components  that  support  data-rate  limiting  set  the 
codecInfoDoesRateConstrai  n  flag  to  1  in  the  compressFl  ags  field  of  the 
VDCompressi  onLi  st  (IV-2497)  structure  returned  by  the  component  in  response  to 
the  VDGetCompressi  onTypes  (III— 1994)  function.  Your  video  digitizer  component 
should  return  this  data-rate  limit  in  the  bytesPerSecond  parameter  of  the  existing 
VDGetDataRate  (III— 1997)  function. 
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VDSetDestinationPort 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Compressed  Source  Devices"  (V-2846) 

See  Also 

For  the  corresponding  get  function,  see  VDGetDataRate  (III— 1997). 


VDSetDestinationPort 


Sets  the  destination  port  for  a  video  digitizer. 

Vi deoDi gi ti zerError  VDSetDestinationPort  ( 
Vi deoDi gi ti zerComponent  ci  , 

CGraf Ptr  destPort  ) ; 


ci 

Specifies  the  video  digitizer  component  for  this  operation.  Applications  can 
obtain  this  reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent 
(11-1131). 

destPort 

A  pointer  to  a  CGraf  Port  (IV-2168)  structure. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 


VDSetDigitizerRect 


Sets  the  current  video  digitizer  rectangle. 

Vi deoDi gi ti zerError  VDSetDigitizerRect  ( 

Vi deoDi gi ti zerComponent  ci  , 

Rect  *di gi ti zerRect  ); 


III-2038 
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VDSetDigitizerUserlnterrupt 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
di gi ti zerRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  contains  the  size  and  location 
information  for  the  digitizer  rectangle.  The  coordinates  of  this  rectangle  must 
be  relative  to  the  maximum  source  rectangle.  In  addition,  the  digitizer  rectangle 
must  be  within  the  maximum  source  rectangle.  For  a  discussion  of  the 
relationship  between  these  rectangles,  see  "Video  Digitizer  Components"  in 
Inside  Macintosh:  QuickTime  Components  (listed  in  the  bibliography). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

All  video  digitizer  components  must  support  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Setting  Source  Characteristics"  (V-2843) 

See  Also 

For  the  corresponding  get  function,  see  VDGetDi  gi  ti  zerRect  (III— 1999). 


VDSetDigitizerUserlnterrupt 


Sets  custom  interrupt  functions. 

zerllserlnterrupt  ( 
ci  , 

fl ags , 

userlnterruptProc, 
ref con  ) ; 


Vi deoDi gi ti zerError  VDSetDi gi ti 
Vi deoDi gi ti zerComponent 
1  ong 

Vdi glntUPP 
1  ong 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

fl  ags 

Indicates  when  the  interrupt  function  is  to  be  called.  If  bit  0  is  set  to  1,  the  video 
digitizer  component  calls  the  custom  interrupt  procedure  each  time  it  starts  to 
display  an  even-line  field.  If  bit  1  is  set  to  1,  the  video  digitizer  component  calls 
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VDSetFieldPreference 


the  custom  interrupt  procedure  each  time  it  starts  to  display  an  odd-line  field. 
Applications  may  set  both  bits  to  1. 

userlnterruptProc 

A  Universal  Procedure  Pointer  to  a  VdiglntProc  (III— 2154)  callback. 
Applications  can  set  this  parameter  to  NI L  to  remove  a  VdiglntProc  callback. 

refcon 

Contains  parameter  data  that  is  appropriate  for  the  callback.  Use  this  parameter 
to  point  to  a  data  structure  containing  any  information  your  callback  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Video  Digitizer  Utilities"  (V-2853),  "Video  Digitizer 
Utilities"  (V-2853) 

VDSetFieldPreference 


Specifies  which  field  to  use  in  cases  where  the  vertical  scaling  is  less  than  half  size. 

Vi deoDi gi ti zerError  VDSetFieldPreference  ( 

Vi deoDi gi ti zerComponent  ci  , 

short  f  i  el  d FI  ag  ) ; 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 
f  i  el  d FI  ag 

A  constant  (see  below)  that  indicates  which  field  to  use. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

fieldFlag  Constants 

vdllseAny  Fi  el  d 

Digitizer  component  decides  which  field  to  use. 
vdllseOddFi  el  d 

Digitizer  uses  odd  field. 
vdllseEvenFi  el  d 

Digitizer  uses  even  field. 
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VDSetFrameRate 


Discussion 

All  video  digitizer  components  must  support  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui ckTi  meComponents  .  h 

Programming  summary:  "Video  Digitizer  Utilities"  (V-2853) 

See  Also 

For  the  corresponding  get  function,  see  VDGetFieldPreference  (ill-2001). 


VDSetFrameRate 


Indicates  an  application's  desired  frame  rate  to  the  video  digitizer. 

Vi deoDi gi ti zerError  VDSetFrameRate  ( 

VideoDigi ti zerComponent  ci  , 

Fixed  f ramesPerSecond  ); 


ci 

Identifies  the  application's  connection  to  the  video  digitizer  component.  An 
application  obtains  this  value  from  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 
f ramesPerSecond 

The  application's  desired  frame  rate.  Applications  may  set  this  parameter  to  0 
to  return  the  digitizer  to  its  default  frame  rate  (typically  29.97  frames  per 
second). 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Controlling  Digitization"  (V-2848) 


VDSetHue 

Sets  the  current  hue  value. 
VideoDi  gi  ti  zerError  VDSetFlue  ( 
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VDSetlnput 


Vi deoDi gi ti zerComponent  ci  , 

unsigned  short  *hue  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 
hue 

A  pointer  to  an  integer  that  contains  the  new  hue  value.  Hue  is  similar  to  the 
tint  control  on  a  television,  and  it  is  specified  in  degrees  with  complementary 
colors  set  180  degrees  apart  (red  is  0  degrees,  green  is  +120  degrees,  and  blue  is 
-120  degrees).  Video  digitizer  components  support  hue  values  that  range  from 
0  (-180  degrees  shift  in  hue)  to  65,535  (+179  degrees  shift  in  hue),  where  32,767 
represents  a  0  degree  shift  in  hue.  The  digitizer  component  returns  the  new 
value,  so  that  the  application  can  avoid  using  unsupported  values  in  future 
requests. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Analog  Video"  (V-2850) 

See  Also 

For  the  corresponding  get  function,  see  VDGetHue  (III— 2002). 


VDSetlnput 


Selects  the  input  video  source  for  a  video  digitizer  component. 

Vi deoDi gi ti zerError  VDSetlnput  ( 

Vi deoDi gi ti zerComponent  ci  , 

short  i nput  ) ; 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

i  nput 

The  input  video  source  for  this  request.  Video  digitizer  components  number 
video  sources  sequentially,  starting  at  0.  To  request  the  first  video  source,  an 
application  sets  this  parameter  to  0. 
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VDSetlnputColorSpaceMode 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

All  video  digitizer  components  must  support  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Selecting  an  Input  Source"  (V-2844) 

Related  Java  Methods 

qui ckti me . std . sg . Vi deoDi gi ti zer . set  Input ( ) 


See  Also 

For  the  corresponding  get  function,  see  VDGetlnput  (III— 2003). 


VDSetlnputColorSpaceMode 


Chooses  between  color  and  grayscale  digitized  video. 

Vi deoDi gi ti zerError  VDSetlnputColorSpaceMode  ( 
VideoDigi ti zerComponent  ci  , 

short  col orSpaceMode  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

col orSpaceMode 

Controls  color  digitization.  Set  to  0  for  grayscale,  1  for  color. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 
Programming  summary:  "Controlling  Color"  (V-2849) 

See  Also 

For  the  corresponding  get  function,  see  VDGetlnputCol  orSpaceMode  (III— 2004). 
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VDSetlnputGammaRecord 


VDSetlnputGammaRecord 


Changes  the  active  input  gamma  data  structure. 

Vi deoDi gi ti zerError  VDSetlnputGammaRecord  ( 

Vi deoDi gi ti zerComponent  ci  , 

VDGamRecPtr  i nputGammaPtr  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

i nputGammaPtr 

A  VDGammaRecord  (IV-2498)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

See  Also 

For  the  corresponding  get  function,  see  VDGetlnputGammaRecord  (III— 2006). 


VDSetlnputGammaValue 


Sets  the  gamma  values. 

Vi deoDi gi ti zerError  VDSetlnputGammaValue  ( 

Vi  deoDi gi ti zerComponent  ci  , 

Fixed  channell, 

Fixed  channel2, 

Fi xed  channel  3  ) ; 

ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  the  Component  Manager's  OpenComponent  function. 

channel  1 

The  gamma  value  for  the  red  component  of  the  input  video  signal, 
channel  2 

The  gamma  value  for  the  green  component  of  the  input  video  signal. 


III-2044 
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channel  3 

The  gamma  value  for  the  blue  component  of  the  input  video  signal. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

These  gamma  values  control  the  brightness  of  the  input  video  signal.  Your 
application  can  implement  special  color  effects,  such  as  turning  off  specific  color 
channels,  by  calling  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Controlling  Analog  Video"  (V-2850) 

See  Also 

For  the  corresponding  get  function,  see  VDGetlnputGammaVal  ue  (III— 2006). 


VD  SetlnputStandard 


Specifies  the  input  signaling  standard  to  digitize. 

Vi deoDi gi ti zerError  VDSetlnputStandard  ( 
VideoDigi ti zerComponent  ci  , 

short  i nputStandard  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

i nputStandard 

A  short  integer  (see  below)  that  identifies  the  input  signaling  standard. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

inputStandard  Constants 

ntscln 

Input  video  signal  to  digitize  is  in  NTSC  format, 
pal  In 

Input  video  signal  to  digitize  is  in  PAL  format, 
secamln 

Input  video  signal  to  digitize  is  in  SECAM  format. 
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VDSetKeyColor 


Discussion 

All  video  digitizer  components  must  support  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Selecting  an  Input  Source"  (V-2844) 


VDSetKeyColor 


Sets  the  key  color  for  video  digitizing. 

Vi deoDI gl tl zerError  VDSetKeyColor  ( 

Vi  deoDi gi ti zerComponent  ci  , 

1 ong  i ndex  ) ; 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

i  ndex 

The  new  key  color.  This  value  must  correspond  to  a  color  in  the  current  color 
lookup  table. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

All  video  digitizer  components  that  support  key  colors  must  support  this  function. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 

Programming  summary:  "Selectively  Displaying  Video"  (V-2852) 

See  Also 

For  the  corresponding  get  function,  see  VDGetKeyCol  or  (ill-2008). 


VDSetKeyColorRange 

Defines  a  key  color  range  for  video  digitizing. 


III-2046 
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VDSetMasterBlendLevel 


Vi deoDi gi ti zerError  VDSetKeyCol orRange  ( 
VideoDigi ti zerComponent  ci  , 

RGBColor  *minRGB, 

RGBColor  *maxRGB  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

mi  nRGB 

A  pointer  to  a  field  that  contains  the  lower  bound  of  the  key  color  range.  All 
colors  in  the  color  table  between  the  color  specified  by  the  mi  nRGB  parameter 
and  the  color  specified  by  the  maxRGB  parameter  are  considered  key  colors. 
maxRGB 

A  pointer  to  a  field  that  contains  the  upper  bound  of  the  key  color  range.  All 
colors  in  the  color  table  between  the  color  specified  by  the  mi  nRGB  parameter 
and  the  color  specified  by  the  maxRGB  parameter  are  considered  key  colors. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Selectively  Displaying  Video"  (V-2852) 

See  Also 

For  the  corresponding  get  function,  see  VDGetKeyCol  orRange  (III— 2009). 


VD  SetMasterBlendLe  vel 


Sets  the  blend  level  value  for  the  input  video  signal. 

Vi deoDi gi ti zerError  VDSetMasterBlendLevel  ( 
VideoDigi ti zerComponent  ci  , 

unsigned  short  *blendLevel  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

bl  endLevel 

A  pointer  to  a  field  that  specifies  the  new  master  blend  level.  Valid  values  range 
from  0  to  65,535,  where  0  corresponds  to  no  video  and  65,535  corresponds  to  all 
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VDSetPlayThruDestination 


video.  The  digitizer  component  returns  the  new  value  in  this  field,  so  your 
application  can  avoid  using  unsupported  values  in  future  requests. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Selectively  Displaying  Video"  (V-2852) 


VDSetPlayThruDestination 


Establishes  the  destination  settings  for  a  video  digitizer  component. 
Vi deoDi gi ti zerError  VDSetPlayThruDestination  ( 


Vi deoDi gi ti zerComponent  ci  , 
PixMapHandle  dest, 

RectPtr  destRect, 

Matri xRecordPtr  m, 

RgnHandl e  mask  ) ; 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

dest 

A  handle  to  the  destination  Pi  xMap  (IV-2332)  structure.  This  pixel  map  may  be 
in  the  video  frame  buffer  of  the  Macintosh  computer,  or  it  may  specify  an 
offscreen  buffer. 

destRect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  specifies  the  size  and  location  of  the 
video  destination.  This  rectangle  must  be  in  the  coordinate  system  of  the 
destination  Pi  xMap  (IV-2332)  structure  specified  by  the  dest  parameter, 
m 

A  pointer  toaMatrixRecord  (IV-2304)  structure  containing  the  transformation 
matrix  for  the  destination  video  image.  To  determine  the  capabilities  of  a  video 
digitizer  component,  you  can  call  VDGetDi  gi  ti  zerlnfo  (III— 1998)  in  your 
application. 


III-2048 
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VDSetPlayThruGlobalRect 


mask 

A  handle  to  aMac  Region  (IV-2303)  structure  that  defines  a  mask.  Applications 
can  use  masks  to  control  clipping  of  the  video  into  the  destination  rectangle. 
This  mask  region  is  defined  in  the  destination  coordinate  space. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

All  video  digitizer  components  must  support  this  function. 

Special  Considerations 

Applications  set  the  source  digitizer  rectangle  by  calling  V DSet D i  gi  ti  zer  Rect 
(III— 2038). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Setting  Video  Destinations"  (V-2845),  "Video  Clipping" 
(V-2853) 

See  Also 

For  the  corresponding  get  function,  see  VDGetPl  ayThruDesti  nati  on  (III— 2014). 


VD  SetPlayThruGlobalRect 


Establishes  the  destination  settings  for  a  video  digitizer  component  that  is  to 
digitize  into  a  global  rectangle. 

Vi  deoDi  gi  ti  zerError  VDSetPlayThruGlobalRect  ( 

VideoDigi ti zerComponent  ci  , 

GrafPtr  theWindow, 

Rect  *globalRect  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

theWi ndow 

A  pointer  to  the  destination  window, 
gl obal Rect 

A  pointer  to  a  Rect  (IV-2399)  structure  that  specifies  the  size  and  location  of  the 
video  destination.  This  rectangle  must  be  in  the  coordinate  system  of  the 
destination  window  specified  by  the  theWi  ndow  parameter. 
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YDS  etPlayThruOnOf  f 


function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

The  application  provides  the  desired  settings  as  parameters  to  this  function.  Not  all 
video  digitizer  components  support  global  rectangles. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Setting  Video  Destinations"  (V-2845),  "Video  Clipping" 
(V-2853) 

VDSetPlayThruOnOff 

Controls  continuous  digitization. 

Vi deoDi gi ti zerError  VDSetPlayThruOnOff  ( 

Vi deoDi gi ti zerComponent  ci , 

short  state  ) ; 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

state 

A  short  integer  (see  below)  that  specifies  whether  to  use  continuous 
digitization.  When  an  application  stops  continuous  digitization,  the  video 
digitizer  component  must  restore  its  a  1  p  h  a  channel,  blending  mask,  or  key  color 
settings  to  graphics  mode. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

state  Constants 

di gi ti zerOff 

Turns  off  continuous  digitization, 
di gi ti zerOn 

Turns  on  continuous  digitization. 

Discussion 

When  opened,  video  digitizer  components  are  always  set  to  off,  so  that  no 
digitization  is  taking  place.  Your  application  can  use  this  function  to  turn 
continuous  digitization  on  and  off. 
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Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui ckTi  meComponents  .  h 

Programming  summary:  "Controlling  Digitization"  (V-2848) 

See  Also 

Applications  can  request  single-frame  digitization  by  calling  VDGrabOneFrame 
(III — 2024)  or  VDGrabOneFrameAsync  (III — 2025). 


VDSetPLLFilterType 


Specifies  which  phase  locked  loop  (PLL)  is  to  be  active. 

Vi deoDi gi ti zerError  VDSetPLLFilterType  ( 

VideoDigi ti zerComponent  ci  , 
short  pllType  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

pi  1  Type 

Indicates  which  PLL  is  to  be  active.  Values  are  0  for  broadcast  mode  and  1  for 
videotape  recorder  mode. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Video  Digitizer  Utilities"  (V-2853) 

See  Also 

For  the  corresponding  get  function,  see  VDGetPLLFilterType  (III— 2015). 


VD  SetPref  erredlmageDimensions 

Sets  the  preferred  image  dimensions  for  a  video  digitizer. 

VideoDi gi ti zerError  VDSetPreferredlmageDimensions  ( 

Vi deoDi gi ti zerComponent  ci , 
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VDSetPreferredPacketSize 


long  width, 

1  ong  hei ght  ) ; 

ci 

Specifies  the  video  digitizer  component  for  this  operation.  Applications  can 
obtain  this  reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent 
(11-1131). 

wi  dth 

The  preferred  image  width, 
hei ght 

The  preferred  image  height. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

See  Also 

For  the  corresponding  get  function,  see  VDGetPreferredlmageDimensi  ons  (III— 2016). 


VDSetPreferredPacketSize 


Sets  the  preferred  packet  size  for  video  digitizing. 

Vi deoDi gi ti zerError  VDSetPreferredPacketSize  ( 

Vi  deoDi  gi ti zerComponent  ci  , 

long  preferredPacketSi zelnBytes  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 

preferredPacketSi zelnBytes 

The  preferred  packet  size  in  bytes. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

This  function  was  added  in  QuickTime  2.5  to  support  videoconferencing 
applications. 


III-2052 


Inside  QuickTime:  Functions  R-Z 


VDSetSaturation 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

Programming  summary:  "Controlling  Digitization"  (V-2848) 


VD  SetSaturation 


Sets  the  saturation  value. 

Vi deoDi gi ti zerError  VDSetSaturation  ( 
VideoDigi ti zerComponent  ci  , 

unsigned  short  *saturation  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 
saturati on 

A  pointer  to  an  integer  that  contains  the  new  saturation  value.  The  saturation 
value  controls  color  intensity.  For  example,  at  high  saturation  levels,  red 
appears  to  be  red;  at  low  saturation,  red  appears  as  pink.  Valid  saturation 
values  range  from  0  to  65,535,  where  0  is  the  minimum  saturation  value  and 
65,535  specifies  maximum  saturation.  The  video  digitizer  component  attempts 
to  set  the  saturation  value  to  the  value  specified  by  this  parameter.  The  digitizer 
component  returns  the  new  value,  so  that  the  application  can  avoid  using 
unsupported  values  in  future  requests. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Controlling  Analog  Video"  (V-2850) 

See  Also 

For  the  corresponding  get  function,  see  VDGetSaturation  (III— 2017). 


VD  SetSharpness 

Sets  the  sharpness  value. 

VideoDigi ti zerError  VDSetSharpness  ( 


Inside  QuickTime:  Functions  R-Z 


III-2053 


VDSetTimeBase 


Vi  deoDi gi ti zerComponent  ci  , 

unsigned  short  *sharpness  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 
sharpness 

A  pointer  to  an  integer  that  contains  the  new  sharpness  value.  The  sharpness 
value  ranges  from  0  to  65,535,  where  0  represents  no  sharpness  filtering  and 
65,535  represents  full  sharpness  filtering.  Higher  values  result  in  a  visual 
impression  of  increased  picture  sharpness.  The  video  digitizer  component 
attempts  to  set  the  sharpness  value  to  the  value  specified  by  this  parameter.  The 
digitizer  component  returns  the  new  value,  so  that  the  application  can  avoid 
using  unsupported  values  in  future  requests. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Analog  Video"  (V-2850) 

See  Also 

For  the  corresponding  get  function,  see  VDGetSharpness  (III— 2018). 


VDSetTimeBase 


Establishes  the  video  digitizer's  time  coordinate  system. 

Vi deoDi gi ti zerError  VDSetTimeBase  ( 

Vi deoDi gi ti zerComponent  ci  , 

TimeBase  t  ) ; 


ci 

Identifies  the  application's  connection  to  the  video  digitizer  component.  An 
application  obtains  this  value  from  OpenComponent  (11-1130)  or 
OpenDefaul  tComponent  (11-1131). 

t 

A  time  base  identifier.  You  can  get  this  value  from  NewT i  meBase  (11-1119). 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


III-2054 


Inside  QuickTime:  Functions  R-Z 


VDSetupBuffers 


Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui ckTi  meComponents  .  h 

Programming  summary:  "Controlling  Compressed  Source  Devices"  (V-2846) 


VD  SetupBuf  f  ers 


Defines  output  buffers  for  use  with  asynchronous  grabs. 

Vi deoDi gi ti zerError  VDSetupBuffers  ( 

VideoDigi ti zerComponent  ci  , 

Vdi gBuf f erRecLi stHandl e  bufferList  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131). 

buf f erLi st 

A  handle  to  a  Vdi  gBuf  f  erRecLi  st  (IV-2499)  structure.  Video  digitizer 
components  extract  information  about  the  spatial  characteristics  of  the  video 
destinations  from  these  buffers. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

If  you  are  developing  a  video  digitizer  component,  note  that  the  matrix  field  in  the 
buffer  list  structure  contains  a  pointer  to  the  Matri  xRecord  (IV-2304)  structure.  It  is 
your  responsibility  to  copy  that  matrix  structure. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

Programming  summary:  "Controlling  Digitization"  (V-2848) 

See  Also 

Applications  free  these  buffers  by  calling  VDRel  easeAsyncBuffers  (III— 2029). 


VD  SetWhiteLevel  V  alue 


Sets  the  white  level  value. 


Inside  QuickTime:  Functions  R-Z 


III-2055 


VDUseSafeBuffers 


Vi deoDi gi ti zerError  VDSetWhi teLevel  Val  ue  ( 

Vi deoDi gi ti zerComponent  ci  , 

unsigned  short  *whiteLevel  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent  (11-1131). 
whi teLevel 

A  pointer  to  an  integer  that  contains  the  new  white  level  value.  White  level 
values  range  from  0  to  65,535,  where  0  represents  the  minimum  white  value 
and  65,535  represents  the  maximum  white  value. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

Programming  summary:  "Controlling  Analog  Video"  (V-2850) 

See  Also 

For  the  corresponding  get  function,  see  VDGetWhi  teLevel  Val  ue  (III— 2024) . 


VDUseSafeBuffers 


Instructs  a  video  digitizer  to  use  protected  buffers. 

Vi deoDi gi ti zerError  VDUseSafeBuffers  ( 

Vi  deoDi gi ti zerComponent  ci  , 

Boolean  useSafeBuffers  ); 


ci 

Specifies  the  video  digitizer  component  for  this  operation.  Applications  can 
obtain  this  reference  from  OpenComponent  (11-1130)  or  OpenDefaul  tComponent 
(11-1131). 

useSafeBuffers 

Pass  TRUE  to  use  protected  buffers;  pass  FALSE  otherwise. 
function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 


III-2056 


Inside  QuickTime:  Functions  R-Z 


VDUseThisCLUT 


Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


VDUseThisCLUT 


Specifies  the  lookup  table  for  color  digitization. 

Vi deoDi gi ti zerError  VDUseThisCLUT  ( 

VideoDigi ti zerComponent  ci  , 

CTabHandle  col orTabl eHandl e  ); 


ci 

The  video  digitizer  component  for  the  request.  Applications  obtain  this 
reference  from  OpenComponent  (11-1130)  or  OpenDef aul  tComponent  (11-1131). 
col orTabl eHandl e 

A  handle  to  a  Col  orTabl  e  (IV-2210)  structure.  The  video  digitizer  component 
uses  the  color  table  referred  to  by  this  parameter. 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Discussion 

This  feature  is  useful  only  for  capturing  8-bit  color  video. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 
Programming  summary:  "Controlling  Color"  (V-2849) 


VideoMediaGetCodecParameter 


Undocumented 


Component Res ul t  VideoMedi a GetCodec Parameter 
MediaHandler  mh, 

CodecType  cType, 

OSType  parameterlD, 

Handle  outParameterData  ); 


( 


A  reference  to  a  video  media  handler.  You  obtain  this  reference  from 
GetMedi  aHandl  er  (1-432). 


Inside  QuickTime:  Functions  R-Z 


III-2057 


VideoMediaGetStallCount 


cType 

A  valid  codec  type  constant;  see  "Codec  Identifiers"  (IV-2655). 
parameterlD 

Undocumented 

outParameterData 

A  handle  to  the  returned  data. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es .  h 

See  Also 

For  the  corresponding  set  function,  see  Vi  deoMedi  aSetCodecParameter  (III— 2060). 


VideoMediaGetStallCount 


Undocumented 

ComponentResul t  VideoMediaGetStallCount  ( 
MediaHandler  mh, 

unsigned  long  *stalls  ); 


mh 

A  reference  to  a  video  media  handler.  You  obtain  this  reference  from 
GetMedi  aHandl  er  (1-432). 
stal 1 s 

The  number  of  stalls. 

function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 


III-2058 


Inside  QuickTime:  Functions  R-Z 


VideoMediaGetStatistics 


VideoMediaGetStatistics 


Returns  the  play-back  frame  rate  of  a  movie. 

ComponentResul t  VideoMediaGetStatistics  ( 
MediaHandier  mh  ); 


mh 

A  reference  to  a  video  media  handler.  You  obtain  this  reference  from 
GetMedi  aHandl  er  (1-432). 

function  result  The  average  frame  rate  since  the  last  time 

Vi deoMedi  aResetStati  sti  cs  (III— 2059)  was  called.  Because  of 
sampling  errors,  the  values  returned  from  this  function  are  accurate 
only  after  waiting  at  least  one  second  after  calling 
Vi deoMedi aResetStati sti cs. 

Discussion 

This  function  can  only  be  used  on  video  or  MPEG  media  handlers.  Because  not  all 
QuickTime  movies  have  a  constant  frame  rate,  the  results  of  this  call  can  be  difficult 
to  interpret  correctly.  For  this  reason,  the  results  of  this  function  should  not  be 
displayed  in  a  place  where  a  novice  user  is  likely  to  see  it. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

Programming  summary:  "Managing  the  Video  Frame  Playback  Rate"  (V-2745) 

Related  Java  Methods 

qui cktime . std .movi es .medi a . Vi deoMedi aHandl er . getStati sti cs ( ) 


VideoMediaResetStatistics 


Resets  the  video  media  handler's  counters  before  using  VideoMediaGetStatistics 
(III— 2059)  to  determine  the  frame  rate  of  a  movie. 

ComponentResul t  VideoMediaResetStatistics  ( 

MediaHandier  mh  ); 


A  reference  to  a  video  media  handler.  You  obtain  this  reference  from 
GetMedi  aHandl  er  (1-432). 


Inside  QuickTime:  Functions  R-Z 


III-2059 


VideoMediaSetCodecParameter 


function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMovi  es  Error 
(1-492)  and  GetMovi  esSti  ckyError  (IM94),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Special  Considerations 

This  call  can  only  be  used  on  video  or  MPEG  media  handlers. 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  Movi  es .  h 

Programming  summary:  "Managing  the  Video  Frame  Playback  Rate"  (V-2745) 

Related  Java  Methods 

quickti  me.  std.  mo  vies,  media.  VideoMediaHandler.resetStatisticsO 


VideoMediaSetCodecParameter 


Undocumented 


Component Res ul t  VideoMediaSetCodecParameter 


Medi aHandl er 

CodecType 

OSType 

1  ong 

voi  d 

1  ong 


mh , 

cType , 

parameterlD, 
parameterChangeSeed, 
*dataPtr , 
dataSi ze  ) ; 


( 


mh 

A  reference  to  a  video  media  handler.  You  obtain  this  reference  from 
GetMedi  aHandl  er  (1-432). 

cType 

A  valid  codec  type  constant;  see  "Codec  Identifiers"  (IV-2655). 
parameterlD 

Undocumented 

parameterChangeSeed 

Undocumented 

dataPtr 

A  pointer  to  the  data  to  be  set. 
dataSi ze 

The  size  of  the  data. 


III-2060 


Inside  QuickTime:  Functions  R-Z 


WinEventToMacEvent 


function  result  You  can  access  Movie  Toolbox  error  returns  through  GetMoviesError 
(1-492)  and  GetMovi esSti  ckyError  (1-494),  as  well  as  in  the  function 
result.  See  "Error  Codes"  (IV-2663). 

Version  Notes 

Introduced  in  QuickTime  4. 

Programming  Info 

C  interface  file:  Movi  es  .  h 

See  Also 

For  the  corresponding  get  function,  see  Vi  deoMedi  aGetCodecParameter  (III— 2057). 


W  inEventT  oMacEvent 


Converts  a  Windows  event  message  into  a  Macintosh  event  record. 

long  WinEventToMacEvent  ( 
void  *winMsg, 

EventRecord  *macEvent  ); 

wi nMsg 

A  pointer  to  a  Windows  event  message. 
macEvent 

A  pointer  to  an  EventRecord  (IV-2246)  structure. 
function  result  Undocumented 

Discussion 

The  following  sample  code  shows  how  to  convert  Windows  messages  to  Macintosh 
events,  then  pass  those  events  to  the  QuickTime  movie  controller: 

//  WinEventToMacEvent  coding  example 
//  See  “Discovering  QuickTime,”  page  240 

Movi eControl 1 er  me;  //  Movie  controller  for  movie 

LRESULT  CALLBACK  WndProc 

(HWND  hwnd,  //  Handle  to  window 

UINT  iMsg,  //  Message  type 


Inside  QuickTime:  Functions  R-Z 


III-2061 


XMLParseAddAttribute 


WPARAM 

wParam, 

// 

Message-dependent  parameter 

LPARAM 

1 Param) 

// 

Message-dependent  parameter 

MSG 

msg ; 

// 

Windows  message  structure 

EventRecord 

er ; 

// 

Macintosh  event  record 

DWORD 

dwPos ; 

// 

Mouse  coordinates  of  message 

msg . hwnd 

=  hwnd; 

// 

Window  handle 

msg. message 

=  iMsg; 

// 

Message  type 

msg.wParam 

=  wParam; 

// 

Word-length  parameter 

msg.l Param 

=  1 Param; 

// 

Long-word  parameter 

msg. time  = 

GetMessageTimet ) ; 

// 

Get  time  of  message 

dwPos  =  GetMessagePos ( ) ; 

// 

Get  mouse  position 

msg.pt.x  = 

LOWORDt dwPos )  ; 

// 

Extract  x  coordinate 

msg . pt .y  = 

HIWORDt dwPos )  ; 

// 

Extract  y  coordinate 

WinEventToMacEvent(&msg,  &er); 

// 

Convert  to  event 

MCIsPl ayerEventtmc ,  &er); 

// 

Pass  event  to  QuickTime 

switch  ( i Ms g )  { 

// 

Dispatch  on  message  type 

...  //  Handle  message  according  to  type 

}  //  end  switch  ( i Ms g ) 

}  //  end  WndProc 

Version  Notes 

Introduced  in  QuickTime  3  or  earlier. 

Programming  Info 

C  interface  file:  QTML.  h 


XMLParseAddAttribute 


Undocumented 


III-2062 


Inside  QuickTime:  Functions  R-Z 


XMLParseAddAttributeAndValue 


ComponentResul t  XMLParseAddAttribute  ( 


Componentlnstance 

UInt32 

UInt32 

char 

UInt32 


aParser, 
elementID, 
nameSpacelD, 
*attri buteName , 
*attributeID  ); 


aParser 

Undocumented 

el ementID 

Undocumented 

nameSpacelD 

Undocumented 

attri buteName 

Undocumented 

attri butelD 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


XMLParseAddAttribute  And  V  alue 


Undocumented 


ComponentResul t  XMLParseAddAttributeAndValue  ( 


Componentlnstance 

UInt32 

UInt32 

char 

UInt32 

UInt32 

voi  d 


aParser, 
el ementID, 
nameSpacelD, 

*attri buteName , 
*attributeID, 
attri  buteVal  ueKi  nd  , 

*attri buteVal ueKi ndlnfo  ); 


aParser 

Undocumented 


Inside  QuickTime:  Functions  R-Z 


III-2063 


XMLParseAddAttributeValueKind 


el ementID 

Undocumented 

nameSpacelD 

Undocumented 
attri buteName 

Undocumented 
attri butelD 

Undocumented 
attri but eVal ueKi nd 
Undocumented 
attri but eVal ueKi nd Info 
Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


XMLParse  Add  Attribute  V  alueKind 


Undocumented 

rseAddAttri buteVal  ueKi  nd  ( 
aParser , 
elementID, 
attributelD, 
attri buteVal ueKi  nd , 

*attri buteVal ueKi ndlnfo  ); 

aParser 

Undocumented 
el ementID 

Undocumented 
attri butelD 

Undocumented 
attri buteVal ueKi nd 
Undocumented 


ComponentResul t  XMLPa 
Componentlnstance 
UInt32 
UInt32 
UInt32 
voi  d 


III-2064 


Inside  QuickTime:  Functions  R-Z 


XMLParseAddElement 


attri buteVal ueKi ndlnfo 
Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 


XMLParseAddElement 


Undocumented 


ComponentResul t  XMLParseAddElement  ( 
Componentlnstance  aParser, 
char 


UInt32 
UInt32 
1  ong 


*el  ementName 
nameSpacelD, 
*elementID, 
el  ementFl  ags 


): 


aParser 

Undocumented 
el ementName 

Undocumented 

nameSpacelD 

Undocumented 
el ementID 

Undocumented 
el  ementFl  ags 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 


Inside  QuickTime:  Functions  R-Z 


III-2065 


XMLParseAddMultipleAttributes 


XMLParseAddMultipleAttributes 

Undocumented 


Component Res ul t  XMLParseAddMul tipi eAttri butes 
Componentlnstance  aParser, 


UInt32 

UInt32 

char 

UInt32 


el ementID , 
*nameSpaceIDs , 
*attri buteNames , 
*attri butelDs  ); 


( 


aParser 

Undocumented 

el ementID 

Undocumented 

nameSpacelDs 

Undocumented 
attri buteNames 
Undocumented 
attri butelDs 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


XMLParseAddMultipleAttributes  AndValues 


Undocumented 

ComponentResul t  XMLParseAddMul ti pi eAttri butesAndVal ues  ( 
Componentlnstance  aParser, 

UInt32  elementID, 

UInt32  *nameSpaceIDs , 

char  *attri buteNames , 

UInt32  *attri butelDs , 

UInt32  *attri buteVal ueKi nds , 

void  **attri buteVal ueKi ndlnfos  ); 


III-2066 


Inside  QuickTime:  Functions  R-Z 


XMLParseAddNameSpace 


aParser 

Undocumented 
el ementID 

Undocumented 

nameSpacelDs 

Undocumented 
attri buteNames 
Undocumented 
attri butelDs 

Undocumented 
attri buteVal ueKi nds 
Undocumented 
attri buteVal ueKi nd Infos 
Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


XMLParseAddNameSpace 


Undocumented 

ComponentResul t  XMLParseAddNameSpace  ( 

Componentlnstance  aParser, 

char  *nameSpaceURL, 

UInt32  *nameSpaceID  ); 

aParser 

Undocumented 

nameSpaceURL 

Undocumented 

nameSpacelD 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Inside  QuickTime:  Functions  R-Z 


III-2067 


XMLParseDataRef 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


XMLParseDataRef 


Undocumented 


ComponentResul t  XMLParseDataRef  ( 
Componentlnstance  aParser, 
Handle  dataRef, 

OSType  dataRefType, 

long  parseFlags, 

XMLDoc  *document  ) ; 


aParser 

Undocumented 

dataRef 

Undocumented 

dataRefType 

Undocumented 
parseFl  ags 

Undocumented 

document 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 


XMLParseDisposeXMLDoc 


Undocumented 

ComponentResul t  XMLParseDisposeXMLDoc  ( 
Componentlnstance  aParser, 


III-2068 


Inside  QuickTime:  Functions  R-Z 


XMLParseFile 


XMLDoc  document  ); 

aParser 

Undocumented 

document 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 

XMLParseFile 

Undocumented 

ComponentResul t  XMLParseFile  ( 

Componentlnstance  aParser, 

ConstFSSpecPtr  fileSpec, 

long  parseFlags, 

XMLDoc  *document  ); 

aParser 

Undocumented 
f i 1 eSpec 

Undocumented 
parseFl  ags 

Undocumented 

document 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 


Inside  QuickTime:  Functions  R-Z 
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XMLParseGetDetailedParseError 


XMLParseGetDetailedParseError 


Undocumented 

ComponentResul t  XMLParseGetDetailedParseError  ( 

Componentlnstance  aParser, 

long  *errorLine, 

Stri ngPtr  errDesc  ) ; 

aParser 

Undocumented 
errorLi  ne 

Undocumented 

errDesc 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


XMLParseSetCharDataHandler 

Undocumented 

ComponentResul t  XMLParseSetCharDataHandler  ( 

Componentlnstance  aParser, 

CharDataHandl erUPP  charData  ); 

aParser 

Undocumented 

charData 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 
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XMLParseSetCommentHandler 


XMLParseSetCommentHandler 

Undocumented 

ComponentResul t  XMLParseSetCommentHandler  ( 

Componentlnstance  aParser, 

CommentHandl  erllPP  comment  ); 

aParser 

Undocumented 

comment 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


XMLParseSetEndDocumentHandler 

Undocumented 

ComponentResul t  XMLParseSetEndDocumentHandler  ( 

Componentlnstance  aParser, 

EndDocumentHandl  erllPP  endDocument  ); 

aParser 

Undocumented 

endDocument 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 


Inside  QuickTime:  Functions  R-Z 
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XMLParseSetEndElementHandler 


XMLParseSetEndElementHandler 

Undocumented 

ComponentResul t  XMLParseSetEndElementHandler  ( 

Componentlnstance  aParser, 

EndEl ementHandl erUPP  endElement  ); 

aParser 

Undocumented 
endEl ement 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


XMLParseSetEventParseRefCon 

Undocumented 

ComponentResul t  XMLParseSetEventParseRefCon  ( 

Componentlnstance  aParser, 

1 ong  refcon  ) ; 

aParser 

Undocumented 

refcon 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 
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XMLParseSetOffsetAndLimit 

Undocumented 

ComponentResul t  XMLParseSetOffsetAndLimit  ( 

Componentlnstance  aParser, 

UInt32  offset, 

UInt32  limit  ); 

aParser 

Undocumented 

offset 

Undocumented 
1  i  mi  t 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


XMLParseSetPreprocessInstructionHandler 

Undocumented 

ComponentResul t  XMLParseSetPreprocessInstructionHandl er  ( 
Componentlnstance  aParser, 

Preprocess  I nstructionHandlerUPP  preprocess  Instruction  ) ; 

aParser 

Undocumented 

preprocesslnstruction 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 


Inside  QuickTime:  Functions  R-Z 
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XMLParseSetStartDocumentHandler 

Undocumented 

ComponentResul t  XMLParseSetStartDocumentHandl  er  ( 

Componentlnstance  aParser, 

StartDocumentHandl  erllPP  startDocument  ); 

aParser 

Undocumented 

startDocument 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


XMLParseSetStartElementHandler 

Undocumented 

ComponentResul t  XMLParseSetStartElementHandler  ( 

Componentlnstance  aParser, 

StartEl  ementHandl  erLIPP  startElement  ); 

aParser 

Undocumented 

startEl ement 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Returns  noErr  if  there  is  no  error. 

Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i  meComponents .  h 
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Callbacks 


ActionsProc 


Action  callback  for  a  media  handler. 


typedef  OSErr  (*ActionsProcPtr)  (void  *refcon.  Track  targetTrack, 
long  targetRefCon ,  QTEventRecordPtr  theEvent); 


//  Declaration  of  a  typical  application-defined  function 
OSErr  MyActi onsProc  ( 

void  *refcon 

Track  targetTrack 

long  targetRefCon 

QTEventRecordPtr  theEvent  ); 


ref con 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 
targetTrack 

The  track  in  which  to  perform  the  actions. 
targetRefCon 

A  reference  constant  for  the  target  track. 
theEvent 

Pointer  to  a  QTEventRecord  (IV-2353)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 


CLB 


See  Also 

See  the  Medi  aSetActi  onsCal  1  back  (11-888)  and  NewActi  onsLIPP  (11-1053)  functions. 


Activate  YDProc 

Controls  the  highlighting  of  dialog  items  that  are  defined  by  your  application  and 
that  can  receive  keyboard  input. 

typedef  void  (*Acti vateYDProcPtr)  (DialogPtr  theDialog,  short  itemNo, 
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Callbacks 


Activate  YDProc 


Boolean  activating,  void  *yourDataPtr ) ; 

//  Declaration  of  a  typical  appl i cati on -def i ned  function 
void  MyActi vateYDProc  ( 

DialogPtr  theDialog 

short  itemNo 

Boolean  activating 

void  *yourDataPtr  ); 

theDi al og 

A  pointer  to  a  dialog  box. 
i temNo 

An  item  number  in  the  dialog  box. 
acti vati ng 

A  Bool  ean  value  that  specifies  whether  the  field  is  being  activated  (TRUE)  or 
deactivated  (FALSE). 

yourDataPtr 

A  pointer  to  your  own  data. 

Discussion 

The  two  standard  keyboard-input  fields  are  the  filename  field  (present  only  in  Save 
dialog  boxes)  and  the  display  list.  Unless  you  override  it  through  your  own  dialog 
hook  function,  the  Standard  File  Package  handles  the  highlighting  of  its  own  items 
and  TextEdit  fields.  When  the  user  changes  the  keyboard  target  by  pressing  the 
mouse  button  or  the  Tab  key,  the  Standard  File  Package  calls  your  Acti  vateYDProc 
callback  twice:  the  first  call  specifies  which  field  is  being  deactivated,  and  the 
second  specifies  which  field  is  being  activated. 

Your  application  is  responsible  for  removing  the  highlighting  when  one  of  its  fields 
becomes  inactive  and  for  adding  the  highlighting  when  one  of  its  fields  becomes 
active.  The  Standard  File  Package  can  handle  the  highlighting  of  all  TextEdit  fields, 
even  those  defined  by  your  application.  You  can  also  use  your  Acti  vateYDProc 
callback  to  keep  track  of  which  field  is  receiving  keyboard  input,  if  your  application 
needs  that  information. 

Special  Considerations 

Ordinarily,  you  need  to  supply  an  Acti  vateYDProc  callback  only  if  your  application 
builds  a  list  from  which  the  user  can  select  entries.  The  Standard  File  Package 
supplies  the  activation  procedure  for  the  file  display  list  and  for  all  TextEdit  fields. 
You  can  also  use  your  Acti  vateYDProc  callback  to  keep  track  of  which  field  is 
receiving  keyboard  input,  if  your  application  needs  that  information 
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ComponentMPWorkFunctionProc 


See  Also 

See  the  CustomGetFi  1  ePrevi  ew  (1-163)  function.  For  information  about  dialog  boxes 
and  the  Standard  File  Package,  see  Inside  Macintosh:  Files  (listed  in  the 

bibliography). 


ComponentMPW  orkFunctionProc 

Undocumented 

typedef  ComponentResul t  (*ComponentMPWorkFuncti onProcPtr) 

(void  *gl  obal  RefCon  ,  ComponentMPWorkFuncti  onFleaderRecordPtr  header); 

//  Declaration  of  a  typical  application-defined  function 
ComponentResul t  MyComponentMPWorkFuncti onProc  ( 

void  *gl  obal  RefCon 

ComponentMPWorkFuncti  onFleaderRecordPtr  header  ); 

gl  obal RefCon 

Undocumented 

header 

Pointer  to  a  ComponentMPWorkFuncti onHeaderRecord  (IV-2215)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 


See  Also 

See  the  ImageCodecGetBaseMPWorkFuncti  on  (11-709)  and 
NewComponentMPWorkFuncti  onUPP  (11-1056)  functions. 


CLB 


ComponentRoutineProc 


Undocumented 

typedef  ComponentResul t  (*ComponentRoutineProcPtr)  (ComponentParameters  *cp, 
Handle  componentStorage) ; 

//  Declaration  of  a  typical  application-defined  function 
ComponentResul t  MyComponentRouti neProc  ( 

ComponentParameters  *cp 

Handle  componentStorage  ); 


cp 

Undocumented 
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DataHCompletionProc 


componentStorage 

Undocumented 


function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 


See  Also 

Seethe  Regi sterComponent  (III — 1451)  and  NewComponentRouti neLIPP  (11-1057) 
functions. 


DataHCompletionProc 

Called  upon  completion  of  a  read  or  write  operation. 

typedef  void  (*DataHCompl eti onProcPtr )  (Ptr  request,  long  refcon,  OSErr  err); 

//  Declaration  of  a  typical  appl i cati on -def i ned  function 
void  MyDataHCompl eti onProc  ( 

Ptr  request 

long  refcon 

OSErr  err  ) ; 

request 

Specifies  a  pointer  to  the  data  that  was  associated  with  the  read  request 
DataHSchedul  eData  (1-220)  or  write  request  DataHWrite  (1-232).  The  client 
program  uses  this  pointer  to  determine  which  request  has  completed, 
refcon 

A  reference  constant  that  the  client  program  supplied  to  your  data  handler 
component  when  it  made  the  original  request. 

err 

Indicates  the  success  or  failure  of  the  operation.  If  the  operation  succeeded,  set 
this  parameter  to  0.  Otherwise,  specify  an  appropriate  error  code. 

Discussion 

Data  handler  completion  functions  are  guaranteed  to  be  called  at  non-interrupt 
time.  This  means  that  you  can  safely  call  functions  that  are  not  interrupt-safe,  such 
as  DataHSchedul  eData  (1-220),  from  within  a  completion  function. 

See  Also 

See  the  DataHGetFi  1  eSi  zeAsync  (1-196),  DataHReadAsync  (1-217),  DataHSchedul  eData 
(1-220),  DataHWri  te  (1-232),  and  NewDataHCompl  eti  onllPP  (11-1057)  functions. 
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DlgHookProc 


Handles  item  selections  in  a  dialog  box. 

typedef  short  (*D1 gHookProcPtr)  (short  item,  DialogPtr  theDialog); 

//  Declaration  of  a  typical  application-defined  function 
short  MyDl gHookProc  ( 
short  item 

DialogPtr  theDialog  ); 


i  tern 

The  item  number  (see  below). 
theDi al og 

A  pointer  to  the  dialog  record. 


function  result  Set  equal  to  the  item  number  if  your  dialog  hook  function  does  not 
handle  a  selection. 


item  Constants 

sf ItemOpenButton 

Save  or  Open  button, 
sf ItemCancel Button 
Cancel  button, 
sf ItemBal 1 oonHel p 
Balloon  Help, 
sf ItemVol umeUser 

Volume  icon  and  name, 
sf ItemEjectButton 
Eject  button, 
sf ItemDesktopButton 
Desktop  button, 
sf  ItemFi  1  eLi  stUser 
Display  list, 
sf ItemPopUpMenuUser 

Directory  pop-up  menu, 
sf ItemDi vi derLi nePi ct 

Dividing  line  between  buttons, 
sf ItemFi 1 eNameTextEdi t 
Filename  field. 


CLB 
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Callbacks 


DlgHookYDProc 


sf ItemPromptStati cText 

Filename  prompt  text  area. 
sfltemNewFoldertlser 
New  Folder  button. 

Discussion 

Your  dialog  hook  function  returns  as  its  function  result  an  integer  that  is  either  the 
item  number  passed  to  it  or  some  other  item  number.  If  it  returns  one  of  the  item 
numbers  in  the  list  of  constants  (see  above),  the  Standard  File  Package  handles  the 
selected  item  as  described  in  Inside  Macintosh:  Files  (listed  in  the  bibliography).  If 
your  dialog  hook  function  does  not  handle  a  selection,  it  should  pass  the  item 
number  back  to  the  Standard  File  Package  for  processing  by  setting  its  return  value 
equal  to  the  item  number. 

See  Also 

Seethe  SFGetFi  1  ePreview  (III— 1674)  and  SFPGetFi 1 ePrevi  ew  (III— 1676)  functions. 


DlgHookYDProc 


Handles  user  selections  in  a  dialog  box. 

typedef  short  (*DlgHookYDProcPtr)  (short  item,  DialogPtr  theDialog, 
voi d  *yourDataPtr ) ; 

//  Declaration  of  a  typical  application-defined  function 
short  MyDl gHookYDProc  ( 
short  item 

DialogPtr  theDialog 

void  *yourDataPtr  ); 


i  tern 

The  dialog  item  number  selected  (see  below). 
theDi al og 

A  pointer  to  the  dialog  record. 
yourDataPtr 

A  pointer  to  the  data  received  from  your  application,  if  any. 


function  result  Set  equal  to  the  item  number  if  your  dialog  hook  function  does  not 
handle  a  selection. 


item  Constants 

sf ItemOpenButton 

Save  or  Open  button. 
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DlgHookYDProc 


sf ItemCancel Button 
Cancel  button, 
sf ItemBal 1 oonHel p 
Balloon  Help, 
sf ItemVol umeUser 

Volume  icon  and  name, 
sf ItemEjectButton 
Eject  button, 
sf ItemDesktopButton 
Desktop  button, 
sf  ItemFi  1  eLi  stUser 
Display  list, 
sf ItemPopUpMenuUser 

Directory  pop-up  menu, 
sf ItemDi vi derLi nePi ct 

Dividing  line  between  buttons, 
sf ItemFi 1 eNameTextEdi t 
Filename  field, 
sf ItemPromptStati cText 

Filename  prompt  text  area, 
sf  ItemNewFol  derllser 
New  Folder  button. 

Discussion 

Your  dialog  hook  function  returns  as  its  function  result  an  integer  that  is  either  the 
item  number  passed  to  it  or  some  other  item  number.  If  it  returns  one  of  the  item 
numbers  in  the  list  of  constants  (see  above),  the  Standard  File  Package  handles  the 
selected  item  as  described  in  Inside  Macintosh:  Files  (listed  in  the  bibliography).  If 
your  dialog  hook  function  does  not  handle  a  selection,  it  should  pass  the  item 
number  back  to  the  Standard  File  Package  for  processing  by  setting  its  return  value 
equal  to  the  item  number. 

See  Also 

Seethe  CustomGetFi  1  ePrevi ew  (1-163)  function. 
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Callbacks 


DoMCActionProc 


DoMCActionProc 


Undocumented 

typedef  OSErr  (*DoMCActi onProcPtr)  (void  *refcon,  short  action,  void  *params, 
Bool ean  *handl ed ) ; 

//  Declaration  of  a  typical  appl  i  cati  on -def  i  ned  function 
OSErr  MyDoMCActi onProc  ( 
void  *refcon 

short  action 

void  *params 

Bool ean  *handl ed  ) ; 

refcon 

Pointer  to  a  reference  constant  that  the  client  code  supplies  to  your  callback. 
You  can  use  this  reference  to  point  to  a  data  structure  containing  any 
information  your  callback  needs. 

acti on 

Undocumented 

params 

Undocumented 
handl ed 

A  pointer  to  a  Bool  ean  in  which  you  put  TRUE  if  the  action  was  handled,  FALSE 
otherwise. 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 


See  Also 

See  the  MCGetDoActi onsProc  (11-811),  Medi  aSetDoMCActi onCal  1  back  (11-892), 

Movi  eMedi  aGetDoMCActi  onCal  1  back  (11-970),  Movi  eMedi  aGetChi  1  dDoMCActi  onCal  1  back 
(11-966),  and  NewDoMCActi  onUPP  (11-1058)  functions. 


FileFilterProc 

Determines  which  files  the  user  can  open. 

typedef  Boolean  (*Fi 1 eFi 1 terProcPtr )  (CInfoPBPtr  pb); 

//  Declaration  of  a  typical  appl i cati on -def i ned  function 
Boolean  My Fi  1  eFi  1  terProc  ( 

CInfoPBPtr  pb  )  ; 
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FileFilterYDProc 


pb 

A  pointer  to  a  catalog  information  parameter  block.  See  Chapter  2  of  Inside 
Macintosh:  Files  (listed  in  the  bibliography). 

function  result  TRUE  suppresses  display  of  the  filename,  and  a  value  of  FALSE  allows 
the  display. 

Discussion 

When  QuickTime  is  displaying  the  contents  of  a  volume  or  folder,  it  checks  the  file 
type  of  each  file  and  filters  out  files  whose  types  do  not  match  your  application's 
specifications.  If  your  application  also  supplies  a  file  filter  function,  the  Standard 
File  Package  calls  that  function  each  time  it  identifies  a  file  of  an  acceptable  type. 
When  your  file  filter  function  is  called,  it  is  passed,  in  the  pb  parameter,  a  pointer  to 
a  catalog  information  parameter  block.  See  Inside  Macintosh:  Files  (listed  in  the 
bibliography)  for  a  description  of  the  fields  of  this  parameter  block.  Your  function 
evaluates  the  catalog  information  parameter  block  and  returns  a  Bool  ean  value  that 
determines  whether  the  file  is  filtered  (that  is,  a  value  of  TRUE  suppresses  display  of 
the  filename,  and  a  value  of  FALSE  allows  the  display).  If  you  do  not  supply  a  file 
filter  function,  the  Standard  File  Package  displays  all  files  of  the  specified  types. 

See  Also 

See  the  StandardGetFi  1  ePrevi  ew  (III — 1910)  and  SFPGetFi  1  ePrevi  ew  (III — 1676) 
functions. 


FileFilterYDProc 


Determines  which  files  the  user  can  open,  with  a  pointer  to  application-defined 
data. 

typedef  Boolean  (*Fi 1 eFi 1 terYDProcPtr)  (CInfoPBPtr  pb,  void  *yourDataPtr) ; 

//  Declaration  of  a  typical  application-defined  function 
Boolean  MyFi  1  eFi  1  terYDProc  ( 

CInfoPBPtr  pb 

void  *yourDataPtr  ); 

pb 

A  pointer  to  a  catalog  information  parameter  block.  See  Chapter  2  of  Inside 
Macintosh:  Files  (listed  in  the  bibliography). 
yourDataPtr 

A  pointer  to  the  data  received  from  your  application,  if  any. 
function  result  TRUE  suppresses  display  of  the  filename,  and  a  value  of  FALSE  allows 
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FilePlayCompletionProc 


the  display. 

Discussion 

When  QuickTime  is  displaying  the  contents  of  a  volume  or  folder,  it  checks  the  file 
type  of  each  file  and  filters  out  files  whose  types  do  not  match  your  application's 
specifications.  If  your  application  also  supplies  a  file  filter  function,  the  Standard 
File  Package  calls  that  function  each  time  it  identifies  a  file  of  an  acceptable  type. 
When  your  file  filter  function  is  called,  it  is  passed,  in  the  pb  parameter,  a  pointer  to 
a  catalog  information  parameter  block.  See  Inside  Macintosh:  Files  (listed  in  the 
bibliography)  for  a  description  of  the  fields  of  this  parameter  block.  Your  function 
evaluates  the  catalog  information  parameter  block  and  returns  a  Bool  ea  n  value  that 
determines  whether  the  file  is  filtered  (that  is,  a  value  of  TRUE  suppresses  display  of 
the  filename,  and  a  value  of  FALSE  allows  the  display).  If  you  do  not  supply  a  file 
filter  function,  the  Standard  File  Package  displays  all  files  of  the  specified  types. 

See  Also 

Seethe  CustomGetFi  1  ePreview  (1-163)  function. 


FilePlayCompletionProc 


Obsolete. 

typedef  void  (*Fi 1 ePl ayCompl eti onProcPtr )  ( SndChannel Ptr  chan); 

//  Declaration  of  a  typical  application-defined  function 
void  My Fi 1 ePl ayCompl eti onProc  ( 

SndChannel Ptr  chan  ) ; 


chan 

A  pointer  to  the  sound  channel. 


GetMissingComponentResourceProc 


Returns  a  specified  component  resource. 

typedef  OSErr  (*GetMi ssi ngComponentResourceProcPtr )  (Component  c, 
OSType  resType,  short  resID,  void  *refCon,  Handle  *resource); 

//  Declaration  of  a  typical  application-defined  function 
OSErr  MyGetMi ssi ngComponentResourceProc  ( 

Component  c 

OSType  resType 

short  resID 
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void  *refCon 

Handle  *resource  ); 


A  component  identifier  that  specifies  the  component  containing  the  resource. 
The  caller  obtains  this  identifier  from  Fi  ndNextComponent  (1-360).  If  the  caller 
registers  a  component,  it  can  also  obtain  a  component  identifier  from 
Regi  sterComponent  (III — 1451)  or  Regi  sterComponentResource  (III — 1453). 
resType 

A  Mac  OS  resource  type. 
resID 

The  resource  ID. 

refCon 

Pointer  to  a  reference  constant  that  the  client  code  supplies  to  your  callback. 
You  can  use  this  reference  to  point  to  a  data  structure  containing  any 
information  your  callback  needs, 
resource 

On  return,  a  pointer  to  a  handle  to  the  resource. 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 


See  Also 

See  the  GetComponentPubl  i  cResourceLi  st  (1-393)  and 
NewGetMi  ssi  ngComponentResourcellPP  (11-1059)  functions. 


GetMovieProc 


CLB 


Provides  movie  data  to  the  Movie  Toolbox. 

typedef  OSErr  (*GetMovieProcPtr)  (long  offset,  long  size,  void  *dataPtr, 
void  *refCon); 

//  Declaration  of  a  typical  application-defined  function 
OSErr  MyGetMovi eProc  ( 


1  ong 

offset 

1  ong 

si  ze 

voi  d 

*dataPtr 

voi  d 

*refCon 
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offset 

Specifies  the  offset  into  the  movie  resource  (not  the  movie  file).  This  is  the 
location  from  which  your  function  retrieves  the  movie  data. 

si  ze 

Specifies  the  amount  of  data  requested  by  the  toolbox,  in  bytes. 
dataPtr 

Specifies  the  destination  for  the  movie  data. 
refCon 

Contains  a  reference  constant  (defined  as  a  void  pointer).  This  is  the  same  value 
you  provided  to  the  toolbox  when  you  called  NewMovi  eFromUserProc  (11-1087). 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 

Discussion 

Normally,  when  a  movie  is  loaded  from  a  file  (for  example,  by  means  of  the 
NewMovi  eFromFi  1  e  function),  the  toolbox  uses  that  file  as  the  default  data  reference. 
Since  NewMovi  eFromUserProc  (11-1087)  does  not  require  a  file  specification,  your 
application  should  specify  the  file  to  be  used  as  the  default  data  reference  using  the 
defaul  tDataRef  and  dataRefType  parameters. 

Special  Considerations 

The  toolbox  automatically  sets  the  movie's  graphics  world  based  upon  the  current 
graphics  port.  Be  sure  that  your  application's  graphics  world  is  valid  before  you  call 
this  function. 

See  Also 

Seethe  NewMovi  eFromUserProc  (11-1087)  and  NewGetMovi  eUPP  (11-1060)  functions. 


ICMAlignmentProc 


Provides  an  alignment  behavior  for  windows  based  on  the  screen's  bit  depth. 

typedef  void  (*ICMA1 i gnmentProcPtr )  (Rect  *rp,  long  refcon); 

//  Declaration  of  a  typical  application-defined  function 
void  My ICMA1 i gnmentProc  ( 

Rect  *rp 

1 ong  refcon  ) ; 
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rp 

Contains  a  pointer  to  a  rectangle  that  has  already  been  aligned  with  a  default 
alignment  function, 
ref con 

Contains  a  reference  constant  value  for  use  by  your  alignment  function.  Your 
application  specifies  the  value  of  this  reference  constant  in  the  alignment 
function  structure  you  pass  to  the  Image  Compression  Manager. 

See  Also 

See  the  ICMA1  i  gnmentProcRecord  (IV-2278)  structure  and  the  A1  i  gn Screen Rect  (1-46), 
A1  i  gnWi  ndow  (I -47),  DragAl  i  gnedGray  Rgn  (1-304),  DragAl  i  gnedWi  ndow  (1-306),  and 
similar  functions. 


ICMCompletionProc 

Called  by  a  compressor  component  upon  completion  of  an  asynchronous  operation. 

typedef  void  (*ICMCompl eti onProcPtr)  (OSErr  result,  short  flags, 
long  refcon); 

//  Declaration  of  a  typical  application-defined  function 
void  My ICMCompl eti onProc  ( 

OSErr  result 

short  flags 

long  refcon  ); 

resul t 

Indicator  of  success  of  current  operation, 
fl  ags 

Contains  flags  (see  below)  that  indicate  which  part  of  the  operation  is  complete. 
Note  that  more  than  one  of  the  flags  may  be  set  to  1. 
refcon 

Contains  a  reference  constant  value  for  use  by  your  completion  function.  Your 
application  specifies  the  value  of  this  reference  constant  in  the  callback  function 
structure  you  pass  to  the  Image  Compression  Manager. 

flags  Constants 

codecCompl eti on Source 

The  Image  Compression  Manager  is  done  with  the  source  buffer.  The  Image 
Compression  Manager  sets  this  flag  to  1  when  it  is  done  with  the  processing 
associated  with  the  source  buffer.  For  compression  operations,  the  source  is  the 
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uncompressed  pixel  map  you  are  compressing.  For  decompression  operations, 
the  source  is  the  decompressed  data  you  are  decompressing. 

codecCompl eti onDest 

The  Image  Compression  Manager  is  done  with  the  destination  buffer.  The 
Image  Compression  Manager  sets  this  flag  to  1  when  it  is  done  with  the 
processing  associated  with  the  destination  buffer. 

See  Also 

Seethe  ICMCompl  etionProcRecord  (IV-2279)  structure  and  the 
CompressSequenceFrame  (1-124),  DecompressSequenceFrameS  (1-243), 
DecompressSequenceFrameWhen  (1-245),  Medi  aQueueNonPrimarySourceData  (11-885), 
and  similar  functions. 

ICMConvertDataFormatProc 

Undocumented 

typedef  OSErr  (*ICMConvertDataFormatProcPtr)  (void  *refCon,  long  flags, 
Handle  desi redFormat ,  Handle  sourceDataFormat,  void  *srcData, 
long  srcDataSize,  void  **dstData,  long  *dstDataSi ze ) ; 

//  Declaration  of  a  typical  appl i cati on -def i ned  function 
OSErr  MylCMConvertDataFormatProc  ( 


voi  d 

*refCon 

1  ong 

fl  ags 

Handl e 

desi redFormat 

Hand!  e 

sourceDataFormat 

voi  d 

*srcData 

1  ong 

srcDataSi ze 

voi  d 

**dstData 

1  ong 

*dstDataSize  ); 

refCon 

Pointer  to  a  reference  constant  that  the  client  code  supplies  to  your  callback. 
You  can  use  this  reference  to  point  to  a  data  structure  containing  any 
information  your  callback  needs, 
fl  ags 

Undocumented 
desi redFormat 

Undocumented 

sourceDataFormat 

Undocumented 
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srcData 

Undocumented 
srcDataSi ze 

Undocumented 

dstData 

Undocumented 
dstDataSi ze 

Undocumented 


function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 


See  Also 

See  the  CDSequenceNewDataSource  (1-82)  and  NewICMConvertDataFormatUPP  (11-1061) 
functions. 


ICMCursorShieldedProc 


Undocumented 

typedef  void  (*ICMCursorShi el dedProcPtr)  (const  Rect  *r,  void  *refcon, 
1 ong  flags); 

//  Declaration  of  a  typical  application-defined  function 
void  My ICMCursorShi el dedProc  ( 
const  Rect  *r 

void  *refcon 

long  flags  ); 
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Undocumented 
re f con 

Pointer  to  a  reference  constant  that  the  client  code  supplies  to  your  callback. 
You  can  use  this  reference  to  point  to  a  data  structure  containing  any 
information  your  callback  needs. 

fl  ags 

Undocumented 

See  Also 

Seethe  NewICMCursorShi el dedUPP  (11-1062)  function. 
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ICMDataProc 


Supplies  compressed  data  during  a  decompression  operation. 

typedef  OSErr  (*ICMDataProcPtr)  (Ptr  *dataP,  long  bytesNeeded,  long  refcon); 

//  Declaration  of  a  typical  appl i cati on -def i ned  function 

OSErr  My ICMDataProc  ( 

Ptr  *dataP 

long  bytesNeeded 

1 ong  refcon  ) ; 

dataP 

Contains  a  pointer  to  the  address  of  the  data  buffer.  The  decompressor  uses  this 
parameter  to  indicate  where  your  data-loading  function  should  return  the 
compressed  data.  You  establish  this  data  buffer  when  you  start  the 
decompression  operation.  For  example,  the  data  parameter  to 
FDecompress  Image  (1-355)  defines  the  location  of  the  data  buffer  for  that 
operation.  Upon  return  from  your  data-loading  function,  this  pointer  should 
refer  to  the  beginning  of  the  compressed  data  that  you  loaded.  The 
decompressor  may  also  use  this  parameter  to  indicate  that  it  wants  to  reset  the 
mark  within  the  compressed  data  stream.  If  the  dataP  parameter  is  set  to  NIL, 
the  bytesNeeded  parameter  contains  the  new  mark  position,  relative  to  the 
current  position  of  the  data  stream.  If  your  data-loading  function  does  not 
support  this  operation,  return  a  nonzero  result  code. 

bytesNeeded 

Specifies  the  number  of  bytes  requested  or  the  new  mark  offset.  If  the 
decompressor  has  requested  additional  compressed  data  (that  is,  the  value  of 
the  dataP  parameter  is  not  N I L),  then  this  parameter  specifies  how  many  bytes 
to  return.  This  value  never  exceeds  the  size  of  the  original  data  buffer.  Your 
data-loading  function  should  read  the  data  from  the  current  mark  in  the  input 
data  stream.  If  the  decompressor  has  requested  to  set  a  new  mark  position  in 
the  data  stream  (that  is,  the  value  of  the  dataP  parameter  is  NIL),  then  this 
parameter  specifies  the  new  mark  position  relative  to  the  current  position  of  the 
data  stream. 

refcon 

Contains  a  reference  constant  value  for  use  by  your  data-loading  function.  Your 
application  specifies  the  value  of  this  reference  constant  in  the  data-loading 
function  structure  you  pass  to  the  Image  Compression  Manager. 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 
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See  Also 

See  the  ICMDataProcRecord  (IV-2279)  structure  and  the  SetCompressedPi  xMapInfo 
(III — 1573),  SetDSequenceDataProc  (III — 1584),  Trimlmage  (III — 1956), 
ImageCodecGetCompressedlmageSi  ze  (11-710),  NewICMDatallPP  (11-1062),  and  similar 
functions. 


ICMFlushProc 


Writes  compressed  data  to  a  storage  device  during  a  compression  operation. 

typedef  OSErr  ( *  I  CM  FI ushProcPtr)  (Ptr  data,  long  bytesAdded,  long  refcon); 

//  Declaration  of  a  typical  application-defined  function 

OSErr  My  I  CM  FI ushProc  ( 

Ptr  data 

long  bytesAdded 

long  refcon  ); 

data 

Points  to  the  data  buffer.  The  compressor  uses  this  parameter  to  indicate  where 
your  data-unloading  function  can  find  the  compressed  data.  You  establish  this 
data  buffer  when  you  start  the  compression  operation.  For  example,  the  data 
parameter  to  FCompress  Image  (1-344)  defines  the  location  of  the  data  buffer  for 
that  operation.  This  pointer  contains  a  32-bit  clean  address.  Your  ICMF1  ushProc 
function  should  make  no  other  assumptions  about  the  value  of  this  address. 
The  compressor  may  also  use  this  parameter  to  indicate  that  it  wants  to  reset 
the  mark  within  the  compressed  data  stream.  If  the  data  parameter  is  set  to  N I L, 
the  bytesNeeded  parameter  contains  the  new  mark  position,  relative  to  the 
current  position  of  the  output  data  stream.  If  your  ICMFlushProc  function  does 
not  support  this  operation,  return  a  nonzero  result  code. 

bytesAdded 

Specifies  the  number  of  bytes  to  write  or  the  new  mark  offset.  If  the  compressor 
wants  to  write  out  some  compressed  data  (that  is,  the  value  of  data  is  not  N I L), 
then  this  parameter  specifies  how  many  bytes  to  write.  This  value  never 
exceeds  the  size  of  the  original  data  buffer.  Your  ICMFlushProc  function  should 
write  that  data  at  the  current  mark  in  the  output  data  stream.  If  the  compressor 
has  requested  to  set  a  new  mark  position  in  the  output  data  stream  (that  is,  the 
value  of  data  is  N I L),  then  this  parameter  specifies  the  new  mark  position 
relative  to  the  current  position  of  the  data  stream. 
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refcon 

Contains  a  reference  constant  value  for  use  by  your  ICMFlushProc  function. 
Your  application  specifies  the  value  of  this  reference  constant  in  the 
data-unloading  function  structure  you  pass  to  the  Image  Compression 
Manager. 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 

Discussion 

You  assign  an  ICMFlushProc  function  to  an  image  or  a  sequence  by  passing  a  pointer 
to  a  structure  that  identifies  the  function  to  the  appropriate  compression  function. 

See  Also 

See  the  I  CM  FI  ushProcRecord  (IV-2280)  structure  and  the  FCompress  Image  (1-344), 
ImageCodecTri  mlmage  (11-743),  SetCSequenceFl  ushProc  (III— 1575),  and  similar 
functions. 


ICMMemoryDisposedProc 

Called  before  disposing  of  the  memory  allocated  by  a  codec. 

typedef  void  (*ICMMemoryD1sposedProcPtr)  (Ptr  memoryBl ock ,  void  *refcon); 

//  Declaration  of  a  typical  appl i cati on -def i ned  function 
void  My ICMMemoryDi sposedProc  ( 

Ptr  memoryBl ock 

voi d  *refcon  ) ; 

memoryBl ock 

Pointer  to  a  block  of  memory, 
refcon 

Contains  a  reference  constant  value  that  your  codec  must  pass  to  the 
memoryGoneProc  function. 

Discussion 

This  function  must  be  called  if  the  memory  block  is  to  be  disposed  of  by  the  codec 
instead  of  by  ImageCodecDi  sposeMemory  (11-696).  For  example,  this  would  occur  if  the 
codec  is  closed  and  still  has  memory  allocation  outstanding  or  if  the  memory  is 
required  to  complete  another  operation. 

Special  Considerations 

The  Image  Compression  Manager  does  not  currently  track  memory  allocations. 
When  a  compressor  or  decompressor  component  instance  is  closed,  it  must  ensure 
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that  all  blocks  allocated  by  that  instance  are  disposed  and  call  your 

ICMMemoryDi  sposedProc  (III— 2092).  This  callback  must  not  be  called  at  interrupt  time. 

See  Also 

Seethe  CDSequenceNewMemory  (1-84),  ImageCodecNewImageBufferMemory  (11-727), 
ImageCodecNewMemory  (11-729),  and  NewICMMemoryDi  sposedUPP  (11-1063)  functions. 


ICMProgressProc 

Reports  on  the  progress  of  a  compressor  or  decompressor. 

typedef  OSErr  (*ICMProgressProcPtr)  (short  message.  Fixed  completeness, 
long  refcon); 

//  Declaration  of  a  typical  application-defined  function 
OSErr  MylCMProgressProc  ( 
short  message 

Fixed  completeness 

long  refcon  ); 

message 

Indicates  why  the  Image  Compression  Manager  called  your  function.  There  are 
three  valid  messages,  listed  below. 

compl eteness 

Contains  a  fixed-point  value  indicating  how  far  the  operation  has  progressed. 
Its  value  is  always  between  0.0  and  1.0.  This  parameter  is  valid  only  when  the 
message  field  is  set  to  codecProgresstlpdatePercent. 
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refcon 

Contains  a  reference  constant  value  for  use  by  your  progress  function.  Your 
application  specifies  the  value  of  this  reference  constant  in  the  progress 
function  structure  you  pass  to  the  Image  Compression  Manager. 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error.  When  a  component  calls  your  progress  function,  it 
supplies  you  with  a  number  that  indicates  the  completion 
percentage.  Your  program  can  cause  the  component  to  terminate  the 
current  operation  by  returning  a  result  code  of  codecAbortErr. 

message  Constants 

codecProgressOpen 

Indicates  the  start  of  a  long  operation.  This  is  always  the  first  message  sent  to 
your  function.  Your  function  can  use  this  message  to  trigger  the  display  of  your 
progress  window. 
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codecProgresslIpdatePercent 

Passes  completion  information  to  your  function.  The  Image  Compression 
Manager  repeatedly  sends  this  message  to  your  function.  The  completeness 
parameter  indicates  the  relative  completion  of  the  operation.  You  can  use  this 
value  to  update  your  progress  window. 
codecProgressClose 

Indicates  the  end  of  a  long  operation.  This  is  always  the  last  message  sent  to 
your  function.  Your  function  can  use  this  message  as  an  indication  to  remove 
its  progress  window. 

Discussion 

The  Image  Compression  Manager  calls  your  progress  function  only  during  long 
operations,  and  it  does  not  call  your  function  more  than  30  times  per  second. 

See  Also 

The  following  functions  have  parameters  that  allow  you  to  provide 
application-defined  progress  functions:  FCompressImage  (1-344),  FDecompressImage 
(1-355),  Tri mlmage  (III — 1956),  FCompressPi cture  (1-348),  FCompressPi ctureFi  1  e 
(1-352),  DrawPi  ctureFi  1  e  (1-310),  DrawT ri mmedPi  cture  (1-311), 

DrawTri  mmedPi  ctureFi  1  e  (1-313),  MakeThumbnai  1  FromPi  cture  (11-790), 

MakeThumbnai  1  FromPi  ctureFi  1  e  (11-791),  MakeThumbnai  1  FromPi  xMap  (11-792), 
SetCompressedPixMapInfo  (III — 1573),  and  GetCompressedPixMapInfo  (1-397).  If  you 
pass  a  value  of  -1  in  the  progressProc  parameter  of  any  of  these  functions,  you 
obtain  a  standard  progress  function. 


ImageCodecDrawBandCompleteProc 


Undocumented 

typedef  void  (*ImageCodecDrawBandCompleteProcPtr)  (void  *refcon, 
ComponentResul t  drawBandResul t ,  UInt32  drawBandCompl  eteFl  ags ) ; 

//  Declaration  of  a  typical  application-defined  function 

void  My ImageCodecDrawBandCompl eteProc  ( 

void  *refcon 

ComponentResul t  drawBandResul t 

UInt32  drawBandCompl eteFl ags  ); 

refcon 

Pointer  to  a  reference  constant  that  the  client  code  supplies  to  your  callback. 
You  can  use  this  reference  to  point  to  a  data  structure  containing  any 
information  your  callback  needs. 
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drawBandResul t 
Undocumented 
drawBandCompl eteFl  ags 
Undocumented 

Version  Notes 

Introduced  in  QuickTime  5. 

See  Also 

See  the  NewImageCodecDrawBandCompl  eteLIPP  (11-1064)  function. 


ImageCodecMPDrawBandProc 


Undocumented 

typedef  ComponentResul t  (*ImageCodecMPDrawBandProcPtr)  (void  *refcon, 
ImageSubCodecDecompressRecord  *drp) ; 

//  Declaration  of  a  typical  application-defined  function 
ComponentResul t  My ImageCodecMPDrawBandProc  ( 
void  *refcon 

ImageSubCodecDecompressRecord  *drp  ); 

ref con 

Pointer  to  a  reference  constant  that  the  client  code  supplies  to  your  callback. 
You  can  use  this  reference  to  point  to  a  data  structure  containing  any 
information  your  callback  needs. 


CLB 


Pointer  to  an  ImageSubCodecDecompressRecord  (IV-2289)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 


See  Also 

See  the  ImageCodecGetBaseMPWorkFunction  (11-709)  and  NewImageCodecMPDrawBandUPP 
(11-1065)  functions. 
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ImageCodecT  imeT  riggerProc 


Undocumented 

typedef  void  (*ImageCodecTimeTriggerProcPtr)  (void  *refcon); 

//  Declaration  of  a  typical  appl i cati on -def i ned  function 
void  My ImageCodecTimeTri ggerProc  ( 
voi d  *refcon  ) ; 

refcon 

Pointer  to  a  reference  constant  that  the  client  code  supplies  to  your  callback. 
You  can  use  this  reference  to  point  to  a  data  structure  containing  any 
information  your  callback  needs. 

See  Also 

See  the  ImageCodecSchedul  eFrame  (11-736)  and  NewImageCodecTi meTri  ggerUPP 
(11-1065)  functions. 


MCActionFilterProc 


Responds  to  movie  controller  actions. 

typedef  Boolean  (*MCActionFilterProcPtr)  (Movi eControl 1 er  me,  short  *action, 
voi d  *params ) ; 

//  Declaration  of  a  typical  application-defined  function 
Boolean  MyMCActi onFi 1 terProc  ( 

Movi eControl 1 er  me 

short  *action 

voi d  *params  ) ; 


me 

Specifies  the  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi eControl  1  er  (11-1071). 

acti on 

A  movie  controller  action.  For  a  list  of  actions,  see  Chapter  2  of  Inside  Macintosh: 
QuickTime  Components  (listed  in  the  bibliography). 
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params 

A  pointer  to  a  structure,  such  as  QTStatusStringRecord  (IV-2387)  or 
Resol  vedQTEventSpec  (IV-2401),  that  passes  information  to  the  callback.  See 
Movi  es .  h. 

function  result  Undocumented 

Discussion 

Movie  controller  components  allow  your  application  to  field  movie  controller 
actions.  You  define  an  MCActi  onFi  1  terProc  in  your  application  and  assign  it  to  a 
controller  by  calling  the  MCSetActionFi  1  terWi  thRefCon  function. 

See  Also 

See  the  MCSetActi onFi  1  ter  and  NewMCActi  onFi  1  terllPP  (11-1068)  functions. 


MCActi  onFilterW  ithRef  ConProc 


Responds  to  movie  controller  actions  with  a  reference  constant. 

typedef  Boolean  (*MCActi onFi 1 terWi thRefConProcPtr)  (Movi eControl 1 er  me, 
short  action,  void  *params,  long  refCon); 

//  Declaration  of  a  typical  application-defined  function 
Boolean  MyMCActi onFi 1 terWi thRefConProc  ( 

Movi eControl 1 er  me 
short  action 

void  *params 

long  refCon  ); 
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me 

Specifies  the  movie  controller  for  the  operation.  You  obtain  this  identifier  from 
OpenComponent  (11-1130)  or  OpenDef  aul  tComponent  (11-1131),  or  from 
NewMovi  eControl  1  er  (11-1071). 
acti on 

A  movie  controller  action.  For  a  list  of  actions,  see  Chapter  2  of  Inside  Macintosh: 
QuickTime  Components  (listed  in  the  bibliography), 
params 

A  pointer  to  a  structure,  such  as  QTStatusStringRecord  (IV-2387),  that  passes 
information  to  the  callback.  See  Movi  es .  h. 
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refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 

function  result  Undocumented 

See  Also 

See  the  MCSetActi  onFi  1  terWi  th  Ref  Con  (11-829)  and  NewMCActi  onFilterWithRefConUPP 
(11-1069)  functions. 


ModalFilterProc 


Determines  how  events  are  filtered  for  modal  dialog  boxes. 

typedef  Boolean  (*Modal Fi 1 terProcPtr )  (DialogPtr  theDialog, 

EventRecord  *theEvent,  Di al ogltemlndex  *itemHit); 

//  Declaration  of  a  typical  appl i cati on -def i ned  function 
Boolean  MyModal Fi 1 terProc  ( 

DialogPtr  theDialog 

EventRecord  *theEvent 

Di al ogltemlndex  *itemHit  ); 

theDi al og 

A  pointer  to  the  dialog  record. 
theEvent 

A  pointer  to  the  event  record, 
i temHi t 

The  item  number. 

function  result  Your  Modal  Fi  1  terProc  callback  returns  a  Bool  ean  value  that  reports 
whether  it  handled  the  event.  If  your  function  returns  a  value  of 
FALSE,  QuickTime  processes  the  event  through  its  own  filters.  If  your 
function  returns  a  value  of  TRUE,  QuickTime  returns  with  no  further 
action. 


Discussion 

The  Standard  File  Package  contains  an  internal  filter  function  that  performs  some 
preliminary  processing  on  each  event  it  receives.  If  you  provide  aModalFilterProc 
callback,  it  is  called  after  the  internal  Standard  File  Package  filter  function  and 
before  the  event  is  sent  to  your  dialog  hook  function.  You  might  provide  a 
Modal  Fi  1  terProc  callback  for  several  reasons.  If  you  have  customized  the  Open  or 
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Save  dialog  boxes  by  adding  one  or  more  items,  you  might  want  to  map  some  of  the 
user's  keypresses  to  those  items  in  the  same  way  that  the  internal  filter  function 
maps  certain  keypresses  to  existing  items. 

Special  Considerations 

You  can  supply  aModalFilterProc  callback  only  when  you  use  one  of  the 
procedures  that  displays  a  customized  dialog  box.  Another  reason  to  provide  a 
Modal  Fi  1  terProc  callback  is  to  avoid  a  problem  that  can  arise  if  an  update  event  is 
received  for  one  of  your  application's  windows  while  a  Standard  File  Package 
dialog  box  is  displayed. 

See  Also 

See  the  ImageCodecRequestSetti  ngs  (11-735),  QTVi  deoOutputCustomConf  i  gureDi  spl  ay 
(11-1322),  SFPGetFi  1  ePrevi  ew  (III— 1676),  and  similar  functions. 

ModalFilterYDProc 

Determines  how  the  Dialog  Manager  filters  events. 

typedef  Boolean  (*Modal Fi 1 terYDProcPtr)  (DialogPtr  theDialog, 

EventRecord  *theEvent,  short  *itemHit,  void  *yourDataPtr) ; 

//  Declaration  of  a  typical  application-defined  function 
Boolean  MyModal Fi 1 terYDProc  ( 

DialogPtr  theDialog 

EventRecord  *theEvent 

short  *itemHit 

void  *yourDataPtr  ); 
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theDi al og 

A  pointer  to  the  dialog  record. 
theEvent 

A  pointer  to  the  event  record, 
i temHi t 

The  item  number. 
yourDataPtr 

A  pointer  to  the  data  received  from  your  application,  if  any. 

function  result  Your  Modal  Fi  1  terProc  callback  returns  a  Bool  ean  value  that  reports 
whether  it  handled  the  event.  If  your  function  returns  a  value  of 
FALSE,  QuickTime  processes  the  event  through  its  own  filters.  If  your 
function  returns  a  value  of  TRUE,  QuickTime  returns  with  no  further 
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action. 

Discussion 

The  Modal  FilterProc  callback  used  with  custom  file  dialogs  requires  the  additional 
yourDataPtr  parameter. 

See  Also 

See  the  CustomGetFi  1  ePrevi ew  (1-163)  and  Graphi  csExportRequestSetti ngs  (1-588) 
functions. 


MovieDrawingCompleteProc 

Called  when  movie  drawing  is  complete. 

typedef  OSErr  (*Movi eDrawi ngCompl eteProcPtr )  (Movie  theMovie,  long  refCon); 

//  Declaration  of  a  typical  application-defined  function 
OSErr  MyMovi eDrawi ngCompl eteProc  ( 

Movie  theMovie 

1  ong  refCon  ) ; 

theMovi  e 

Specifies  the  movie  for  this  operation. 
refCon 

Contains  the  reference  constant  you  supplied  when  your  application  called  the 
SetMovi  eDrawi  ngCompl  eteProc  function. 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 


Special  Considerations 

Some  media  handlers  may  take  less  efficient  playback  paths  when  a 

Movi  eDrawi  ngCompl  eteProc  is  used,  so  it  should  be  used  only  when  absolutely 

necessary. 

See  Also 

See  the  SetMovi  eDrawi  ngCompl  eteProc  (III — 1617)  and  NewMovi  eDrawi  ngCompl  etellPP 
(11-1072)  functions. 
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MovieExecuteW  ired  ActionsProc 


Undocumented 

typedef  OSErr  (*MovieExecuteWi redActi onsProcPtr)  (Movie  theMovie, 
void  *refcon,  long  flags,  QTAtomContai ner  wi redActi ons  ) ; 

//  Declaration  of  a  typical  application-defined  function 
OSErr  MyMovi eExecuteWi redActi onsProc  ( 

Movie  theMovie 

void  *refcon 

long  flags 

QTAtomContai ner  wi redActi ons  ); 


theMovi e 

Specifies  the  movie  for  this  operation, 
ref con 

Pointer  to  a  reference  constant  that  the  client  code  supplies  to  your  callback. 
You  can  use  this  reference  to  point  to  a  data  structure  containing  any 
information  your  callback  needs. 

fl  ags 

Undocumented 

wi redActi ons 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 


See  Also 

See  the  AddMovi  eExecuteWi  redActi  onsProc  (1-36), 
RemoveMovi  eExecuteWi  redActi  onsProc  (III-1457),  and 
NewMovi  eExecuteWi  redActi  onslIPP  (11-1073)  functions. 


MovieExportGetDataProc 


Defines  a  data  source  for  an  export  operation. 

typedef  OSErr  (*MovieExportGetDataProcPtr)  (void  *refCon, 
Movi eExportGetDataParams  *params ) ; 

//  Declaration  of  a  typical  application-defined  function 
OSErr  MyMovieExportGetDataProc  ( 

void  *refCon 
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Movi eExportGetDataParams  *params  ); 
refCon 

Contains  the  value  passed  to  Movi  eExportAddDataSource  (11-919)  in  the  refCon 
parameter 

params 

The  sample  request  is  made  through  a  Movi  eExportGetDataParams  (IV-2314) 
structure. 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 

Discussion 

This  callback  is  passed  to  Movi  eExportAddDataSource  (11-919)  to  define  a  new  data 
source  for  an  export  operation.  The  function  is  used  by  the  exporting  application  to 
request  source  media  data  to  be  used  in  the  export  operation.  For  example,  in  a 
video  export  operation,  frames  of  video  data  (either  compressed  or  uncompressed) 
are  provided.  In  a  sound  export  operation,  buffers  of  audio  (either  compressed  or 
uncompressed)  are  provided. 

Special  Considerations 

The  data  pointed  tobydataPtr  must  remain  valid  until  the  next  call  to  this  function. 
The  MovieExportGetDataProc  callback  is  responsible  for  allocating  and  disposing  of 
the  memory  associated  with  this  data  pointer. 

See  Also 

See  the  Movi  eExportAddDataSource  (11-919), 

Movi  e Expo rtNewGet Da taAndP rope rti  esProcs  (11-927),  and 
Movi  eExportDi  sposeGetDataAndProperti  esProcs  functions. 


MovieExportGetPropertyProc 


Returns  parameters  that  determine  the  appropriate  format  for  movie  export  data. 

typedef  OSErr  (*Movi eExportGetPropertyProcPtr )  (void  *refcon,  long  trackID, 
OSType  propertyType ,  void  *propertyVal ue ) ; 

//  Declaration  of  a  typical  application-defined  function 
OSErr  MyMovi eExportGetPropertyProc  ( 
void  *refcon 

long  trackID 

OSType  propertyType 

void  *propertyVal ue  ); 
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ref con 

Contains  the  value  passed  to  Movi eExportAddDataSource  (11-919)  in  the  refCon 
parameter. 
trackID 

Specifies  the  value  returned  from  Movi  eExportAddDataSource  (11-919). 
propertyType 

Contains  a  pointer  to  the  location  of  the  requested  property  information. 
propertyVal ue 

Specifies  the  property  being  requested  (see  below). 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error.  If  this  function  doesn't  have  a  setting  for  a  requested 
property,  it  should  return  an  error. 

propertyValue  Constants 

scSoundSampi eRateType 

An  UnsignedFixed  value  that  represents  a  sound  track's  sampling  rate. 
scSoundSampi eSizeType 

A  short  integer  that  represents  a  sound  track's  sample  size. 
scSoundChannelCountType 

A  short  integer  that  represents  a  sound  track's  channel  count. 
scSoundCompressi onType 

A  sound  track's  compression  type  constant;  see  "Codec  Identifiers"  (IV-2655). 
movi eExportWi dth 

A  fixed  integer  that  represents  a  video  track's  image  width  in  pixels, 
movi eExportHei ght 

A  fixed  integer  that  represents  a  video  track's  image  height  in  pixels, 
movi eExportVi deoFi  1  ter 

A  pointer  to  a  QTAtomContai  ner  handle  that  references  a  video  track's  filter  atom 
container. 

scSpati al Setti ngsType 

A  video  track's  SCSpati  al  Settings  (IV-2423)  structure. 
scTemporal Setti ngsType 

A  video  track's  SCTemporal  Setti  ngs  (IV-2427)  structure. 
scDataRateSetti ngsType 

A  video  track's  SCDataRateSetti  ngs  (IV-2417)  structure, 
movi eExportDurati  on 

The  TimeRecord  (IV-2486)  structure  for  the  whole  movie. 
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Discussion 

This  function  is  passed  to  Movi  eExportAddDataSource  (11-919)  to  define  a  new  data 
source  for  an  export  operation.  For  example,  a  video  export  operation  may  call  this 
function  to  determine  the  dimensions  of  the  destination  video  track.  The  export 
component  provides  a  default  value  for  the  property  based  on  the  source  data 
format.  For  example,  if  no  values  for  video  track  width  and  height  properties  were 
provided  by  the  callback  function,  the  dimensions  of  the  source  data  would  be  used. 

See  Also 

See  the  Movi  eExportAddDataSource  (11-919), 

Movi  e Expo rtNewGet Da taAndP rope rti  esProcs  (11-927), 

Movi  eExportDi  sposeGetDataAndProperti  esProcs  (11-920),  and 
NewMovi  eExportGetPropertyUPP  (11-1074)  functions. 


MoviePrePrerollCompleteProc 


Undocumented 

typedef  void  (*Movi ePrePrerol 1 Compl eteProcPtr )  (Movie  theMovie, 

OSErr  prerollErr,  void  *refcon); 

//  Declaration  of  a  typical  appl i cati on -def i ned  function 
void  MyMovi ePrePrerol 1 Compl eteProc  ( 

Movie  theMovie 

OSErr  prerollErr 

voi d  *refcon  ) ; 

theMovi e 

Specifies  the  movie  for  this  operation, 
prerol 1  Err 

Undocumented 

refcon 

Pointer  to  a  reference  constant  that  the  client  code  supplies  to  your  callback. 
You  can  use  this  reference  to  point  to  a  data  structure  containing  any 
information  your  callback  needs. 

See  Also 

See  the  PrePrerol  1  Movi  e  (11-1141)  and  NewMovi  ePrePrerol  1  Compl  eteUPP  (11-1089) 
functions. 
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MoviePreviewCallOutProc 


Controls  the  playing  of  a  movie's  preview. 

typedef  Boolean  (*MoviePreviewCal 1 OutProcPtr)  (long  refcon); 

//  Declaration  of  a  typical  application-defined  function 
Boolean  MyMovi ePrevi ewCal 1 OutProc  ( 
long  refcon  ); 

refcon 

A  reference  constant  you  specified  when  you  called  PI  ayMovi  ePrevi  ew  (11-1140). 

function  result  If  your  function  sets  this  value  to  FALSE,  the  Movie  Toolbox  stops  the 
preview  and  returns  to  your  application. 

Discussion 

If  you  call  GetMovi  eActi  veSegment  (1-457)  from  within  your  callback,  the  Movie 
Toolbox  can  change  the  active  movie  segment  to  be  the  preview  segment  of  the 
movie.  The  Movie  Toolbox  will  restore  the  active  segment  when  the  preview  is  done 
playing. 

See  Also 

See  PI  ayMovi  ePrevi  ew  (11-1140). 


MovieProgressProc 


Monitors  the  progress  of  the  Movie  Toolbox  during  long  operations. 

typedef  OSErr  (*MovieProgressProcPtr)  (Movie  theMovie,  short  message, 
short  whatOperati on ,  Fixed  percentDone,  long  refcon); 

//  Declaration  of  a  typical  application-defined  function 
OSErr  MyMovieProgressProc  ( 

Movie  theMovie 

short  message 

short  whatOperati on 
Fixed  percentDone 

long  refcon  ); 

theMovi e 

Specifies  the  movie  for  this  operation.  The  Movie  Toolbox  sets  this  parameter 
to  identify  the  appropriate  movie. 
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message 

Constant  (see  below)  that  indicates  why  the  Movie  Toolbox  called  your 
function. 
whatOperati on 

Constant  (see  below)  that  indicates  the  long  operation  that  is  currently 
underway. 

percentDone 

Contains  a  fixed-point  value  indicating  how  far  the  operation  has  progressed. 
Its  value  is  always  between  0.0  and  1.0.  This  parameter  is  valid  only  when  the 
message  field  is  set  to  movi  eProgressUpdatePercent. 
refcon 

Reference  constant  value  for  use  by  your  progress  function.  Your  application 
specifies  the  value  of  this  reference  constant  when  you  assign  the  progress 
function  to  the  movie. 

function  result  Your  progress  function  should  return  an  error  value.  The  Movie 

Toolbox  examines  this  value  after  each  movi  eProgressUpdatePercent 
message  and  before  continuing  the  current  operation.  Set  this  value 
to  a  nonzero  value  to  cancel  the  operation;  set  it  to  noErr  to  continue. 

message  Constants 

movi eProgressOpen 

Indicates  the  start  of  a  long  operation.  This  is  always  the  first  message  sent  to 
your  function.  Your  function  can  use  this  message  to  trigger  the  display  of  your 
progress  window. 

movi eProgressUpdatePercent 

Passes  completion  information  to  your  function.  The  Movie  Toolbox  repeatedly 
sends  this  message  to  your  function.  The  percentDone  parameter  indicates  the 
relative  completion  of  the  operation.  You  can  use  this  value  to  update  your 
progress  window. 
movieProgressClose 

Indicates  the  end  of  a  long  operation.  This  is  always  the  last  message  sent  to 
your  function.  Your  function  can  use  this  message  as  an  indication  to  remove 
its  progress  window. 

whatOperation  Constants 

progressOpFl atten 

Your  application  has  called  the  FlattenMovie  (1-372)  or  FI  attenMovi  eData 
(1-374)  function. 
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progressOpInsertT  rackSegment 

Your  application  has  called  the  InsertTrackSegment  (11-764)  function.  The 
Movie  Toolbox  calls  the  progress  function  that  is  assigned  to  the  movie  that 
contains  the  destination  track. 
progressOpInsertMovi eSegment 

Your  application  has  called  the  InsertMovi  eSegment  (11-762)  function.  The 
Movie  Toolbox  calls  the  progress  function  that  is  assigned  to  the  destination 
movie. 

progressOpPaste 

Your  application  has  called  the  PasteMovi  eSel  ecti  on  (11-1139)  function.  The 
Movie  Toolbox  calls  the  progress  function  that  is  assigned  to  the  destination 
movie. 

prog  res sOpAddMovi eSel ecti on 

Your  application  has  called  the  AddMovi  eSel  ecti  on  (1-38)  function.  The  Movie 
Toolbox  calls  the  progress  function  that  is  assigned  to  the  destination  movie. 
The  Movie  Toolbox  calls  the  progress  function  that  is  assigned  to  the 
destination  movie. 
progressOpCopy 

Your  application  has  called  the  CopyMovi  eSel  ecti  on  (1-139)  function  The  Movie 
Toolbox  calls  the  progress  function  that  is  assigned  to  the  destination  movie. 

progressOpCut 

Your  application  has  called  the  CutMovi  eSel  ecti  on  (1-166)  function.  The  Movie 
Toolbox  calls  the  progress  function  that  is  assigned  to  the  destination  movie, 
prog ressOpLoadMovielnto Ram 

Your  application  has  called  the  LoadMovi  elntoRam  (11-781)  function.  The  Movie 
Toolbox  calls  the  progress  function  that  is  assigned  to  the  destination  movie. 
progressOpLoadTracklntoRam 

Your  application  has  called  the  LoadT racklntoRam  (11-782)  function.  The  Movie 
Toolbox  calls  the  progress  function  that  is  assigned  to  the  destination  track. 

p r ogress Op LoadMedi alntoRam 

Your  application  has  called  the  LoadMedi  alntoRam  (11-779)  function.  The  Movie 
Toolbox  calls  the  progress  function  that  is  assigned  to  the  destination  media. 
progressOpImportMovi e 

Your  application  has  called  the  ConvertFi  1  eToMovi  eFi  1  e  (1-129)  function.  The 
Movie  Toolbox  calls  the  progress  function  that  is  associated  with  the 
destination  movie  file.  This  flag  is  also  used,  as  appropriate,  for  the 
PasteHandl  elntoMovi e  (11-1137)  functions. 
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p rog res s Op Export Mo vi e 

Your  application  has  called  the  C  o  n  v  e  r  t  M  o  v  i  e  T  o  F  i  1  e  (1-1  34)  function.  The  Movie 
Toolbox  calls  the  progress  function  that  is  associated  with  the  destination 
movie.  This  flag  is  also  used,  as  appropriate,  for  the  PutMovi  elntoTypedHandl  e 
(11-1152)  function. 

See  Also 

See  the  ConvertFi  1  eToMovi  eFi  1  e  (1-129),  GetMovi  eProgressProc  (1-488), 

Movi  e Expo rtSetP rog ressP roc  (11-930),  MovielmportSetProgressProc  (11-961), 

SetMovi eProgressProc  (III— 1630),  and  NewMovi eProgressUPP  (11-1090)  functions. 


MovieRgnCoverProc 


Undocumented 

typedef  OSErr  (*MovieRgnCoverProcPtr)  (Movie  theMovie,  RgnHandle  changedRgn, 

1 ong  refcon ) ; 

//  Declaration  of  a  typical  appl  i  cati on -def i ned  function 
OSErr  MyMovi eRgnCoverProc  ( 

Movie  theMovie 

RgnHandle  changedRgn 

1  ong  refcon  ) ; 

theMovi e 

Specifies  the  movie  for  this  operation. 
changedRgn 

Undocumented 

refcon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 


See  Also 

See  the  GetMovi  eCoverProcs  (IM64),  SetMovi  eCoverProcs  (III — 1614),  and 
NewMovi  eRgnCoverUPP  (11-1091)  functions. 
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MoviesErrorProc 


An  error-notification  function,  called  each  time  the  current  error  value  is  to  be  set  to 
a  nonzero  value. 

typedef  void  (*MoviesErrorProcPtr)  (OSErr  theErr,  long  refcon); 

//  Declaration  of  a  typical  application-defined  function 
void  MyMoviesErrorProc  ( 

OSErr  theErr 

long  refcon  ); 

theErr 

An  error  code;  see  "Error  Codes"  (IV-2663). 
refcon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 

See  Also 

Seethe  SetMovi esErrorProc  (III— 1633)  and  NewMovi esErrorUPP  (11-1091)  functions. 


MusicMIDIReadHookProc 


Undocumented 

typedef  ComponentResul t  (*MusicMIDIReadHookProcPtr)  (MusicMIDIPacket  *mp, 
1 ong  myRefCon ) ; 

//  Declaration  of  a  typical  application-defined  function 
ComponentResul t  MyMusicMIDIReadHookProc  ( 

MusicMIDIPacket  *mp 

long  myRefCon  ); 


CLB 


A  MusicMIDIPacket  (IV-2320)  structure. 
myRefCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 
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See  Also 

See  the  Musi  cRecei  veMIDI  (11-1005),  NAUseDefaul  t M I D I  Input  (11-1052), 
QTMIDIUseRecei  vePort  (11-1189),  and  NewMusi  cMIDI Read HookUP P  (11-1093)  functions. 


MusicMIDISendProc 


Undocumented 


typedef  ComponentResul t  (*MusicMIDISendProcPtr)  ( Componentlnstance  self, 
long  refCon,  Musi cMIDIPacket  *mmp); 

//  Declaration  of  a  typical  application-defined  function 
ComponentResul t  MyMusicMIDISendProc  ( 

Componentlnstance  self 

long  refCon 

MusicMIDIPacket  *mmp  ); 


sel  f 

Undocumented 

refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 


mmp 

A  pointer  to  a  Musi  cMIDIPacket  (IV-2320)  structure. 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 


See  Also 

See  the  Musi  cGetMIDI  Proc  (11-998),  MusicDerivedSetMIDI  (11-978),  Musi  cSetMIDI  Proc 
(11-1009),  and  NewMusi  cMIDISendUPP  (11-1094)  functions. 


MusicOfflineDataProc 

Undocumented 

typedef  ComponentResul t  (*Musi cOff 1 i neDataProcPtr )  (Ptr  SoundData, 
long  numBytes,  long  myRefCon); 

//  Declaration  of  a  typical  application-defined  function 
ComponentResul t  MyMusi cOff 1 i neDataProc  ( 
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Ptr 

SoundData 

1  ong 

numBytes 

1  ong 

myRefCon  ) 

SoundData 

Undocumented 

numBytes 

Undocumented 

myRefCon 

Undocumented 


function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 


See  Also 

See  the  Musi cStartOffl  1  ne  (11-1016)  and  NewMusi cOffl  i neDatallPP  (11-1094) 
functions. 


PrePrerollCompleteProc 


Undocumented 

typedef  void  (*PrePrerol 1 Compl eteProcPtr)  (Medi aHandl er  mh,  OSErr  err, 
void  *refcon); 

//  Declaration  of  a  typical  application-defined  function 
void  MyPrePrerol 1 Compl eteProc  ( 

Medi aHandl er  mh 

OSErr  err 

void  *refcon  ); 


CLB 


mh 

A  media  handler. 


An  error  code;  see  "Error  Codes"  (IV-2663). 
ref con 

Pointer  to  a  reference  constant  that  the  client  code  supplies  to  your  callback. 
You  can  use  this  reference  to  point  to  a  data  structure  containing  any 
information  your  callback  needs. 
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Proc 


See  Also 

Seethe  Medi  aPrePrerol  1  Begi  n  (11-882)  and  NewMovi  ePrePrerol  1  Compl  eteUPP  (11-1089) 
functions. 


Proc 

Generic  callback. 

typedef  long  (*ProcPtr)  (); 

//  Declaration  of  a  typical  appl i cati on -def i ned  function 
1 ong  MyProc  ( ) ; 

function  result  Undocumented 

See  Also 

See  the  NewComponentFuncti  onllPP  (11-1056)  function. 


QDArcProc 


An  application-defined  low-level  routine  to  draw  arcs  or  wedges. 

typedef  void  (*QDArcProcPtr)  (GrafVerb  verb,  Rect  *r,  short  startAngle, 
short  arcAngl e) ; 

//  Declaration  of  a  typical  application-defined  function 
void  MyQDArcProc  ( 

GrafVerb  verb 
Rect  *r 

short  startAngle 

short  arcAngl e  ) ; 


verb 

A  constant  (see  below)  that  defines  the  drawing  action, 
r 

The  rectangle  to  contain  the  arc. 
startAngl e 

The  beginning  angle. 
arcAngl e 

The  ending  angle. 
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verb  Constants 

kQDGrafVerbFrame 

Make  a  pen  drawing. 
kQDGrafVerbPai nt 

Paint  in  the  shape 
kQDGrafVerbErase 

Use  the  background  color. 
kQDGrafVerblnvert 

Invert  the  drawing  color. 
kQDGrafVerbFi 1 1 

Use  the  fill  pattern. 

See  Also 

See  the  QDProcs  (IV-2342)  and  CQDProcs  (IV-2226)  structures. 


QDBitsProc 


An  application-defined  low-level  routine  to  do  bit  and  pixel  image  transfers. 

typedef  void  (*QDBitsProcPtr)  (BitMap  *srcBits,  Rect  *srcRect,  Rect  *dstRect, 
short  mode,  RgnFlandle  maskRgn); 


//  Declaration  of  a  typical 
void  MyQDBitsProc  ( 


Bi tMap 
Rect 
Rect 
short 
RgnHandl e 


*srcBi ts 
*srcRect 
*dstRect 
mode 

maskRgn  ); 


application-defined  function 


srcBi ts 

A  pointer  to  a  bitmap  or  pixel  map  containing  the  image  to  copy. 
srcRect 

A  pointer  to  the  source  rectangle. 
dstRect 

A  pointer  to  the  destination  rectangle. 

mode 

The  source  mode  for  transferring;  see  "Graphics  Transfer  Modes"  (IV-2670). 
maskRgn 

A  handle  to  a  region  acting  as  a  mask  for  the  transfer. 
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QDCommentProc 


See  Also 

See  the  QDProcs  (IV-2342)  and  CQDProcs  (IV-2226)  structures. 


QDCommentProc 


An  application-defined  low-level  routine  to  process  picture  comments,  such  as 
printer  instructions. 

typedef  void  (*QDCommentProcPtr )  (short  kind,  short  dataSize, 

Handl e  dataHandl e) ; 

//  Declaration  of  a  typical  application-defined  function 
void  MyQDCommentProc  ( 
short  kind 

short  dataSize 

Handl e  dataHandl e  ) ; 

ki  nd 

A  comment  type  code,  usually  specific  to  a  printer  or  other  device.  For  a 
discussion  of  picture  comments,  see  Appendix  B  of  Inside  Macintosh:  Imaging 
With  QnickDrazv  (listed  in  the  bibliography). 

dataSi ze 

The  size  of  any  additional  data  passed  in  the  dataHandl  e  parameter. 
dataHandl e 

A  handle  to  additional  data,  or  N I L  if  there  is  none. 


See  Also 

See  the  QDProcs  (IV-2342)  and  CQDProcs  (IV-2226)  structures. 


QDGetPicProc 

An  application-defined  low-level  routine  to  retrieve  picture  definitions. 

typedef  void  (*QDGetPicProcPtr)  (Ptr  dataPtr,  short  byteCount); 

//  Declaration  of  a  typical  application-defined  function 
void  MyQDGetPi cProc  ( 

Ptr  dataPtr 

short  byteCount  ) ; 

dataPtr 

A  pointer  to  the  picture  data. 
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QDJ  ShieldCursorProc 


byteCount 

The  size  of  the  picture  data  in  bytes. 

See  Also 

See  the  QDProcs  (IV-2342)  and  CQDProcs  (IV-2226)  structures. 


QDJ  ShieldCursorProc 


An  application-defined  low-level  routine  to  hide  the  cursor. 

typedef  void  (*QDJShie1 dCursorProcPtr)  (short  left,  short  top,  short  right, 
short  bottom); 

//  Declaration  of  a  typical  application-defined  function 
void  MyQDJShi el dCursorProc  ( 
short  left 

short  top 

short  right 

short  bottom  ); 


1  eft 

The  x  coordinate  of  the  upper-left  corner  of  the  cursor  rectangle. 

top 

The  y  coordinate  of  the  upper-left  corner  of  the  cursor  rectangle, 
ri  ght 

The  x  coordinate  of  the  lower-right  comer  of  the  cursor  rectangle, 
bottom 

The  y  coordinate  of  the  lower-right  comer  of  the  cursor  rectangle. 


QDLineProc 


An  application-defined  low-level  routine  to  draw  a  line. 

typedef  void  (*QDLi neProcPtr)  (Point  newPt); 

//  Declaration  of  a  typical  application-defined  function 
void  MyQDLineProc  ( 

Point  newPt  ); 

newPt 

The  point  to  which  to  draw  the  line. 
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QDOpcodeProc 


See  Also 

See  the  QDProcs  (IV-2342)  and  CQDProcs  (IV-2226)  structures. 


QDOpcodeProc 


An  application-defined  low-level  routine  to  process  QuickDraw  opcodes. 

typedef  void  (*QDOpcodeProcPtr)  (Rect  *fromRect,  Rect  *toRect,  short  opcode, 
short  versi on ) ; 

//  Declaration  of  a  typical  appl i cati on -def i ned  function 
void  MyQDOpcodeProc  ( 

Rect  *fromRect 

Rect  *toRect 

short  opcode 

short  version  ) ; 

f romRect 

A  pointer  to  the  source  rectangle. 
toRect 

A  pointer  to  the  destination  rectangle, 
opcode 

The  QuickDraw  opcode.  See  Appendix  A  of  Inside  Macintosh:  Imaging  With 
QnickDraiv  (listed  in  the  bibliography). 

versi on 

The  format  version.  See  Appendix  A  of  Inside  Macintosh:  Imaging  With 
QiuckDrazv  (listed  in  the  bibliography). 

See  Also 

See  the  CQDProcs  (IV-2226)  structure. 


QDOvalProc 


An  application-defined  low-level  routine  to  draw  ovals. 

typedef  void  (*QD0val ProcPtr)  (GrafVerb  verb,  Rect  *r); 

//  Declaration  of  a  typical  application-defined  function 
void  MyQDOvalProc  ( 

GrafVerb  verb 
Rect  *r  )  ; 
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verb 

A  constant  (see  below)  that  defines  the  drawing  action, 
r 

The  rectangle  to  contain  the  oval. 

verb  Constants 

kQDGrafVerbFrame 

Make  a  pen  drawing. 
kQDGrafVerbPai nt 

Paint  in  the  shape 
kQDGrafVerbErase 

Use  the  background  color. 
kQDGrafVerblnvert 

Invert  the  drawing  color. 
kQDGrafVerbFi 1 1 

Use  the  fill  pattern. 

See  Also 

See  the  QDProcs  (IV-2342)  and  CQDProcs  (IV-2226)  structures. 


QDPixProc 


Undocumented 


typedef  void  (*QDPixProcPtr)  (PixMap  *src,  Rect  *srcRect, 
MatrixRecord  *matrix,  short  mode,  RgnHandle  mask,  PixMap  *matte, 
Rect  *matteRect,  short  flags); 


//  Declaration  of 
void  MyQDPixProc  ( 
Pi xMap 
Rect 

Matri xRecord 
short 
RgnHandl e 
Pi xMap 
Rect 
short 

src 

Undocumented 


typical  applicati 
*src 

*srcRect 

*matri x 

mode 

mask 

*matte 

*matteRect 

flags  ); 


-defined  function 
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QDPolyProc 


srcRect 

Undocumented 

matrix 

Undocumented 

mode 

Undocumented 

mask 

Undocumented 

matte 

Undocumented 

matteRect 

Undocumented 
fl  ags 

Undocumented 

See  Also 

Undocumented 


QDPolyProc 


An  application-defined  low-level  routine  to  draw  polygons. 

typedef  void  (*QDPolyProcPtr)  (GrafVerb  verb,  PolyHandle  poly); 

//  Declaration  of  a  typical  application-defined  function 
void  MyQDPolyProc  ( 

GrafVerb  verb 

PolyHandl e  poly  ) ; 


verb 

A  constant  (see  below)  that  defines  the  drawing  action. 

poly 

A  handle  to  the  polygon  data. 

verb  Constants 

kQDGrafVerbFrame 

Make  a  pen  drawing. 
kQDGrafVerbPai nt 

Paint  in  the  shape 
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QDPutPicProc 


kQDGrafVerbErase 

Use  the  background  color. 
kQDGrafVerblnvert 

Invert  the  drawing  color. 
kQDGrafVerbFi 1 1 

Use  the  fill  pattern. 

See  Also 

See  the  QDProcs  (IV-2342)  and  CQDProcs  (IV-2226)  structures. 


QDPutPicProc 


An  application-defined  low-level  routine  to  save  information  as  a  picture 
definition. 

typedef  void  (*QDPutPi cProcPtr)  (Ptr  dataPtr,  short  byteCount); 

//  Declaration  of  a  typical  application-defined  function 
void  MyQDPutPi cProc  ( 

Ptr  dataPtr 

short  byteCount  ); 

dataPtr 

A  pointer  to  the  data  to  be  saved. 
byteCount 

The  size  of  the  data  in  bytes. 

See  Also 

See  the  QDProcs  (IV-2342)  and  CQDProcs  (IV-2226)  structures. 
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QDRectProc 


An  application-defined  low-level  routine  to  draw  rectangles. 

typedef  void  (*QDRectProcPtr)  (GrafVerb  verb,  Rect  *r); 

//  Declaration  of  a  typical  application-defined  function 
void  MyQDRectProc  ( 

GrafVerb  verb 
Rect  *r  ); 


Inside  QuickTime:  Callbacks 


III-2119 


Callbacks 


QDRgnProc 


verb 

A  constant  (see  below)  that  defines  the  drawing  action, 
r 

A  pointer  to  a  Rect  (IV-2399)  structure  that  defines  the  rectangle. 

verb  Constants 

kQDGrafVerbFrame 

Make  a  pen  drawing. 
kQDGrafVerbPai nt 

Paint  in  the  shape 
kQDGrafVerbErase 

Use  the  background  color. 
kQDGrafVerblnvert 

Invert  the  drawing  color. 
kQDGrafVerbFi 1 1 

Use  the  fill  pattern. 

See  Also 

See  the  QDProcs  (IV-2342)  and  CQDProcs  (IV-2226)  structures. 


QDRgnProc 


An  application-defined  low-level  routine  to  draw  regions. 

typedef  void  (*QDRgnProcPtr)  (GrafVerb  verb,  RgnHandle  rgn); 

//  Declaration  of  a  typical  application-defined  function 
void  MyQDRgnProc  ( 

GrafVerb  verb 

RgnFlandl  e  rgn  ) ; 


verb 

A  constant  (see  below)  that  defines  the  drawing  action, 
rgn 

A  handle  to  a  MacRegi  on  (IV-2303)  structure  that  defines  the  region. 

verb  Constants 

kQDGrafVerbFrame 

Make  a  pen  drawing. 
kQDGrafVerbPai nt 

Paint  in  the  shape 
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QDRRectProc 


kQDGrafVerbErase 

Use  the  background  color. 
kQDGrafVerblnvert 

Invert  the  drawing  color. 
kQDGrafVerbFi 1 1 

Use  the  fill  pattern. 

See  Also 

See  the  QDProcs  (IV-2342)  and  CQDProcs  (IV-2226)  structures. 

QDRRectProc 

An  application-defined  low-level  routine  to  draw  rounded  rectangles. 

typedef  void  (*QDRRectProcPtr)  (GrafVerb  verb,  Rect  *r,  short  ovalWidth, 
short  ovalHeight); 

//  Declaration  of  a  typical  application-defined  function 
void  MyQDRRectProc  ( 

GrafVerb  verb 
Rect  *r 

short  ovalWidth 

short  ovalHeight  ); 

verb 

A  constant  (see  below)  that  defines  the  drawing  action. 


CLB 


A  pointer  to  a  Rect  (IV-2399)  structure  that  defines  the  rectangle, 
oval Wi dth 

The  width  diameter  for  the  comer  oval, 
oval Hei ght 

The  height  diameter  for  the  comer  oval. 

verb  Constants 

kQDGrafVerbFrame 

Make  a  pen  drawing. 
kQDGrafVerbPai nt 

Paint  in  the  shape 
kQDGrafVerbErase 

Use  the  background  color. 
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QDStdGlyphsProc 


kQDGrafVerblnvert 

Invert  the  drawing  color. 
kQDGrafVerbFi 1 1 

Use  the  fill  pattern. 

See  Also 

See  the  QDProcs  (IV-2342)  and  CQDProcs  (IV-2226)  structures. 


QDStdGlyphsProc 


An  application-defined  low-level  routine  to  draw  Unicode  text. 

typedef  OSStatus  (*QDStdGlyphsProcPtr)  (void  *dataStream ,  ByteCount  size); 

//  Declaration  of  a  typical  appl i cati on -def i ned  function 
OSStatus  MyQDStdGlyphsProc  ( 
void  *dataStream 

ByteCount  size  ) ; 

dataStream 

A  pointer  to  the  Unicode  data. 

si  ze 

The  size  of  the  data  in  bytes. 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 


See  Also 

See  the  CQDProcs  (IV-2226)  structure. 


QDTextProc 


An  application-defined  low-level  routine  to  draw  text. 

typedef  void  (*QDTextProcPtr)  (short  byteCount,  Ptr  textBuf,  Point  numer, 
Poi nt  denom) ; 

//  Declaration  of  a  typical  application-defined  function 
void  MyQDTextProc  ( 


short 

byteCount 

Ptr 

textBuf 

Poi  nt 

numer 

Poi  nt 

denom  ) ; 
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QDTxMeasProc 


byteCount 

The  number  of  bytes  of  text  to  draw. 
textBuf 

A  pointer  to  the  buffer  containing  the  text, 
numer 

The  scaling  numerator, 
denom 

The  scaling  denominator. 

See  Also 

See  the  QDProcs  (IV-2342)  and  CQDProcs  (IV-2226)  structures. 


QDTxMeasProc 


An  application-defined  low-level  routine  to  measure  text  width. 

typedef  short  (*QDTxMeasProcPtr)  (short  byteCount,  Ptr  textAddr, 

Point  *numer.  Point  *denom,  Fontlnfo  *info); 

//  Declaration  of  a  typical  application-defined  function 
short  MyQDTxMeasProc  ( 
short  byteCount 

Ptr  textAddr 

Point  *numer 

Point  *denom 

Fontlnfo  *info  ); 

byteCount 

The  number  of  bytes  of  text  data  to  measure. 
textAddr 

A  pointer  to  the  location  of  the  text, 
numer 

The  scaling  numerator, 
denom 

The  scaling  denominator. 

i  nf  o 

A  pointer  to  a  Fontlnfo  (IV-2261)  structure  that  provides  measurement 
information  for  the  current  font. 

function  result  The  width  of  the  text  in  pixels. 
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QTBand  widthN  otificationProc 


See  Also 

See  the  QDProcs  (IV-2342)  and  CQDProcs  (IV-2226)  structures. 


QTBandwidthNotificationProc 


Undocumented 

typedef  OSErr  (*QTBandwidthNotificationProcPtr)  (long  flags,  void  *reserved, 
voi d  *refcon ) ; 

//  Declaration  of  a  typical  appl i cati on -def i ned  function 
OSErr  MyQTBandwi dthNoti fi cati  onProc  ( 
long  flags 

void  *reserved 

voi d  *refcon  ) ; 

fl  ags 

Undocumented 

reserved 

Reserved. 

refcon 

Pointer  to  a  reference  constant  that  the  client  code  supplies  to  your  callback. 
You  can  use  this  reference  to  point  to  a  data  structure  containing  any 
information  your  callback  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 


See  Also 

See  the  QTBandwi  dth Request  (11-1156),  QTBandwi  dthRequestForTimeBase  (11-1157), 
QTSchedul  edBandwi  dthRequest  (11-1219),  and  NewQTBandwi  dthNoti  f  i  cati  onllPP 
(11-1096)  functions. 


QTCallBackProc 

A  generic  callback  function,  installed  by  Cal  1  MeWhen  (1-67). 

typedef  void  (*QTCall BackProcPtr)  (QTCallBack  cb,  long  refCon); 

//  Declaration  of  a  typical  application-defined  function 
void  MyQTCall BackProc  ( 

QTCallBack  cb 
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QTSModalFilterProc 


long  refCon  ); 


cb 

A  pointer  to  a  Call  BackRecord  (IV-2165)  structure  containing  the  callback's 
data. 

refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 

See  Also 

See  the  Cal  1  MeWhen  (1-67)  and  NewQTCal  1  BackUPP  (11-1097)  functions. 


QTSModalFilterProc 

Undocumented 

typedef  Boolean  (*QTSModal Fi 1 terProcPtr)  (DialogPtr  inDialog, 
const  EventRecord  *inEvent,  SIntl6  *1oItemHit,  void  *inRefCon); 

//  Declaration  of  a  typical  application-defined  function 
Boolean  MyQTSModal Fi 1 terProc  ( 

DialogPtr  inDialog 

const  EventRecord  *inEvent 
SIntl6  *ioItemHit 

void  *inRefCon  ); 


CLB 


A  pointer  to  the  dialog  record, 
i nEvent 

A  pointer  to  the  event  record, 
i oltemHi t 

Undocumented 
i nRefCon 

Undocumented 

function  result  Undocumented 


Version  Notes 

Introduced  in  QuickTime  5. 


See  Also 

Seethe  NewQTSModal  FilterUPP  (11-1097)  function. 
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QTSNotificationProc 


QTSNotificationProc 


A  back  channel  from  a  presentation  to  its  creator,  sending  notification  of  various 
events  such  as  a  presentation,  ending,  or  acknowledgment  of  a  preroll  request. 

typedef  ComponentResul t  (*QTSNotificationProcPtr)  ( ComponentResul t  inErr, 
OSType  i nNoti f i cati onType ,  void  *inNotificationParams ,  void  *inRefCon); 


//  Declaration  of  a  typical  appl i cati on -def i ned  function 
ComponentResul t  MyQTSNoti f i cati onProc  ( 

ComponentResul t  inErr 
OSType  i nNoti fi cati onType 

void  *inNoti fi cati onParams 

voi d  *i nRefCon  ) ; 


inErr 

Undocumented 

i nNoti fi cati onType 

The  kind  of  notification;  see  Qui  ckTi  meStreami  ng .  h. 
i nNoti fi cati onParams 
Undocumented 
i nRefCon 

Undocumented 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 


See  Also 

See  the  QTSNewPresentati  onParams  (IV-2376)  and  QTSMedi  aNoti  f  i  cati  onParams 
(IV-2374)  structures  and  the  QTSPresGetNoti  f  i  cati  onProc  (11-1275), 
QTSPresSetNoti  f  i  cati  onProc  (11-1296),  and  NewQTSNoti  f  i  cati  onUPP  (11-1098) 
functions. 


QTSPanelFilterProc 


Undocumented 

typedef  Boolean  (*QTSPanel Fi 1 terProcPtr )  (QTSPanel FilterParams  *inParams, 
voi d  *i nRefCon ) ; 

//  Declaration  of  a  typical  application-defined  function 
Boolean  MyQTSPanel Fi 1 terProc  ( 

QTSPanel Fi 1 terParams  *inParams 
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void  *inRefCon  ); 

i nParams 

Undocumented 
i nRefCon 

Undocumented 

function  result  Undocumented 

Version  Notes 

Introduced  in  QuickTime  5. 

See  Also 

Seethe  NewQTSPanel  FilterUPP  (11-1098)  function. 


QTSyncT  askProc 

Undocumented 

typedef  void  (*QTSyncTaskProcPtr)  (void  *task); 

//  Declaration  of  a  typical  application-defined  function 
void  MyQTSyncTaskProc  ( 
void  *task  ); 


task 

Undocumented 

See  Also 

Seethe  QTSyncTaskRecord  (IV-2391)  structure  and  the  NewQTSyncTaskUPP  (11-1099) 
function. 


CLB 


QTVRBackBufferlmagingProc 

An  imaging  procedure  that  draws  directly  into  the  back  buffer  for  a  QTVR 
panoramic  node. 

typedef  OSErr  (*QTVRBackBufferImagi ngProcPtr)  (QTVRInstance  qtvr, 

Rect  *drawRect,  UIntl6  arealndex,  UInt32  flagsln,  UInt32  *flags0ut, 
SInt32  refCon); 

//  Declaration  of  a  typical  application-defined  function 
OSErr  MyQTVRBackBuf f erlmagi ngProc  ( 

QTVRInstance  qtvr 
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QTVREnteringNodeProc 


Rect 

*drawRect 

UIntl6 

arealndex 

UInt32 

fl agsln 

UInt32 

*f 1 agsOut 

SInt32 

refCon  ) ; 

qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
drawRect 

Undocumented 

arealndex 

Undocumented 
fl agsln 

Undocumented 
f 1 agsOut 

Undocumented 

refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 


function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 

See  Also 

See  the  QTVRSetBackBuf  ferlmagi  ngProc  (11-1411)  and  NewQTVRBackBuf  f  erlmagi  ngUPP 
(11-1099)  functions. 


QTVREnteringNodeProc 


A  routine  called  whenever  a  QTVR  node  is  entered,  in  response  either  to  user 
actions  or  QuickTime  VR  Manager  functions  that  change  nodes. 

typedef  OSErr  (*QTVREnteri ngNodeProcPtr )  ( QTVRInstance  qtvr,  UInt32  nodelD, 
SInt32  refCon ) ; 

//  Declaration  of  a  typical  application-defined  function 
OSErr  MyQTVREnteri ngNodeProc  ( 

QTVRInstance  qtvr 

UInt32  nodelD 

SInt32  refCon  ) ; 
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QTVRImagingCompleteProc 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRI instance  (11-1373). 
nodelD 

A  node  ID.  Set  this  parameter  to  kQTVRCurrentNode  to  designate  the  current 
node. 

refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 


function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 


See  Also 

See  the  QTVRSetEnteri  ngNodeProc  (11-1419)  and  NewQTVREnteri  ngNodeUPP  (II — 1100) 
functions. 


QTVRImagingCompleteProc 


An  imaging  completion  procedure  for  a  QuickTime  VR  movie,  called  whenever 
QTVR  finishes  drawing  an  image  into  the  prescreen  buffer. 

typedef  OSErr  (*QTVRImagingCompl eteProcPtr)  (QTVRInstance  qtvr, 

SInt32  refCon); 

//  Declaration  of  a  typical  application-defined  function 
OSErr  MyQTVRImagi ngCompl eteProc  ( 

QTVRInstance  qtvr 

SInt32  refCon  ); 


CLB 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 

refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 
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QTVRInterceptProc 


See  Also 

See  the  QTVRSetPrescreenlmagi ngCompl  eteProc  (11-1432)  and 
NewQTVRImagi  ngCompl  eteUPP  (II— 1 100)  functions. 


QTVRInterceptProc 


A  routine  that  is  called  when  certain  QTVR  functions  are  intercepted. 

typedef  void  (*QTVRInterceptProcPtr )  (QTVRInstance  qtvr, 
QTVRInterceptPtr  qtvrMsg,  SInt32  refCon,  Boolean  *cancel ) ; 

//  Declaration  of  a  typical  application-defined  function 
void  MyQTVRInterceptProc  ( 

QTVRInstance  qtvr 

QTVRInterceptPtr  qtvrMsg 
SInt32  refCon 

Bool ean  *cancel  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
qtvrMsg 

A  pointer  to  a  QTVRInterceptRecord  (IV-2396)  structure  that  determines  which 
functions  are  intercepted. 

refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs, 
cancel 

A  pointer  to  a  Boolean;  set  to  TRUE  if  the  intercept  is  cancelled. 

See  Also 

See  the  QTVRInstal  1  InterceptProc  (11-1387)  and  NewQTVRInterceptUPP  (II — 1101) 
functions. 


QTVRLeavingNodeProc 

A  routine  called  whenever  a  QTVR  node  is  left,  in  response  either  to  user  actions  or 
QuickTime  VR  Manager  functions  that  change  nodes. 

typedef  OSErr  (*QTVRLeavingNodeProcPtr)  (QTVRInstance  qtvr, 
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UInt32  fromNodelD,  UInt32  toNodelD,  Boolean  *cancel ,  SInt32  refCon); 

//  Declaration  of  a  typical  application-defined  function 
OSErr  MyQTVRLeavi ngNodeProc  ( 

QTVRInstance  qtvr 
UInt32  fromNodelD 

UInt32  toNodelD 

Boolean  *cancel 

SInt32  refCon  ); 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRInstance  (11-1373). 
fromNodelD 

The  ID  of  the  node  being  left.  Set  this  parameter  to  kQTVRCurrentNode  to 
designate  the  current  node. 

toNodelD 

The  ID  of  the  node  being  entered.  Set  this  parameter  to  kQTVRCurrentNode  to 
designate  the  current  node, 
cancel 

A  pointer  to  a  Boolean;  set  to  TRUE  if  the  callback  is  cancelled. 
refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 


function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 


See  Also 

See  the  QTVRSetLeavi  ngNodeProc  (11-1428)  and  NewQTVRLeavi  ngNodeUPP  (II — 1101) 
functions. 


CLB 


QTVRMouseOverHotSpotProc 


A  routine  that  is  called  when  the  mouse  is  over  a  hot  spot  in  a  QTVR  movie. 

typedef  OSErr  (*QTVRMouseOverHotSpotProcPtr)  (QTVRInstance  qtvr, 

UInt32  hotSpotID,  UInt32  flags,  SInt32  refCon); 

//  Declaration  of  a  typical  application-defined  function 
OSErr  MyQTVRMouseOverHotSpotProc  ( 
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QTVRInstance 

UInt32 

UInt32 

SInt32 


qtvr 

hotSpotID 
fl  ags 
refCon  ) ; 


qtvr 

An  instance  of  a  QuickTime  VR  movie.  You  can  get  this  value  by  calling 
QTVRGetQTVRI nstance  (11-1373). 

hotSpotID 

A  hot  spot  ID. 
fl  ags 

Undocumented 

refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 


function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 

See  Also 

See  the  QTVRSetMouseOverHotSpotProc  (11-1429)  and  NewQTVRMouseOverHotSpotUPP 
(11-1102)  functions. 


RTPMPDataReleaseProc 


Routine  called  when  a  media  packetizer  is  finished  with  its  sample  data. 

typedef  void  (*RTPMPDataReleaseProcPtr)  (UInt8  *inData,  void  *inRefCon); 

//  Declaration  of  a  typical  application-defined  function 
void  MyRTPMPDataRel easeProc  ( 

UInt8  *inData 

voi d  *i nRefCon  ) ; 

i nData 

A  pointer  to  the  data, 
i nRefCon 

Apointer  to  information  passed  from  a  RTPMPSampl  eDataParams  (IV-2407) 
structure. 
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See  Also 

See  the  RTPMPSampleDataParams  (IV-2407)  structure  and  the  NewRTPMPDataReleaseUPP 
(11-1102)  function. 


RTPPBCallbackProc 


Routine  used  to  communicate  with  the  caller  of  a  media  packetizer. 

typedef  void  (*RTPPBCal 1 backProcPtr)  (OSType  inSelector,  void  *ioParams, 
void  *inRefCon); 

//  Declaration  of  a  typical  application-defined  function 
void  MyRTPPBCal 1 backProc  ( 

OSType  inSelector 

void  *ioParams 

void  *inRefCon  ); 

i nSel ector 

Undocumented 
i oParams 

Undocumented 
i nRefCon 

Undocumented 

See  Also 

See  the  RTPPBGetCal  1  back  (III— 1493),  RTPPBSetCall  back  (III— 1497),  and 
NewRTPPBCal  1  backUPP  (11-1103)  functions. 


CLB 


SCModalFilterProc 


Filter  routine  called  when  a  user  event  occurs  in  a  sequence  compression  modal 
dialog  box. 

typedef  Boolean  (*SCModal Fi 1 terProcPtr)  (DialogPtr  theDialog, 

EventRecord  *theEvent,  short  *itemHit,  long  refcon); 


//  Declaration  of  a  typical  appl 
Boolean  MySCModal Fi 1 terProc  ( 
DialogPtr  theDialog 

EventRecord  *theEvent 

short  *itemHit 

long  refcon  ); 


i cati on-defined  function 
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theDi al og 

A  pointer  to  a  dialog  box. 
theEvent 

A  pointer  to  an  Event  Re  cord  (IV-2246)  structure  that  defines  a  user  event, 
i temHi t 

A  pointer  to  an  item  ID  number  in  the  dialog  box. 
refcon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 

function  result  Return  TRUE  if  the  event  was  handled,  FALSE  otherwise. 

See  Also 

See  the  SCExtendedProcs  (IV-2418)  structure  and  the  SCGetCompressi  onExtended  and 
NewSCModal  Fi  1  terLIPP  (11-1103)  functions. 


SCModalHookProc 


Called  whenever  the  user  selects  an  item  in  the  dialog  box. 

typedef  short  (*SCModal HookProcPtr)  (DialogPtr  theDialog,  short  itemHit, 
void  *params,  long  refcon); 

//  Declaration  of  a  typical  appl i cati on -def i ned  function 
short  MySCModal HookProc  ( 

DialogPtr  theDialog 
short  itemHit 

void  *params 

1  ong  refcon  ) ; 

theDi al og 

A  pointer  to  a  dialog  box. 
i temHi t 

A  pointer  to  an  item  ID  number  in  the  dialog  box. 
params 

A  pointer  to  your  data  area, 
refcon 

A  reference  constant  that  the  client  code  supplies  to  your  callback. 
function  result  Return  TRUE  if  the  event  was  handled,  FALSE  otherwise. 
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Discussion 

You  can  use  this  callback  to  customize  the  operation  of  the  standard 
image-compression  dialog  box.  For  example,  you  might  want  to  support  a  custom 
button  that  activates  a  secondary  dialog  box.  Another  possibility  would  be  to 
provide  additional  validation  support  when  the  user  clicks  OK. 

See  Also 

Seethe  SCExtendedProcs  (IV-2418)  structure  and  the  SCGetCompressi  onExtended 
(III— 1544)  and  NewSCModal  HookUPP  (11-1104)  functions. 


SequenceFilterDataProc 


Undocumented 

typedef  ComponentResul t  (*SequenceFi 1 terDataProcPtr)  (Ptr  data,  long  len, 
long  sampleCount,  TimeValue  timestamp,  void  *sampl eExtra ,  void  *refCon); 

//  Declaration  of  a  typical  application-defined  function 
ComponentResul t  MySequenceFi 1 terDataProc  ( 


Ptr 

data 

1  ong 

1  en 

1  ong 

sampl eCount 

T i meVal ue 

ti meStamp 

voi  d 

*sampl eExtra 

void 

*refCon  ); 

data 

Undocumented 

1  en 

Undocumented 

sampl eCount 

Undocumented 

ti meStamp 

Undocumented 
sampl eExtra 

Undocumented 

refCon 

Pointer  to  a  reference  constant  that  the  client  code  supplies  to  your  callback. 
You  can  use  this  reference  to  point  to  a  data  structure  containing  any 
information  your  callback  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
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there  is  no  error. 

SFModalFilterProc 

Undocumented 

typedef  Boolean  (*SFModal Fi 1 terProcPtr )  (DialogPtr  theDialog, 

EventRecord  *theEvent,  short  *i temH i t ,  long  refcon); 

//  Declaration  of  a  typical  application-defined  function 
Boolean  MySFModal Fi 1 terProc  ( 

DialogPtr  theDialog 

EventRecord  *theEvent 

short  *i temH i t 

1  ong  refcon  ) ; 

theDi al og 

A  pointer  to  a  dialog  box. 
theEvent 

Undocumented 
i temHi t 

Undocumented 

refcon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 

function  result  Return  TRUE  if  the  event  was  handled,  FALSE  otherwise. 

SGAddFrameBottleProc 

Undocumented 

typedef  ComponentResul t  (*SGAddFrameBottleProcPtr)  (SGChannel  c, 
short  bufferNum,  TimeValue  atTime,  TimeScale  scale, 
const  SGCompressInfo  *ci ,  long  refCon); 

//  Declaration  of  a  typical  application-defined  function 
ComponentResul t  MySGAddFrameBottl eProc  ( 

SGChannel  c 

short  bufferNum 

TimeValue  atTime 
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TimeScale  scale 

const  SGCompressInfo  *ci 

long  refCon  ); 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 
but ferNum 

A  buffer  identifier  provided  by  the  sequence  grabber  component. 
atTime 

Undocumented 

scale 

The  current  time  scale, 
ci 

A  pointer  to  a  SGCompressInfo  (IV-2432)  structure. 
refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 


function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 

See  Also 

See  the  Vi  deoBottl  es  (IV-2501)  structure  and  the  NewSGAddFrameBottl  eUPP  (11-1104) 
function. 


SGCompressBottleProc 


CLB 


Undocumented 

typedef  ComponentResul t  (*SGCompressBottl eProcPtr)  (SGChannel  c, 
short  bufferNum,  long  refCon); 

//  Declaration  of  a  typical  application-defined  function 
ComponentResul t  MySGCompressBottl eProc  ( 

SGChannel  c 

short  bufferNum 

long  refCon  ); 
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SGCompressCompleteBottleProc 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 
bufferNum 

A  buffer  identifier  provided  by  the  sequence  grabber  component. 
refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 


function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 

See  Also 

See  the  Vi  deoBottl  es  (IV-2501)  structure  and  the  SGCompressBottl  eUPP 
(api>SGCompressBottleUPP-SGCompressBottl  eUPP)  function. 


SGCompressCompleteBottleProc 


Undocumented 


typedef  ComponentResul t  (*SGCompressCompl eteBottl eProcPtr )  (SGChannel  c, 
short  bufferNum,  Boolean  *done,  SGCompressInfo  *ci ,  long  refCon); 


//  Declaration  of  a  typical  appl i cati on -def i ned  function 
ComponentResul t  MySGCompressCompl eteBottl eProc  ( 


SGChannel 
short 
Bool ean 

SGCompressInfo 
1  ong 


bufferNum 

*done 

*ci 

refCon  ) ; 


c 

The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

bufferNum 

A  buffer  identifier  provided  by  the  sequence  grabber  component. 

done 

A  pointer  to  a  Bool  ean;  return  TRUE  if  the  task  was  completed,  FALSE  otherwise, 
ci 

Apointer  to  a  SGCompressInfo  (IV-2432)  structure. 
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refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 


function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 

See  Also 

See  the  Vi  deoBottl  es  (IV-2501)  structure  and  the  SGCompressCompl  eteBottl  eUPP 
(api>SGCompressCompleteBottleUPP-SGCompressCornpl  eteBottl  eUPP)  function. 


SGDataProc 


Undocumented 


typedef  OSErr  (*SGDataProcPtr)  (SGChannel  c,  Ptr  p,  long  len,  long  *offset, 
long  chRefCon,  TimeValue  time,  short  writeType,  long  refCon); 


//  Declaration  of  a  typical 
OSErr  MySGDataProc  ( 


SGChannel 
Ptr 
1  ong 
1  ong 
1  ong 

T i meVal ue 
short 
1  ong 


P 

1  en 

*of f set 
chRefCon 
ti  me 

wri teType 
refCon  ); 


application-defined  function 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (ill-1753)  or  SGNewChannel  FromComponent  (ill-1756). 


P 

Undocumented 


CLB 


1  en 

Undocumented 

offset 

Undocumented 

chRefCon 

Undocumented 
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time 

Undocumented 
wri teType 

Undocumented 

refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 


function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 


See  Also 

Seethe  SGSetDataProc  (III— 1 787)  and  NewSGDataUPP  (11-1106)  functions. 


SGDisplayBottleProc 


Undocumented 


typedef  ComponentResul t  (*SGDisplayBottleProcPtr)  (SGChannel  c, 
short  bufferNum,  MatrixRecord  *mp,  RgnHandle  clipRgn,  long  refCon); 


//  Declaration  of  a  typical  appl i cati on -def i ned  function 
ComponentResul t  MySGDi spl ayBottl eProc  ( 


SGChannel 

short 

Matri xRecord 
RgnHandl e 
1  ong 


bufferNum 

*mp 

cl i pRgn 
refCon  ) ; 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

bufferNum 

A  buffer  identifier  provided  by  the  sequence  grabber  component, 
mp 

Undocumented 
cl i pRgn 

Undocumented 
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refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 


function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 

See  Also 

See  the  Vi  deoBottl  es  (IV-2501)  structure  and  the  SGDi  spl  ayBottl  eUPP 
(api>SGDisplayBottleUPP-SGDi  spl  ayBottl  eUPP)  function. 


SGDisplayCompressBottleProc 


Undocumented 

typedef  ComponentResul t  (*SGDi spl ayCompressBottl eProcPtr)  (SGChannel  c, 
Ptr  dataPtr,  ImageDescri pti onHandl e  desc,  MatrixRecord  *mp, 

RgnHandle  clipRgn,  long  refCon); 

//  Declaration  of  a  typical  application-defined  function 
ComponentResul t  MySGDi spl ayCompressBottl eProc  ( 


SGChannel  c 

Ptr  dataPtr 

ImageDescri pti onHandl e  desc 
MatrixRecord  *mp 

RgnHandle  clipRgn 

long  refCon  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

dataPtr 

Undocumented 

desc 

Undocumented 

mp 

Undocumented 

cl  i  pRgn 

Undocumented 
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refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 


function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 

See  Also 

See  the  Vi  deoBottl  es  (IV-2501)  structure  and  the  SGDi  s pi  ayCompressBottl  eUPP 
(api>SGDisplayCompressBottleUPP-SGDi  spl  ayCompressBottl  eUPP)  function. 


SGGrabBottleProc 


Undocumented 

typedef  ComponentResul t  (*SGGrabBottleProcPtr)  (SGChannel  c, 
short  bufferNum,  long  refCon); 

//  Declaration  of  a  typical  application-defined  function 
ComponentResul t  MySGGrabBottl eProc  ( 

SGChannel  c 

short  bufferNum 

1  ong  refCon  ) ; 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 

bufferNum 

A  buffer  identifier  provided  by  the  sequence  grabber  component. 
refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 


function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 

See  Also 

See  the  Vi  deoBottl  es  (IV-2501)  structure  and  the  SGGrabBottl  eUPP 
(api>SGGrabBottleUPP-SGGrabBottl  eUPP)  function. 


III-2142 


Inside  QuickTime:  Callbacks 


SGGrabCompleteBottleProc 


SGGrabCompleteBottleProc 


Undocumented 

typedef  ComponentResul t  (*SGGrabCompl eteBottl eProcPtr)  (SGChannel  c, 
short  bufferNum,  Boolean  *done,  long  refCon); 

//  Declaration  of  a  typical  application-defined  function 
ComponentResul t  MySGGrabCompl eteBottl eProc  ( 

SGChannel  c 

short  bufferNum 

Boolean  *done 

long  refCon  ); 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 

bufferNum 

A  buffer  identifier  provided  by  the  sequence  grabber  component. 

done 

A  pointer  to  a  Bool  ean;  return  TRUE  if  the  task  was  completed,  FALSE  otherwise. 
refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 


function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 

See  Also 

See  the  Vi  deoBottl  es  (IV-2501)  structure  and  the  SGGrabCompl  eteBottl  eUPP 
(api>SGGrabCompleteBottleUPP-SGGrabCompl  eteBottl  eUPP)  function. 


CLB 


SGGrabCompressCompleteBottleProc 


Undocumented 

typedef  ComponentResul t  (*SGGrabCompressCompl eteBottl eProcPtr)  (SGChannel  c, 
Boolean  *done,  SGCompressInfo  *ci ,  TimeRecord  *t,  long  refCon); 

//  Declaration  of  a  typical  application-defined  function 
ComponentResul t  MySGGrabCompressCompl eteBottl eProc  ( 

SGChannel  c 
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Bool ean 

SGCompressInfo 
T i meRecord 
1  ong 


*done 

*ci 

*t 

refCon  ) ; 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1 756). 

done 

A  pointer  to  a  Bool  ean;  return  TRUE  if  the  task  was  completed,  FALSE  otherwise, 
ci 

Apointer  to  a  SGCompressInfo  (IV-2432)  structure, 
t 

Undocumented 

refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 


function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 

See  Also 

See  the  Vi  deoBottl  es  (IV-2501)  structure  and  the  SGGrabCompressCompl  eteBottl  eUPP 
(api>SGGrabCompressCompleteBottleUPP-SGGrabCompressCompl  eteBottl  eUPP) 
function. 


SGModalFilterProc 


Undocumented 

typedef  Boolean  (*SGModal Fi 1 terProcPtr )  (DialogPtr  theDialog, 
const  EventRecord  *theEvent,  short  *itemHit,  long  refCon); 

//  Declaration  of  a  typical  application-defined  function 
Boolean  MySGModal Fi 1 terProc  ( 

DialogPtr  theDialog 

const  EventRecord  *theEvent 

short  *itemHit 

1 ong  refCon  ) ; 
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theDi al og 

A  pointer  to  a  dialog  box. 
theEvent 

Undocumented 
l temHi t 

Undocumented 

refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 

function  result  Return  TRUE  if  the  event  was  handled,  FALSE  otherwise. 

See  Also 

See  the  SGSetti  ngsDi  al  og  (III— 1808),  SGPanel  SetEventFi  1  ter  (III— 1767),  and 
NewSGModal  FilterUPP  (11-1109)  functions. 


SGTransferFrameBottleProc 


Undocumented 


typedef  ComponentResul t  (*SGTransferFrameBottleProcPtr)  (SGChannel  c, 
short  bufferNum,  MatrixRecord  *mp,  RgnHandle  clipRgn,  long  refCon); 


//  Declaration  of  a  typical  application-defined  function 
ComponentResul t  MySGTransf erFrameBottl eProc  ( 


SGChannel 

short 

Matri xRecord 
RgnHandl e 
1  ong 


bufferNum 

*mp 

cl  i  pRgn 
refCon  ) ; 


CLB 


The  connection  identifier  for  the  channel  for  this  operation.  You  get  this  value 
from  SGNewChannel  (III — 1753)  or  SGNewChannel  FromComponent  (III — 1756). 
bufferNum 

A  buffer  identifier  provided  by  the  sequence  grabber  component, 
mp 

Undocumented 
cl  i  pRgn 

Undocumented 
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refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 


function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 

See  Also 

See  the  Vi  deoBottl  es  (IV-2501)  structure  and  the  SGT ransf  erFrameBottl  eUPP 
(api>SGT ransf erFrameBottleUPP-S GT ransferFrameBottleUPP)  function. 


SICCompletionProc 

Accesses  the  parameter  block  for  a  read  request  from  the  Sound  Manager  to  a 
custom  sound  input  component. 

typedef  void  (*SICCompl eti onProcPtr )  (SndlnputCmpParamPtr  SlCParmPtr); 

//  Declaration  of  a  typical  application-defined  function 
void  MySICCompl eti onProc  ( 

SndlnputCmpParamPtr  SlCParmPtr  ); 


Discussion 


See  Also 


SlCParmPtr 

A  pointer  to  a  SndlnputCmpParam  (IV-2446)  structure. 

Use  this  callback  only  if  you  are  writing  your  own  sound  input  component. 
See  the  SndlnputCmpParam  (IV-2446)  structure. 


SICompletionProc 

A  completion  callback  called  by  the  sound  input  functions. 

typedef  void  (*SICompl eti onProcPtr )  (SPBPtr  inParamPtr); 

//  Declaration  of  a  typical  application-defined  function 
void  MySICompl eti onProc  ( 

SPBPtr  i nParamPtr  ) ; 
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l nParamPtr 

A  pointer  to  an  SPB  (IV-2456)  structure. 

See  Also 

See  the  SPB  (IV-2456)  structure  and  the  NewSICompl  eti  on U P P  (II— 1 1 10)  function. 


SllnterruptProc 

An  interrupt  callback  called  by  the  sound  input  functions. 

typedef  void  (*SI InterruptProcPtr)  (SPBPtr  inParamPtr,  Ptr  dataBuffer, 
short  peakAmpl i tude ,  long  sampl eSi ze) ; 

//  Declaration  of  a  typical  application-defined  function 
void  MySI InterruptProc  ( 

SPBPtr  inParamPtr 

Ptr  dataBuffer 

short  peakAmpl i tude 

long  sampleSize  ); 

i nParamPtr 

A  pointer  to  an  SPB  (IV-2456)  structure. 
dataBuffer 

A  pointer  to  data. 
peakAmpl i tude 

Undocumented 
sampl eSi ze 

Undocumented 


See  Also 

See  the  SPB  (IV-2456)  structure  and  the  NewSI  InterruptUPP  (II— 1110)  function. 


SndCallBackProc 


The  callback  that  the  Sound  Manager  executes  whenever  it  receives  a  cal  1  BackCmd 
command. 

typedef  void  (*SndCal 1 BackProcPtr)  ( SndChannel Ptr  chan,  SndCommand  *cmd); 

//  Declaration  of  a  typical  application-defined  function 
void  MySndCal 1 BackProc  ( 

SndChannel Ptr  chan 


CLB 
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SndCommand  *cmd  ) ; 

chan 

A  pointer  to  a  SndChannel  (IV-2440)  structure. 

cmd 

A  pointer  to  a  SndCommand  (IV-2441)  structure. 

See  Also 

See  the  SndChannel  (IV-2440)  structure  and  the  SndNewChannel  (III— 1839)  and 
NewSndCal  1  BackUPP  (II— 1  111)  functions.  The  cal  1  BackCmd  command  is  listed  in 
"Sound  Commands"  (IV-2691). 


SndDoubleBackProc 


Undocumented 

typedef  void  (*SndDoubl eBackProcPtr )  ( SndChannel Ptr  channel, 

SndDoubl eBufferPtr  doubl eBufferPtr ) ; 

//  Declaration  of  a  typical  appl i cati on -def i ned  function 
void  MySndDoubl eBackProc  ( 

SndChannel Ptr  channel 

SndDoubl eBufferPtr  doubl eBufferPtr  ); 

channel 

A  pointer  to  a  SndChannel  (IV-2440)  structure, 
doubl eBufferPtr 

A  pointer  to  a  SndDoubl  eBuf  fer  (IV-2442)  structure. 

See  Also 

See  the  SndDoubl  eBuf  f  erHeader  (IV-2443)  and  SndDoubl  eBuf ferHeader2  (IV-2444) 
structures  and  the  NewSndDoubl  eBackUPP  (II— 1111)  function. 


SoundConverterFillBufferDataProc 

Provides  data  to  the  Sound  Converter. 

typedef  Boolean  (*SoundConverterFi 11 BufferDataProcPtr) 
(SoundComponentDataPtr  *data,  void  *refCon); 

//  Declaration  of  a  typical  application-defined  function 
Boolean  MySoundConverterFi 11 BufferDataProc  ( 
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SoundComponentDataPtr  *data 

void  *refCon  ); 


data 

A  pointer  to  a  SoundComponentData  (IV-2448)  structure. 
refCon 

Pointer  to  a  reference  constant  that  the  client  code  supplies  to  your  callback. 
You  can  use  this  reference  to  point  to  a  data  structure  containing  any 
information  your  callback  needs. 

function  result  Undocumented 

See  Also 

See  the  SoundConverterFi  1 1  Buffer  (III — 1864)  and 
NewSoundConverterFi  1 1  Buf ferDataUPP  (11-1112)  functions. 


SoundParamProc 


A  callback  that  is  called  by  a  sound  output  device  when  another  buffer  of  audio  data 
is  needed  or  when  the  sound  has  finished  playing. 

typedef  Boolean  (*SoundParamProcPtr)  (SoundParamBl ockPtr  *pb); 

//  Declaration  of  a  typical  application-defined  function 
Boolean  MySoundParamProc  ( 

SoundParamBl ockPtr  *pb  ); 


CLB 


A  pointer  to  a  SoundParamBl  ock  (IV-2454)  structure. 
function  result  Undocumented 

See  Also 

See  the  SoundParamBl  ock  (IV-2454)  structure  and  the  NewSoundParamUPP  (11-1112) 
function. 


StdPixProc 


Undocumented 

typedef  void  (*StdPixProcPtr)  (PixMap  *src,  Rect  *srcRect, 
MatrixRecord  *matrix,  short  mode,  RgnHandle  mask,  PixMap  *matte, 
Rect  *matteRect,  short  flags); 
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//  Declaration  of  a  typical  appl 
void  MyStdPixProc  ( 


Pi xMap 
Rect 

Matri xRecord 
short 
RgnHandl e 
Pi xMap 
Rect 
short 


*src 

*srcRect 

*matri x 

mode 

mask 

*matte 

*matteRect 

f 1 ags  ) ; 


ication-defined  function 


src 

Undocumented 

srcRect 

Undocumented 
matri x 

Undocumented 

mode 

Undocumented 

mask 

Undocumented 

matte 

Undocumented 

matteRect 

Undocumented 
fl  ags 

Undocumented 


See  Also 

See  the  NewStdPixUPP  (11-1118)  function. 


TextMediaProc 

A  callback  that  can  be  called  whenever  a  text  sample  is  displayed  in  a  movie. 

typedef  OSErr  (*TextMediaProcPtr)  (Handle  theText,  Movie  theMovie, 
short  *di spl ay Fl ag ,  long  refcon); 

//  Declaration  of  a  typical  appl i cati on -def i ned  function 
OSErr  MyTextMediaProc  ( 
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Handle  theText 

Movie  theMovie 

short  *di  spl  ayFl  ag 

long  ref con  ); 

theText 

A  handle  to  the  text  being  displayed. 
theMovi e 

Specifies  the  movie  for  this  operation, 
di  spl  ay  FI  ag 

Undocumented 
ref con 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 


See  Also 

Seethe  TextMediaSetTextProc  (III— 1947)  and  NewTextMedi aUPP  (11-1118)  functions. 


T  rackT  ransf  erProc 


Called  when  a  track  is  forced  to  draw  into  a  particular  graphics  world,  which  may 
be  different  from  that  of  the  movie. 


CLB 


typedef  OSErr  (*TrackTransferProcPtr)  (Track  t,  long  refCon); 

//  Declaration  of  a  typical  application-defined  function 
OSErr  MyTrackTransferProc  ( 

Track  t 

long  refCon  ); 


t 

A  track  designator. 
refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
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TuneCallBackProc 


there  is  no  error. 


See  Also 

Seethe  SetTrackGWorld  (III— 1659)  and  NewTrackTransferllPP  (11-1122)  functions. 


TuneCallBackProc 


Called  when  a  sequence  of  music  events  is  placed  into  a  queue  to  be  played. 

typedef  void  (*TuneCallBackProcPtr)  (const  TuneStatus  *status,  long  refCon); 

//  Declaration  of  a  typical  application-defined  function 
void  MyTuneCall BackProc  ( 

const  TuneStatus  *status 

1 ong  refCon  ) ; 


status 

A  pointer  to  a  TuneStatus  (IV-2492)  structure. 
refCon 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 

See  Also 

See  the  TuneQueue  (III— 1964)  and  NewTuneCal  1  BackUPP  (11-1122)  functions. 


TunePlayCallBackProc 


Supports  the  TuneSetNoteChannels  (III— 1969)  function. 

typedef  void  (*TunePl ayCal 1 BackProcPtr )  (unsigned  long  *event,  long  seed, 
1 ong  refCon ) ; 

//  Declaration  of  a  typical  application-defined  function 

void  MyTunePl ayCal 1 BackProc  ( 

unsigned  long  *event 

long  seed 

1 ong  refCon  ) ; 


event 

A  pointer  to  a  QuickTime  music  event  structure  in  the  sequence  data. 
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seed 

A  32-bit  value  that  is  guaranteed  to  be  different  for  each  call  to  the  callback 
routine  (unless  2A32  calls  are  made,  after  which  the  values  repeat),  with  one 
exception:  the  value  passed  at  the  beginning  of  a  note  is  also  passed  at  the  end 
of  the  note's  duration,  together  with  a  note  structure  or  an  extended  note  in 
which  the  velocity  bits  are  set  to  0. 
refCon 

A  reference  constant  that  the  client  code  supplies  to  the  callback. 

See  Also 

See  the  T uneSetNoteChannel  s  (III — 1969)  and  NewT unePl  ayCal  1  BackUPP  (11-1123) 
functions. 


T  weenerDataProc 


A  callback  the  tween  component  calls  with  the  value  generated  by  a  tween 
operation. 

typedef  ComponentResul t  (*TweenerDataProcPtr)  (TweenRecord  *tr, 
void  *tweenData,  long  tweenDataSi ze ,  long  dataDescri pti onSeed , 

Handle  dataDescri pti on ,  ICMCompl eti onProcRecordPtr  asyncCompl eti onProc , 
Uni versal ProcPtr  transf erProc ,  void  *refCon); 


//  Declaration  of  a  typical  application-defined  function 


ComponentResul t  MyTweenerDataProc 
TweenRecord 
void 
1  ong 
1  ong 
Handl e 

ICMCompl eti onProcRecordPtr 

Uni versal ProcPtr 

void 


( 

*tr 

*tweenData 
tweenDataSi ze 
dataDescri pti onSeed 
dataDescri pti on 
asyncCompl eti onProc 
transferProc 
*refCon  ); 


CLB 


tr 

A  pointer  to  the  tween  record  for  the  tween  operation. 
tweenData 

A  pointer  to  the  generated  tween  value. 
tweenDataSi ze 

The  size,  in  bytes,  of  the  tween  value. 
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dataDescriptionSeed 

The  starting  value  for  the  calculation.  Every  time  the  content  of  the 
dataDescription  handle  changes,  this  value  should  be  incremented. 
dataDescri pti on 

Specifies  a  handle  containing  a  description  of  the  tween  value  passed.  For  basic 
types  such  as  integers,  the  calling  tween  component  should  set  this  parameter 
to  NIL.  For  more  complex  types  such  as  compressed  image  data,  the  calling 
tween  component  should  set  this  handle  to  contain  a  description  of  the  tween 
value,  such  as  an  image  description. 

asyncCompl etionProc 

A  pointer  to  a  completion  procedure  for  asynchronous  operations.  The  calling 
tween  component  should  set  the  value  of  this  parameter  to  NIL. 
transferProc 

A  pointer  to  a  procedure  to  transfer  the  data.  The  calling  tween  component 
should  set  the  value  of  this  parameter  to  NIL. 
refCon 

A  pointer  to  a  reference  constant.  The  calling  tween  component  should  set  the 
value  of  this  parameter  to  NIL. 

function  result  See  "Error  Codes"  (IV-2663).  Your  callback  should  return  noErr  if 
there  is  no  error. 


See  Also 

See  the  TweenRecord  (IV-2493)  and  TweenVIRecord  (IV-2495)  structures  and  the 
QTDoTween  (11-1165),  TweenerDoTween  (III — 1976),  and  NewTweenerDataUPP  (11-1123) 
functions. 


VdiglntProc 

An  interrupt  callback  called  by  the  video  digitizer  component  each  time  it  starts  to 
display  a  field. 

typedef  void  (*VdigIntProcPtr)  (long  flags,  long  refcon); 

//  Declaration  of  a  typical  appl i cati on -def i ned  function 
void  MyVdi glntProc  ( 
long  flags 
1  ong  refcon  ) ; 


fl  ags 

Undocumented 
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ref con 

A  reference  constant  that  the  client  code  supplies  to  your  callback.  You  can  use 
this  reference  to  point  to  a  data  structure  containing  any  information  your 
callback  needs. 

See  Also 

See  the  VDSetDi  gi  ti  zerUserlnterrupt  (III— 2039)  and  NewVdi  glntUPP  (11-1125) 
functions. 
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AliasRecord 


STR 


Defines  a  Mac  OS  alias  record. 

struct  AliasRecord  { 

OSType  userType; 

unsigned  short  aliasSize; 

}; 

userType 

A  4-byte  field  that  can  contain  application-specific  data,  such  as  the 
application's  signature.  When  the  alias  record  is  created,  this  field  contains  0. 

al  i as  Si ze 

The  size,  in  bytes,  assigned  to  the  alias  record  when  it  is  created  or  updated. 
The  size  includes  the  userType  and  al  i  asSi  ze  fields  plus  additional  data  that  is 
private  to  the  Mac  OS. 

Discussion 

The  two  declared  fields  of  the  AliasRecord  structure  are  followed  by  a 
variable-length  block  of  data  maintained  privately  by  the  Mac  OS.  Al  i  asRecord 
structures  may  be  used  inside  of  '  dref '  atoms  to  reference  other  movies. 

Version  Notes 

Originally  part  of  the  Mac  OS. 

Programming  Info 

C  interface  file:  Al  i  ases  .  h 

See  Also 

The  Al  i  asRecord  structure  is  created  by  QTNewAl  i  as  (11-1202).  For  information  about 
Mac  OS  aliases,  see  Inside  Macintosh:  Files  (listed  in  the  bibliography). 


ARGBColor 


Specifies  a  color  with  alpha,  red,  green,  and  blue  values. 

struct  ARGBColor  { 

unsigned  short  alpha; 

unsigned  short  red; 
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unsigned  short  green; 

unsigned  short  blue; 

}; 

al  pha 

Specifies  the  alpha  component  of  the  color, 
red 

Specifies  the  red  component  of  the  color, 
green 

Specifies  the  green  component  of  the  color. 

bl  ue 

Specifies  the  blue  component  of  the  color. 

Discussion 

This  structure  is  used  in  QuickTime  vector  graphics  and  other  other  graphics 
routines. 

Programming  Info 

C  interface  file:  ImageCodec.  h 


Audioinfo 


Deprecated.  Stores  information  for  Audi  oGetlnfo  (1-48). 

struct  Audioinfo  { 

1  ong 
1  ong 

unsigned  short 

}; 

capabi 1 i ti esFl ags 

Describes  a  device's  capabilities;  see  "Sound  Device  Features"  (IV-2692). 
reserved 

Reserved  by  Apple. 
numVol umeSteps 

The  number  of  significant  increments  between  minimum  and  maximum 
volume. 

Associated  Functions 

Audi  oGetlnfo  (1-48) 


capabi 1 i ti esFl ags  ; 
reserved ; 
numVol umeSteps ; 
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Programming  Info 

C  interface  file:  Sound .  h 


AudioSelection 


Deprecated. 

struct  AudioSelection  { 

long  unitType; 

UnsignedFixed  selStart; 

UnsignedFixed  selEnd; 

}; 

Associated  Functions 

SndStartFi  1  ePl  ay  (III — 1847) 

Programming  Info 

C  interface  file:  Sound .  h 


STR 


BandwidthManagementPrefsRecord 


Undocumented 

struct  BandwidthManagementPrefsRecord  { 

Boolean  overrideConnecti on Speed ForBandwi dth : 

}; 

overrideConnecti onSpeed ForBandwi dth 
Undocumented 


Programming  Info 

C  interface  file:  Movi  es  .  h 


BigEndianFixed 


Protects  a  big-endian  Fixed  value  from  being  changed  by  little-endian  code. 

struct  BigEndianFixed  { 

Fixed  bi gEndi anVal ue ; 

}; 


Inside  QuickTime:  Data  Structures 


IV-2161 


Data  Structures 
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bi gEndi anVal ue 
A  Fixed  value. 

Special  Considerations 

On  W indows,  BigEndianFixedis  defined  as  a  struct  that  contains  a  fixed  variable, 
which  causes  a  compiler  error  if  you  attempt  to  directly  access  the  variable.  In  effect, 
the  error  serves  as  a  reminder  to  endian-flip  the  variable. 

Programming  Info 

C  interface  file:  Endi  an .  h 


BigEndianLong 


Protects  a  big-endian  long  value  from  being  changed  by  little-endian  code. 

struct  BigEndianLong  { 

long  bi gEndi anVal ue ; 

}; 

bi gEndi anVal ue 
A  long  value. 

Programming  Info 

C  interface  file:  Endi  an .  h 


BigEndianOSType 


Protects  a  big-endian  OSType  value  from  being  changed  by  little-endian  code. 

struct  BigEndianOSType  { 

OSType  bi gEndi anVal ue ; 

1: 

bi gEndi anVal ue 

An  OSType  value. 


Programming  Info 

C  interface  file:  Endi  an .  h 


BigEndianShort 

Protects  a  big-endian  short  value  from  being  changed  by  little-endian  code. 


IV-2162 
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struct  Bi gEndi anShort  { 

short  bi gEndi anVal ue ; 

}; 

bi gEndi anVai ue 
A  short  value. 


Programming  Info 

C  interface  file:  Endi  an  .  h 


STR 


BigEndianUnsignedFixed 

Protects  a  big-endian  unsigned  Fixed  value  from  being  changed  by  little-endian 
code. 

struct  BigEndianUnsignedFixed  { 

Unsi gnedFi xed  bigEndianValue; 

}; 

bi gEndi anVal ue 

An  unsigned  Fixed  value. 

Programming  Info 

C  interface  file:  Endi  an  .  h 


BigEndianUnsignedLong 

Protects  a  big-endian  unsigned  long  value  from  being  changed  by  little-endian 
code. 

struct  BigEndianUnsignedLong  { 

unsigned  long  bigEndianValue; 

}; 

bi gEndi anVal ue 

An  unsigned  long  value. 

Programming  Info 

C  interface  file:  Endi  an .  h 
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BigEndianUnsignedShort 

Protects  a  big-endian  unsigned  short  value  from  being  changed  by  little-endian 
code. 

struct  BigEndianUnsignedShort  { 

unsigned  short  bi gEndi anVal ue ; 

}; 

bi gEndi anVal ue 

An  unsigned  short  value. 

Programming  Info 

C  interface  file:  Endi  an .  h 


BitMap 


Defines  a  bit  image  using  Macintosh  QuickDraw  coordinates. 

struct  BitMap  { 

Ptr  baseAddr; 

short  rowBytes; 

Rect  bounds: 

1: 

baseAddr 

A  pointer  to  the  beginning  of  the  bit  image. 
rowBytes 

The  offset  in  bytes  from  one  row  of  the  image  to  the  next.  This  value  may  not 
exceed  0x4000. 
bounds 

The  bitmap's  boundary  rectangle;  by  default,  the  whole  computer  screen. 

Discussion 

The  width  passed  in  the  bounds  parameter  determines  how  many  bits  of  one  row  are 
part  of  the  bitmap.  This  value  must  not  exceed  the  number  of  bits  in  each  row  of  the 
bit  image.  The  height  passed  in  the  bounds  parameter  determines  how  many  rows 
are  part  of  the  bitmap.  This  value  must  not  exceed  the  number  of  rows  in  the  bit 
image.  The  rectangle  passed  in  the  bounds  parameter  defines  the  local  coordinate 
system  used  by  the  portRect  field  of  the  Graf  Port  (IV-2273)  structure. 

Associated  Functions 

QDBitsProc  (III — 2113) 
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BooleanRangeRecord 


Programming  Info 

C  interface  file:  Quickdraw.h 


See  Also 

See  the  Rect  (IV-2399)  and  Pi  xMap  (IV-2332)  structures. 


BooleanRangeRecord 

Undocumented 

struct  BooleanRangeRecord  { 
long  maskValue; 

}; 

maskVal ue 

Undocumented 

Discussion 

Undocumented 

Programming  Info 

C  interface  file:  ImageCodec.  h 
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CallBackRecord 


Stores  data  for  a  QTCal  1  BackProc  (III— 2124). 

struct  CallBackRecord  { 
long  data [ 1  ] ; 

}; 

data 

Callback  data. 


Programming  Info 

C  interface  file:  Movi  es  .  h 


CDSequenceDataSource 


Contains  a  linked  list  of  all  data  sources  for  a  decompression  sequence. 

struct  CDSequenceDataSource  { 

long  recordSize; 
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Data  Structures 


CDSequenceDataSource 


voi  d  * 

ImageSequence 
ImageSequence Da taSource 
OSType 
1  ong 
voi  d  * 

Handl e 
i  ong 

ICMConvertDataFormatUPP 
voi  d  * 

1  ong 
QHdrPtr 
voi  d  * 

1  ong 
Handl e 
1  ong 

}; 

recordSi ze 

The  size  of  this  structure. 


next ; 
seqlD ; 
sourcelD ; 
sourceType ; 
sourcelnputNumber ; 
dataPtr ; 

dataDescri pti on ; 

changeSeed ; 

transferProc ; 

transferRefcon ; 

dataSi ze ; 

dataQueue ; 

ori gi nal DataPtr ; 

ori gi nal DataSi ze ; 

originalDataDescription; 

ori gi nal DataDescri pti onSeed; 


next 

A  pointer  to  the  next  source  entry.  If  it  is  N I L,  there  are  no  more  entries. 
seqlD 

The  image  sequence  that  this  source  is  associated  with. 
sourcelD 

The  source  reference  identifying  this  source. 
sourceType 

A  four-character  code  describing  how  the  input  will  be  used.  This  value  is 
passed  to  this  parameter  by  CDSequenceNewDataSource  (1-82)  when  the  source  is 
created. 

sourcelnputNumber 

A  value  is  passed  to  this  parameter  by  CDSequenceNewDataSource  when  the 
source  is  created. 
dataPtr 

A  pointer  to  the  actual  source  data. 
dataDescri pti on 

A  handle  to  a  data  structure  describing  the  data  format.  This  is  often  a  handle 
to  an  ImageDescri  pti  on  (IV-2285)  structure. 
changeSeed 

An  integer  that  is  incremented  each  time  the  dataPtr  field  changes  or  that  data 
that  the  dataPtr  field  points  to  changes.  By  remembering  the  value  of  this  field 
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CDSequenceDataSourceQueueEntry 


and  comparing  to  the  value  the  next  time  the  decompressor  or  compressor 
component  is  called,  the  component  can  determine  if  new  data  is  present. 

transferProc 
Reserved. 
transferRef con 
Reserved. 
dataSi ze 

The  size  of  the  data  pointed  to  by  the  dataPtr  field. 
dataQueue 

A  pointer  to  a  QHdr  (IV-2345)  structure  that  contains  a  queue  of 
CDSequenceDataSourceQueueEntry  (IV-2167)  structures. 

ori gi nal DataPtr 

The  original  value  of  dataPtr. 
ori  gi  nal DataSi ze 

The  original  value  of  dataSi  ze. 
ori gi nal DataDescri pti on 

The  original  value  of  dataDescri  pti  on. 
ori gi nal DataDescri pti onSeed 

The  original  value  ofchangeSeed. 

Discussion 

Because  each  data  source  is  associated  with  a  link  to  the  next  data  source,  a  codec 
can  access  all  data  sources  using  this  structure. 

Version  Notes 

Fields  from  dataQueue  onward  were  introduced  in  QuickTime  3. 

Associated  Functions 

ImageCodecGetMaxCompressi  onSi  zeWi  thSources  (11-716) 

Programming  Info 

C  interface  file:  ImageCodec.h 

See  Also 

See  CDSequenceDataSourceQueueEntry  (IV-2167). 


CDSequenceDataSourceQueueEntry 

Provides  data  for  CDSequenceDataSource  (IV-2165). 
struct  CDSequenceDataSourceQueueEntry  { 
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CGrafPort 


voi  d  * 

nextBusy ; 

1  ong 

descSeed ; 

Handl e 

dataDesc ; 

voi  d  * 

data ; 

1  ong 

dataSi ze ; 

1  ong 

useCount ; 

T i meVal ue 

f rameT i me ; 

T i meVal ue 

f rameDurati on 

T i meVal ue 

ti meScal e ; 

nextBusy 

Undocumented 

descSeed 

Undocumented 

dataDesc 

Undocumented 


data 

Undocumented 

dataSi ze 

Undocumented 

useCount 

Undocumented 

f rameT i me 

Undocumented 

f rameDurati on 

Undocumented 

ti meScal  e 

Undocumented 


Programming  Info 

C  interface  file:  ImageCodec.h 


See  Also 

See  CDSequenceDataSource  (IV-2165). 


CGrafPort 

Defines  a  complete  drawing  environment  for  color  graphics  operations, 
struct  CGrafPort  { 


IV-2168 
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CGrafPort 


short 

devi ce ; 

Pi xMapHandl e 

portPi xMap ; 

short 

portVersi on 

Handl e 

grafVars ; 

short 

chExtra  ; 

short 

pnLocHFrac ; 

Rect 

portRect ; 

RgnHandl e 

vi  sRgn ; 

RgnHandl e 

cl  i  pRgn ; 

Pi xPatHandl e 

bkPi xPat ; 

RGBCol or 

rgbFgCol or ; 

RGBCol or 

rgbBkCol or ; 

Poi  nt 

pnLoc ; 

Poi  nt 

pnSi ze ; 

short 

pnMode ; 

Pi xPatHandl e 

pnPi xPat ; 

Pi xPatHandl e 

fi  1 1  Pi  xPat ; 

short 

pnVi s  ; 

short 

txFont ; 

Styl eFi el d 

txFace ; 

short 

txMode ; 

short 

txSi ze ; 

Fi  xed 

spExtra  ; 

1  ong 

fgCol or ; 

1  ong 

bkCol  or ; 

short 

col rBi t ; 

short 

patStretch ; 

Handl e 

pi cSave ; 

Handl e 

rgnSave ; 

Handl e 

polySave; 

CQDProcsPtr 

graf Procs ; 

devi ce 

Device-specific  information  that  QuickDraw  uses  to  achieve  the  best  possible 
results  when  drawing  text  in  the  graphics  port.  There  may  be  physical 
differences  in  the  same  logical  font  for  different  output  devices,  to  ensure  the 
highest-quality  printing  on  the  device  being  used.  The  default  value  of  the 
device  field  is  0,  indicating  the  computer  screen. 
portPi xMap 

A  handle  to  a  P  i  xM  a  p  (IV-2332)  structure,  which  describes  the  pixels  in  this  color 
graphics  port. 
portVersi on 

The  highest  2  bits  are  permanently  set  to  indicate  that  this  is  a  CGrafPort 
structure  and  the  remai  nder  of  the  field  contains  the  version  number  of 
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CGrafPort 


Macintosh  Color  QuickDraw  that  created  this  structure.  Currently  initialized  to 
OxCOOO. 

grafVars 

A  handle  toaGrafVars  structure  that  contains  additional  graphics  fields  of  color 
information.  On  initialization,  black  is  assigned  to  the  rgbOpCol  or  field  of  this 
structure,  the  default  highlight  color  is  assigned  to  the  rgbHiliteColor  field, 
and  all  other  fields  are  set  to  0.  For  information  about  the  GrafVars  structure,  see 
Inside  Macintosh:  Imaging  With  QnickDrazv  (listed  in  the  bibliography). 

chExtra 

A  number  by  which  to  widen  every  character,  excluding  spaces,  in  a  line  of  text. 
This  value  is  used  in  proportional  spacing.  The  value  in  this  field  is  in  4.12 
fractional  notation:  4  bits  of  signed  integer  followed  by  12  bits  of  fraction.  This 
value  is  multiplied  by  the  value  in  the  txSi  ze  field  before  it  is  used.  By  default, 
this  field  contains  0. 
pnLocHFrac 

The  fractional  horizontal  pen  position  used  when  drawing  text.  The  value  in 
this  field  represents  the  low  word  of  type  Fixed;  in  decimal,  its  initial  value  is 
0.5. 

portRect 

The  port  rectangle  that  defines  a  subset  of  the  pixel  map  to  be  used  for  drawing. 
All  drawing  done  by  the  application  occurs  inside  the  port  rectangle.  The  port 
rectangle  (also  called  the  content  region)  uses  the  local  coordinate  system 
defined  by  the  boundary  rectangle  in  the  portPi  xMap  field  of  the  Pi  xMap 
structure.  The  upper-left  comer  (which  for  a  window  is  called  the  window 
origin)  of  the  port  rectangle  usually  has  vertical  and  horizontal  coordinates  of 
0.  The  port  rectangle  usually  falls  within  the  boundary  rectangle,  but  it's  not 
required  to  do  so. 

vi  sRgn 

The  region  of  the  graphics  port  that's  actually  visible  on  the  screen;  that  is,  the 
part  of  the  window  that's  not  covered  by  other  windows.  By  default,  the  visible 
region  is  equivalent  to  the  port  rectangle.  The  visible  region  has  no  effect  on 
images  that  aren't  displayed  on  the  screen, 
cl i pRgn 

A  handle  to  the  graphics  port's  clipping  region,  an  arbitrary  region  that  you  can 
use  to  limit  drawing  to  any  region  within  the  port  rectangle.  Unlike  the  visible 
region,  the  clipping  region  affects  the  image  even  if  it  isn't  displayed  on  the 
screen.  Initially  the  clip  region  is  set  to  the  rectangle  -32768,  -32768,  32767, 
32767. 
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CGrafPort 


bkPi xPat 

A  handle  to  a  Pi  xPat  (IV-2336)  structure  that  describes  the  background  pixel 
pattern,  initially  set  to  white. 
rgbFgCol or 

An  RGBCol  or  (IV-2403)  structure  that  defines  the  requested  foreground  color. 
By  default,  the  foreground  color  is  black. 

rgbBkCol or 

An  RGBCol  or  (IV-2403)  structure  that  defines  the  requested  background  color.  By 
default,  the  background  color  is  white. 
pnLoc 

The  point  where  QuickTime  will  begin  drawing  the  next  line,  shape,  or 
character.  It  can  be  anywhere  on  the  coordinate  plane;  there  are  no  restrictions 
on  the  movement  or  placement  of  the  pen.  The  location  of  the  graphics  pen  is  a 
point  in  the  graphics  port's  coordinate  system,  not  a  pixel  in  a  pixel  image.  The 
upper-left  corner  of  the  pen  is  at  the  pen  location;  the  graphics  pen  hangs  below 
and  to  the  right  of  this  point.  This  field  is  initialized  to  0,0. 
pnSi ze 

The  vertical  height  and  horizontal  width  of  the  graphics  pen.  The  default  size 
is  a  1-by-l  pixel  square;  the  vertical  height  and  horizontal  width  can  range  from 
0  by  0  to  32,767  by  32,767.  If  either  the  pen  width  or  the  pen  height  is  0,  the  pen 
does  not  draw.  Heights  or  widths  of  less  than  0  are  undefined. 

pnMode 

The  pattern  mode,  a  Boolean  operation  that  determines  the  how  QuickTime 
transfers  the  pen  pattern  to  the  pixel  map  during  drawing  operations.  See 
"Graphics  Transfer  Modes"  (IV-2670).  When  the  graphics  pen  draws  into  a 
pixel  map,  QuickTime  first  determines  what  pixels  in  the  pixel  image  are 
affected  and  finds  their  corresponding  pixels  in  the  pen  pattern.  It  then  does  a 
pixel-by-pixel  comparison  based  on  the  pattern  mode,  which  specifies  one  of 
eight  Bool  ean  transfer  operations  to  perform.  QuickTime  stores  the  resulting 
pixel  in  its  proper  place  in  the  image.  This  field  is  initially  set  to  patCopy. 
pnPi xPat 

A  handle  to  a  Pi  xPat  (IV-2336)  structure  that  describes  a  pixel  pattern  that  can 
be  used  like  the  ink  in  the  graphics  pen.  This  field  is  initially  set  to  black, 
f  i  1 1  Pi  xPat 

A  handle  to  a  Pi  xPat  (IV-2336)  structure  that  describes  the  pixel  pattern  that's 
used  to  fill  an  area.  This  field  is  initially  set  to  black.  Notice  that  this  is  not  in  the 
same  location  as  the  f  i  1 1  Pat  field  in  the  GrafPort  (IV-2273)  structure. 
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CGrafPort 


pnVi  s 

The  graphics  pen's  visibility;  that  is,  whether  or  not  it  draws  on  the  screen.  This 
field  is  initially  set  to  0  (visible). 
txFont 

A  font  number  that  identifies  the  font  to  be  used  in  the  graphics  port.  This  field 
is  initially  set  to  0,  indicating  the  system  font. 

txFace 

The  character  style  of  the  text,  with  values  from  the  set  defined  by  the  Style 
type,  which  includes  such  styles  as  bold,  italic,  and  shaded.  You  can  apply 
stylistic  variations  either  alone  or  in  combination.  This  field  is  initially  set  to 
plain  text. 
txMode 

One  of  three  Bool  ean  source  mode  constants  (see  below)  that  determines  the 
way  characters  are  placed  in  the  bit  image.  This  mode  functions  much  like  a 
pattern  mode  specified  in  the  pnMode  field;  when  drawing  a  character, 
QuickTime  determines  which  pixels  in  the  image  are  affected,  does  a 
pixel-by-pixel  comparison  based  on  the  mode,  and  stores  the  resulting  pixels  in 
the  image.  This  field  is  initially  set  to  srcOr. 
txSi ze 

The  text  size  in  pixels.  QuickTime  uses  this  information  to  provide  the  bitmaps 
for  text  drawing.  The  txSi  ze  value  can  be  represented  by  the  formula  (size  in 
points)  x  (device  resolution)  /  72  dpi.  This  field  is  initially  set  to  the  system  font 
size. 

spExtra 

A  number  equal  to  the  average  number  of  pixels  by  which  each  space  character 
should  be  widened  to  fill  out  a  fully  justified  text  line.  This  field  is  useful  when 
a  line  of  characters  is  to  be  aligned  with  both  the  left  and  the  right  margin.  This 
field  is  initially  set  to  0. 
fgCol or 

The  pixel  value  of  the  foreground  color.  This  is  the  best  available 
approximation  in  the  color  lookup  table  (CLUT)  to  the  color  specified  in  the 
rgbFgCol  or  field.  This  field  is  initially  set  to  bl  ackCol  or;  see  "Color  Constants" 
(IV-2657). 
bkCol or 

The  pixel  value  of  the  backgroundcolor.  This  is  the  best  available  approximation 
in  the  color  lookup  table  (CLUT)  to  the  color  specified  in  the  rgbBkCol  or  field. 
This  field  is  initially  set  to  whi  teCol  or;  see  "Color  Constants"  (IV-2657). 
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col rBi t 

Reserved  and  set  to  0. 
patStretch 

A  value,  initially  set  to  0,  used  during  output  to  a  printer  to  expand  patterns  if 
necessary.  Your  application  should  not  change  this  value. 

pi cSave 

A  handle  to  the  state  of  the  Macintosh  picture  definition.  If  no  picture  is  open, 
this  field  contains  N I L;  otherwise  it  contains  a  handle  to  information  related  to 
the  picture  definition.  Your  application  shouldn't  be  concerned  about  exactly 
what  information  the  handle  leads  to;  you  may,  however,  save  the  current 
value  of  this  field,  set  the  field  to  N I L  to  disable  the  picture  definition,  and  later 
restore  it  to  the  saved  value  to  resume  defining  the  picture. 
rgnSave 

A  handle  to  the  state  of  the  region  definition.  If  no  region  is  open,  this  field 
contains  NIL;  otherwise  it  contains  a  handle  to  information  related  to  the  region 
definition.  Your  application  shouldn't  be  concerned  about  exactly  what 
information  the  handle  leads  to;  you  may,  however,  save  the  current  value  of 
this  field,  set  the  field  to  N I L  to  disable  the  region  definition,  and  later  restore  it 
to  the  saved  value  to  resume  defining  the  region. 
polySave 

A  handle  to  the  state  of  the  polygon  definition.  If  no  polygon  is  open,  this  field 
contains  NIL;  otherwise  it  contains  a  handle  to  information  related  to  the 
polygon  definition.  Your  application  shouldn't  be  concerned  about  exactly 
what  information  the  handle  leads  to;  you  may,  however,  save  the  current 
value  of  this  field,  set  the  field  to  N I L  to  disable  the  polygon  definition,  and  later 
restore  it  to  the  saved  value  to  resume  defining  the  polygon. 

graf Procs 

An  optional  pointer  to  a  CQDProcs  (IV-2226)  structure  that  your  application  can 
store  into  if  you  want  to  customize  Color  QuickDraw  drawing  routines  or  use 
Color  QuickDraw  in  other  advanced,  highly  specialized  ways.  This  field  is 
initially  set  to  NIL. 

txMode  Constants 

srcOr 

If  the  source  pixel  is  black,  apply  the  foreground  color.  If  the  source  pixel  is 
white,  leave  it  white.  If  the  source  pixel  is  any  other  color,  apply  weighted 
portions  of  foreground  color. 

srcXor 

If  the  source  pixel  is  black,  invert  the  color  (undefined  for  a  colored  destination 
pixel).  If  the  source  pixel  is  white  or  any  other  color,  leave  the  color  as  is. 
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CleanAperturelmageDescriptionExtension 


srcBi c 

If  the  source  pixel  is  black,  apply  the  background  color.  If  the  source  pixel  is 
white,  leave  the  color  as  is.  If  the  source  pixel  is  any  other  color,  apply  weighted 
portions  of  the  background  color. 

Discussion 

You  can  have  many  graphics  ports  open  at  once;  each  one  has  its  own  local 
coordinate  system,  pen  pattern,  background  pattern,  pen  size  and  location,  font  and 
font  style,  and  pixel  map  in  which  drawing  takes  place.  Several  fields  in  this 
structure  define  your  application's  drawing  area.  All  drawing  in  a  graphics  port 
occurs  in  the  intersection  of  the  graphics  port's  boundary  rectangle  and  its  port 
rectangle.  Within  that  intersection,  all  drawing  is  cropped  to  the  graphics  port's 
visible  region  and  its  clipping  region. 

Special  Considerations 

Before  a  color  graphics  port  defined  byCGrafPort  can  be  used,  it  must  be  allocated 
and  initialized.  Once  a  CGraf  Port  is  initialized  you  can  read  its  fields  directly,  but 
you  should  not  store  values  directly  into  them.  You  must  use  QuickTime  functions 
to  alter  the  contents  of  a  CGraf  Port  structure. 

Version  Notes 

The  CGrafPort  structure  supersedes  the  earlier  GrafPort  (IV-2273)  structure. 

Programming  Info 

C  interface  file:  Quickdraw.h 


CleanAperturelmageDescriptionExtension 


An  extension  to  ImageDescription  (IV-2285)  that  describes  the  dimensions  of  a  clean 
aperture. 

struct  Cl eanAperturelmageDescri pti onExtensi on  { 


UInt32 

cleanApertureWidthN; 

UInt32 

cleanApertureWidthD; 

UInt32 

cleanApertureHeightN; 

UInt32 

cleanApertureHeightD; 

UInt32 

hori zOff N ; 

UInt32 

hori zOff D ; 

UInt32 

vertOff N ; 

UInt32 

vertOff D ; 

}; 


cleanApertureWidthN 
Width  numerator. 
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cl eanApertureWi dthD 
Width  denominator, 
cl eanApertureHei ghtN 
Height  numerator, 
cl eanApertureHei ghtD 
Height  denominator 
hori zOf f N 

Numerator  of  horizontal  offset  of  clean  aperture  center  minus  (width-1  )/2. 
hori zOf f D 

Denominator  of  horizontal  offset  of  clean  aperture  center  minus  (width-l)/2. 
vertOf fN 

Numerator  of  vertical  offset  of  clean  aperture  center  minus  (height-1)/ 2. 
vertOf f D 

Denominator  of  vertical  offset  of  clean  aperture  center  minus  (height-l)/2. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

See  Also 

See  ImageDescri  pti  on  (IV-2285). 
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CloneRecord 


Defines  a  track  clone. 

struct  CloneRecord  { 
long  flags; 

long  masterTrackID; 

}; 

fl  ags 

Currently  0. 
masterTrackID 

The  track  ID  of  the  track  being  cloned. 

Programming  Info 

C  interface  file:  Movi  es Format .  h 


See  Also 

Seethe  'cion'  (-' cl  on ')  atom  and  AddClonedTrackToMovie  (1-22). 
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CmpSoundHeader 


Describes  compressed  sampled-sound  data, 
struct  CmpSoundHeader  { 


Ptr 

sampl ePtr ; 

unsigned  long 

numChannel s ; 

Unsi gnedFi xed 

sampl eRate ; 

unsigned  long 

1 oopStart ; 

unsigned  long 

1 oopEnd ; 

UInt8 

encode ; 

UInt8 

baseFrequency ; 

unsigned  long 

numFrames ; 

extended80 

AI FFSampl eRate ; 

Ptr 

markerChunk; 

OSType 

format ; 

unsigned  long 

f utureUse2 ; 

StateBl ockPtr 

stateVars ; 

LeftOverBl ockPtr 

1 eftOverSampl es 

short 

compressionID; 

unsigned  short 

packetSi ze ; 

unsigned  short 

snthID; 

unsigned  short 

sampl eSi ze ; 

UInt8 

sampl eArea[l]  ; 

sampl ePtr 

The  location  of  the  compressed  sound  frames.  If  sampl  ePtr  is  N I L,  then  the 
frames  are  located  in  the  sampl  eArea  field  of  the  compressed  sound  header. 
Otherwise,  sampl  ePtr  points  to  a  buffer  that  contains  the  frames. 

numChannel s 

The  number  of  channels  in  the  sample, 
sampl eRate 

The  sample  rate  at  which  the  frames  were  sampled  before  compression;  see 
"Sound  Sample  Rates"  (IV-2695). 

1 oopStart 

The  beginning  of  the  loop  points  of  the  sound  before  compression.  The  loop 
starting  and  ending  points  are  0-based. 

1 oopEnd 

The  end  of  the  loop  points  of  the  sound  before  compression, 
encode 

The  method  of  encoding  (if  any)  used  to  generate  the  sampled-sound  data  (see 
below).  For  a  compressed  sound  header,  you  should  specify  the  constant  cmpSH. 
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Encode  option  values  in  the  ranges  0  through  63  and  128  to  255  are  reserved  for 
use  by  Apple.  You  are  free  to  use  numbers  in  the  range  64  through  127  for  your 
own  encode  options. 
baseFrequency 

The  pitch  of  the  original  sampled  sound. 
numFrames 

The  number  of  frames  contained  in  the  compressed  sound  header.  When  you 
store  multiple  channels  of  noncompressed  sound,  store  them  as  interleaved 
sample  frames  (as  in  AIFF).  When  you  store  multiple  channels  of  compressed 
sounds,  store  them  as  interleaved  packet  frames. 

AI FFSampl eRate 

The  sample  rate  at  which  the  frames  were  sampled  before  compression,  as 
expressed  in  the  80-bit  extended  data  type  representation  (IEEE  sample  rate). 

markerChunk 

Synchronization  information.  The  markerChunk  field  is  not  presently  used  and 
should  be  set  to  NIL. 

format 

The  data  format  type;  see  "Sound  Formats"  (IV-2692).  This  field  contains  a 
value  of  type  OS  Type  that  defines  the  compression  algorithm,  if  any,  used  to 
generate  the  audio  data.  For  example,  for  data  generated  using  MACE  3:1 
compression,  this  field  should  contain  the  value  '  MAC3 ' .  This  field  is  used  only 
if  the  comp  res  si  on  ID  field  contains  the  value  f  i  xedCompressi  on. 
f utureUse2 

This  field  is  reserved  for  use  by  Apple.  To  maintain  compatibility  with  future 
versions  of  system  software,  you  should  always  set  this  field  to  0. 

stateVars 

A  pointer  toaStateBlock  (IV-2463)  structure.  This  field  is  used  to  store  the  state 
variables  for  a  given  algorithm  across  consecutive  calls. 

1 eftOverSampl es 

A  pointer  to  a  Lef tOverBi  ock  (IV-2301)  structure.  You  can  use  this  block  to  store 
samples  that  will  be  truncated  across  algorithm  invocations, 
compressi onID 

The  compression  algorithm  used  on  the  samples  in  the  compressed  sound 
header  (see  below).  The  constant  ft  xedCompressi  on  is  available  only  with  Sound 
Manager  versions  3.0  and  later.  If  the  compressi  onID  field  contains  the  value 
f  i  xedCompressi  on,  the  Sound  Manager  reads  the  format  field  to  determine  the 
compression  algorithm  used  to  generate  the  compressed  data.  Otherwise,  the 
Sound  Manager  reads  the  compressi  onID  field.  Apple  reserves  the  right  to  use 
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compression  IDs  in  the  range  0  through  511.  Currently  the  constant 
vari  abl  eCompressI on  is  not  used  by  the  Sound  Manager. 

packetSi ze 

The  size,  in  bits,  of  the  smallest  element  that  a  given  expansion  algorithm  can 
work  with  (see  below).  Beginning  with  Sound  Manager  version  3.0,  you  can 
specify  the  value  0  in  this  field  to  instruct  the  Sound  Manager  to  determine  the 
packet  size  itself. 

snthID 

Resource  ID  of  the  Sound  Manager  synthesizer  that  contains  NRT  compression/ 
expansi  on.  If  this  field  is  not  used,  set  it  to  0. 
sampl eSi ze 

The  size  of  the  sample  before  it  was  compressed.  The  samples  passed  in  the 
compressed  sound  header  should  always  be  byte-aligned,  and  any  padding 
done  to  achieve  byte  alignment  should  be  done  from  the  left  with  zeros. 

sampl eArea 

The  sample  frames,  but  only  when  the  sampl  ePtr  field  is  NIL.  Otherwise,  the 
sample  frames  are  in  the  location  indicated  by  sampl  ePtr. 

encode  Constants 

cmpSH 

Compressed  sound  header;  value  is  OxFE. 
extSH 

Extended  sound  header;  value  is  OxFF. 
stdSH 

Standard  sound  header;  value  is  0x00. 

compressionID  Constants 

vari abl eCompressi on 

Variable-ratio  compression;  value  is  -2. 
f i xedCompressi on 

Fixed-ratio  compression;  value  is  -1. 
notCompressed 

Uncompressed  samples;  value  is  0. 
threeToOne 

3:1  compressed  samples;  value  is  3. 
sixToOne 

6:1  compressed  samples;  value  is  4 
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packetSize  Constants 

si xToOne Packet Si  ze 

Size  for  6:1  compression;  value  is  8. 
threeToOne Packet Si ze 

Size  for  3:1  compression;  value  is  16. 

Discussion 

Compressed  sound  headers  include  all  of  the  essential  fields  of  ExtSoundHeader 
(IV-2255)  in  addition  to  several  fields  that  pertain  to  compression. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

See  ExtSoundHeader  (IV-2255). 
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Lets  image  compressor  components  report  their  capabilities  to  the  Image 
Compression  Manager. 

struct  CodecCapabilities  { 
long  flags; 

short  wantedPixel Si ze ; 

short  extendWidth; 

short  extendHei ght ; 

short  bandMin; 

short  bandlnc; 

short  pad; 

unsigned  long  time; 
long  f 1  a  gs  2 ; 

}; 

fl  ags 

Contains  flags  (see  below)  that  contain  control  information  used  by  both  the 
Image  Compression  Manager  and  the  compressor  component. 
wantedPi xel Si ze 

Indicates  the  pixel  depth  the  component  can  use  with  the  specified  image.  The 
component  determines  the  pixel  depth  of  the  image  for  the  operation  by 
examining  the  appropriate  pixel  map. 
extendWi dth 

Specifies  the  number  of  pixels  the  image  must  be  extended  in  width.  If  the 
component  cannot  accommodate  the  image  at  its  given  width,  the  component 
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may  request  that  the  Image  Compression  Manager  extend  the  width  of  the 
image  by  adding  pixels  to  the  right  edge  of  the  image.  This  is  sometimes 
necessary  to  accommodate  the  component's  block  size. 
extendHei ght 

Specifies  the  number  of  pixels  the  image  must  be  extended  in  height.  If  the 
component  cannot  accommodate  the  image  at  its  given  height  the  component 
may  request  that  the  Image  Compression  Manager  extend  the  height  of  the 
image  by  adding  pixels  to  the  bottom  of  the  image.  This  is  sometimes  necessary 
to  accommodate  the  component's  block  size. 

bandMi n 

Contains  the  minimum  image  band  height  supported  by  the  component. 
Components  that  can  tolerate  small  values  operate  under  a  wider  set  of 
memory  conditions, 
bandlnc 

Specifies  a  common  factor  of  supported  image  band  heights.  A  component  may 
support  only  image  bands  that  are  an  even  multiple  of  some  number  of  pixels 
high.  These  components  report  this  common  factor  in  the  bandlnc  field.  Set  this 
field  to  1  if  your  component  supports  bands  of  any  size. 

pad 

Reserved  for  use  by  Apple. 

time 

Indicates  the  number  of  milliseconds  the  operation  will  take  to  complete.  If  the 
compressor  cannot  determine  this  value,  it  sets  this  field  to  0. 
f  1  ags2 

Additional  compressor  capability  flags  (see  below). 

flags  Constants 

codecCanScal e 

Indicates  whether  the  decompressor  can  scale  the  image  during 
decompression.  The  decompressor  sets  this  flag  to  1  to  indicate  that  it  can  scale 
the  image  during  decompression.  The  decompressor  sets  this  flag  to  0  if  it 
cannot  scale  the  decompressed  image. 
codecCanMask 

Indicates  whether  the  decompressor  can  apply  a  mask  to  the  decompressed 
image.  The  decompressor  sets  this  flag  to  1  to  indicate  that  it  can  use  a  mask  to 
control  the  image  that  results  from  a  decompression  operation.  The 
decompressor  sets  this  flag  to  0  if  it  cannot  work  with  masks. 
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codecCanMatte 

Indicates  whether  the  decompressor  can  blend  the  decompressed  image  using 
a  matte.  The  decompressor  sets  this  flag  to  1  to  indicate  that  it  can  use  a  blend 
matte  during  decompression.  The  decompressor  sets  this  flag  to  0  if  it  cannot 
use  a  blend  matte. 
codecCanTransf orm 

Indicates  whether  the  decompressor  can  work  with  complex  placement 
matrixes.  The  decompressor  sets  this  flag  to  1  to  indicate  that  it  can  work  with 
transformation  matrixes  during  decompression.  The  decompressor  sets  this 
flag  to  0  if  it  cannot  work  with  matrixes. 

codecCanTransferMode 

Indicates  whether  the  decompressor  can  accept  a  transfer  mode  other  than 
source  copy  or  dither  copy  when  displaying  a  decompressed  image.  The 
decompressor  sets  this  flag  to  1  to  indicate  that  it  can  accept  transfer  modes; 
otherwise,  the  decompressor  sets  this  flag  to  0. 
codecCanCopyPrev 

Indicates  whether  the  compressor  can  update  the  previous  image  buffer  during 
sequence  compression.  The  compressor  sets  this  flag  to  1  to  indicate  that  it  can 
update  the  previous  image  buffer.  The  compressor  sets  this  flag  to  0  if  it  cannot 
update  the  buffer. 
codecCanSpool 

Indicates  whether  the  component  can  use  data-loading  and  data-unloading 
functions  to  spool  data  during  decompression  and  compression  operations, 
respectively.  Applications  may  define  data-loading  and  data-unloading 
functions  to  handle  images  that  cannot  fit  into  memory.  See  the  chapter  "Image 
Compression  Manager"  in  Inside  Macintosh:  QuickTime  (listed  in  the 
bibliography)  for  more  information  on  data-loading  and  data-unloading 
functions.  The  component  sets  this  flag  to  1  to  indicate  that  it  can  use  these 
functions.  The  component  sets  this  flag  to  0  to  indicate  that  it  cannot  use  these 
functions. 

codecCanCl i pVerti cal 

Indicates  whether  the  decompressor  can  clip  an  image  vertically  during 
decompression.  The  decompressor  sets  this  flag  to  1  to  indicate  that  it  can  clip 
an  image  vertically.  The  decompressor  sets  this  flag  to  0  to  indicate  that  it 
cannot  clip  an  image  vertically. 
codecCanCl i pRectangul a r 

Indicates  whether  the  decompressor  can  clip  both  vertically  and  horizontally 
during  decompression.  The  decompressor  sets  this  flag  to  1  to  indicate  that  it 
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can  clip  along  both  axes.  The  decompressor  sets  this  flag  to  0  to  indicate  that  it 
cannot  clip  an  image  both  vertically  and  horizontally. 

codecCanRemapCol or 

Indicates  whether  the  compressor  can  remap  the  colors  for  an  image  using  color 
tables.  The  compressor  sets  this  flag  to  1  if  it  can  remap  colors.  The  compressor 
sets  this  flag  to  0  if  it  cannot  remap  colors. 

codecCanFastDither 

Indicates  whether  the  compressor  supports  fast  dithering.  The  compressor  sets 
this  flag  to  1  if  it  supports  fast  dithering.  The  compressor  sets  this  flag  to  0  if  it 
does  not  support  fast  dithering.  See  the  chapter  "Image  Compression 
Manager"  in  Inside  Macintosh:  QuickTime  (listed  in  the  bibliography)  for  more 
information  about  fast  dithering. 
codecCanSrc Extract 

Indicates  whether  the  compressor  can  extract  a  portion  of  the  source  image.  The 
compressor  sets  this  flag  to  1  if  it  can  extract  a  portion  of  the  source  image.  The 
compressor  sets  the  flag  to  0  if  it  cannot. 

codecCanCopyPrevComp 

Indicates  whether  the  compressor  can  update  the  previous  image  buffer  during 
sequence  compression  using  compressed  data.  The  compressor  sets  this  flag  to 
1  to  indicate  that  it  can  update  the  previous  image  buffer.  The  compressor  sets 
this  flag  to  0  if  it  cannot  update  the  buffer. 

codecCanAsync 

Indicates  whether  the  component  can  work  asynchronously.  The  compressor 
sets  this  flag  to  1  if  it  can  compress  and  decompress  asynchronously;  otherwise, 
it  sets  this  flag  to  0. 
codecCanMakeMask 

Indicates  whether  the  decompressor  creates  modification  masks  during 
decompression.  These  masks  indicate  which  pixels  in  the  decompressed  image 
differ  from  the  previous  image  and  must  therefore  be  displayed.  Such  masks 
are  useful  only  when  processing  sequences.  The  decompressor  sets  this  flag  to 
1  to  indicate  that  it  creates  modification  masks.  The  decompressor  sets  this  flag 
to  0  if  it  does  not  create  such  masks. 

codecCanShi ft 

Indicates  whether  the  component  can  work  with  pixels  that  are  not 
byte-aligned.  This  flag  is  valid  only  when  the  source  or  destination  uses  fewer 
than  8  bits  per  pixel.  Components  set  this  flag  to  1  if  they  can  read  or  write 
pixels  that  are  not  byte-aligned.  Components  set  this  flag  to  0  if  pixels  must  be 
byte-aligned. 
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codecCanAsyncWhen 

Indicates  whether  your  decompressor  component  supports  scheduled 
asynchronous  decompression.  Set  this  flag  to  1  if  your  component  can  support 
the  scheduling  functionality  of  ImageCodecBandDecompress  (11-689).  Note  that 
you  must  also  set  the  codecCanAsync  flag  to  1. 

codecCanShieldCursor 

Indicates  whether  your  decompressor  component  will  manage  the  shielding  of 
the  cursor  during  decompression.  If  your  component  can  manage  the  cursor's 
display,  set  this  flag  to  1.  Your  component  can  use  ICMShi  el  dSequenceCursor 
(11-679)  to  shield  the  cursor.  The  cursor  is  automatically  unshielded  when  you 
call  ICMDecompressCompl  ete  (11-671).  Otherwise,  set  this  flag  to  0;  the  Image 
Compression  Manager  then  manages  the  cursor  for  you.  It  is  highly 
recommended  that  you  support  this  capability  if  your  decompressor  supports 
asynchronous  operation  or  the  cursor  may  remain  shielded  for  unacceptably 
long  periods  of  time. 

codecCanManagePrevBuffer 

Indicates  that  your  compressor  component  is  capable  of  allocating  and 
managing  the  prevPi  xMap  used  in  temporal  compression.  If  this  flag  is  set,  then 
your  compressor  must  determine  when  to  update  the  prevPi  xMap  during 
compression  sequences.  Codecs  setting  this  flag  should  also  set 
codecCanCopyPrev. 

codecHasVolatileBuffer 

Some  hardware  decompressors  don't  actually  draw  the  decompressed  pixels 
into  the  frame  buffer  as  requested  by  QuickTime.  Instead,  they  have  a  second 
frame  buffer  that  floats  or  overlays  above  the  main  frame  buffer.  The  image  is 
decompressed  into  this  secondary  frame  buffer  instead.  To  the  user,  the  effect 
is  the  same  because  the  video  hardware  merges  the  two  frame  buffers  together. 
When  the  window  that  contains  the  image  is  moved  to  another  location  in  the 
same  screen  buffer,  the  Window  Manager  uses  CopyBi  ts  to  transfer  the 
window's  pixels  from  the  old  location  to  the  new  location.  Unfortunately, 
because  the  Window  Manager  is  unaware  of  the  presence  of  the  secondary 
frame  buffer,  it  cannot  move  the  image  it  is  displaying.  By  setting  the 
codecHasVolatileBuffer  flag  to  1,  the  decompressor  component  informs 
QuickTime  that  it  uses  a  secondary  frame  buffer.  When  the  Window  Manager 
moves  a  window,  QuickTime  forces  a  redraw  of  the  contents  of  the  window  so 
that  the  secondary  frame  buffer  can  be  repositioned  and/or  updated  as 
necessary. 
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codecImageBufferlsOnScreen 

By  setting  the  codecImageBufferlsOnScreen  flag  to  1,  the  decompressor 
component  informs  QuickTime  that  it  is  a  direct  screen  transfer  codec.  Codecs 
that  use  ImageCodecNewImageBufferMemory  (11-727)  to  create  an  offscreen  buffer 
that  is  really  onscreen  would  set  this  flag. 
codecWantsSpecial Scaling 

Specifies  to  use  an  image  buffer  whose  size  is  determined  by  the 
requestedBufferWi  dth  and  requestedBuf  ferHei  ght  fields  in 
CodecDecompressParams  (IV-2190)  or  CodecCompressParams  (IV-2184). 

codecWantsDestinationPixels 

Undocumented 

Discussion 

Before  compressing  or  decompressing  an  image,  the  Image  Compression  Manager 
requests  capability  information  from  the  component  that  will  be  handling  the 
operation  by  calling  ImageCodecPreCompress  (11-730)  or  ImageCodecPreDecompress 
(11-731).  The  compressor  component  examines  the  compression  or  decompression 
parameters  and  indicates  any  restrictions  on  its  ability  to  satisfy  the  request  in  a 
formatted  compressor  capability  structure.  The  Image  Compression  Manager  then 
manages  the  operation  according  to  the  capabilities  of  the  component. 

Programming  Info 

C  interface  file:  ImageCodec.h 
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Contains  parameters  that  govern  a  compression  operation. 


struct  CodecCompressParams  { 
ImageSequence 
ImageDescriptionHandle 
Ptr 
1  ong 
1  ong 
1  ong 
1  ong 
1  ong 

CodecFl ags 
CodecCapabi 1 i ti es  * 
ICMProgressProc Record 
ICMCompl etionProc Record 
I  CM  FI ushProcRecord 
Pi xMap 


sequencelD; 
i mageDescri pti on  ; 
data ; 

bufferSi ze ; 
f rameNumber ; 
startin'  ne ; 
stopLi  ne ; 
condi  ti  onFl  ags  ; 
cal  1  erFl  ags  ; 
capabi 1 i ti es  ; 
progressProc Record; 
compl etionProc Record: 
f 1 ushProcRecord ; 
srcPixMap; 
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Pi xMap 
CodecQ 
CodecQ 
Fi  xed 

DataRateParamsPtr 

1  ong 

UIntl6 

UIntl6 

CDSequenceDataSourcePtr 

1  ong 

1  ong 

1  ong 

OSType 

1  ong 

UInt32 

OSType 


prevPi xMap ; 
spati al Qual i ty ; 
temporal Qual i ty ; 
si  mi  1 ari ty ; 
dataRateParams ; 
reserved ; 

ma jorSourceChangeSeed ; 
mi norSourceChangeSeed ; 
sourceData ; 

prefer red  Packet Si ze In Bytes  ; 
requested But ferWi dth  ; 
requested But f erHei ght ; 
wan ted Source Pi xel Type ; 
compressed Data  Si ze ; 
taskWeight; 
taskName; 


sequencelD 

Contains  a  unique  sequence  identifier.  If  the  image  to  be  compressed  is  part  of 
a  sequence,  this  field  contains  the  sequence  identifier  that  was  assigned  by 
CompressSequenceBegi  n  (1-119).  If  the  image  is  not  part  of  a  sequence,  this  field 
is  set  to  0. 
i mageDescri pti on 

Contains  a  handle  to  the  image  description  structure  that  describes  the  image 
to  be  compressed. 

data 

Points  to  a  location  to  receive  the  compressed  image  data.  This  is  a  32-bit  clean 
address.  If  there  is  not  sufficient  memory  to  store  the  compressed  image,  the 
application  may  choose  to  write  the  compressed  data  to  mass  storage  during 
the  compression  operation.  The  fl  ushProcRecord  field  identifies  the 
data-unloading  function  that  the  application  provides  for  this  purpose.  This 
field  is  used  only  by  ImageCodecBandCompress  (11-688). 

but f erSi ze 

Contains  the  size  of  the  buffer  specified  by  the  data  field.  Your  component  sets 
the  value  of  the  buffers ize  field  to  the  number  of  bytes  of  compressed  data 
written  into  the  buffer.  Your  component  should  not  return  more  data  than  the 
buffer  can  hold;  it  should  return  a  nonzero  result  code  instead.  This  field  is  used 
only  by  ImageCodecBandCompress  (11-688). 
f rameNumber 

Contains  a  frame  identifier.  Indicates  the  relative  frame  number  within  the 
sequence.  The  Image  Compression  Manager  increments  this  value  for  each 
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frame  in  the  sequence.  This  field  is  used  only  by  ImageCodecBandCompress 
(11-688). 
startin'  ne 

Contains  the  starting  line  for  the  band.  This  field  indicates  the  starting  line 
number  for  the  band  to  be  compressed.  The  line  number  refers  to  the  pixel  row 
in  the  image,  starting  from  the  top  of  the  image.  The  first  row  is  row  number  0. 
This  field  is  used  only  by  ImageCodecBandCompress  (11-688). 

stopLi  ne 

Contains  the  ending  line  for  the  band.  This  field  indicates  the  ending  line 
number  for  the  band  to  be  compressed.  The  line  number  refers  to  the  pixel  row 
in  the  image,  starting  from  the  top  of  the  image.  The  first  row  in  the  image  is 
row  number  0.  The  image  band  includes  the  row  specified  by  this  field.  So,  to 
define  a  band  that  contains  one  row  of  pixels  at  the  top  of  an  image,  you  set  the 
startin'  ne  field  to  0  and  the  stopLi  ne  field  to  1. 
condi ti onFl ags 

Contains  flags  (see  below)  that  identify  the  condition  under  which  your 
component  has  been  called.  This  field  is  used  only  by  ImageCodecBandCompress 
(11-688).  In  addition,  these  fields  contain  information  about  actions  taken  by 
your  component. 

cal  1  erFl  ags 

Flags  that  provide  further  control  information.  This  field  is  used  only  by 
ImageCodecBandCompress  (11-688). 

capabi 1 i ti es 

Points  to  a  compressor  capability  structure.  The  Image  Compression  Manager 
uses  this  field  to  determine  the  capabilities  of  your  compressor  component. 
This  field  is  used  only  by  ImageCodecPreCompress  (11-730). 
progressProc Record 

Contains  an  ICMProgressProcRecord  (IV-2284)  structure.  During  the 
compression  operation,  your  compressor  may  occasionally  call  a  function  that 
the  application  provides  in  order  to  report  your  progress.  This  field  contains  a 
structure  that  identifies  the  progress  function.  If  the  progressProc  field  in  this 
structure  is  set  to  N I L,  the  application  has  not  supplied  a  progress  function.  This 
field  is  used  only  by  ImageCodecBandCompress  (11-688). 

compl etionProc Record 

Contains  an  ICMCompl  eti onProcRecord  (IV-2279)  structure.  This  structure 
governs  whether  you  perform  the  compression  asynchronously.  If  the 
compl  eti onProc  field  in  this  structure  is  set  to  NIL,  perform  the  compression 
synchronously.  If  this  field  is  not  N I L,  it  specifies  an  application  completion 
function.  Perform  the  compression  asynchronously  and  call  that  completion 
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function  when  your  component  is  finished.  If  the  comp!  eti  onProc  field  in  this 
structure  has  a  value  of  -1,  perform  the  operation  asynchronously  but  do  not 
call  the  application's  completion  function.  This  field  is  used  only  by 
ImageCodecBandCompress  (11-688). 

f 1 ushProcRecord 

Contains  an  I  CM  FI  ushProcRecord  (IV-2280)  structure.  If  there  is  not  enough 
memory  to  store  the  compressed  image,  the  application  may  provide  a  function 
that  unloads  some  of  the  compressed  data.  This  field  contains  a  structure  that 
identifies  that  data-unloading  function.  If  the  application  did  not  provide  a 
data-unloading  function,  the  flushProc  field  in  this  structure  is  set  to  N I L .  In  this 
case,  your  component  writes  the  entire  compressed  image  into  the  memory 
location  specified  by  the  data  field.  The  data-unloading  function  structure  is 
used  only  by  ImageCodecBandCompress  (11-688). 

srcPixMap 

Points  to  the  image  to  be  compressed.  The  image  must  be  stored  in  a  pixel  map 
structure.  The  contents  of  this  pixel  map  differ  from  a  standard  pixel  map  in 
two  ways.  First,  the  rowBy  tes  field  is  a  full  16-bit  value;  the  high-order  bit  is  not 
necessarily  set  to  1.  Second,  the  baseAddr  field  must  contain  a  32-bit  clean 
address.  This  field  is  used  only  by  ImageCodecBandCompress  (11-688). 

prevPi xMap 

Points  to  a  pixel  map  containing  the  previous  image.  If  the  image  to  be 
compressed  is  part  of  a  sequence  that  is  being  temporally  compressed,  this  field 
defines  the  previous  image  for  temporal  compression.  Your  component  should 
then  use  this  previous  image  as  the  basis  of  comparison  for  the  image  to  be 
compressed.  If  the  temporal  Qual  1  ty  field  is  set  to  0,  do  not  perform  temporal 
compression.  If  the  codecFl  agUpdatePrevi  ous  flag  or  the 
codecFl  agUpdatePrevi  ousComp  flag  in  the  f  1  ags  field  is  set  to  1,  update  the 
previous  image  at  the  end  of  the  compression  operation.  The  contents  of  this 
pixel  map  differ  from  a  standard  pixel  map  in  two  ways.  First,  the  rowBy  tes 
field  is  a  full  16-bit  value;  the  high-order  bit  is  not  necessarily  set  to  1.  Second, 
the  baseAddr  field  must  contain  a  32-bit  clean  address.  This  field  is  used  only  by 
ImageCodecBandCompress  (11-688). 

spati al Qual i ty 

Specifies  the  desired  compressed  image  quality.  This  field  is  used  only  by 
ImageCodecBandCompress  (11-688). 

temporal Qual i ty 

Specifies  the  desired  sequence  temporal  quality.  This  field  governs  the  level  of 
compression  the  application  desires  with  respect  to  information  in  successive 
frames  in  the  sequence.  If  this  field  is  set  to  0,  do  not  perform  temporal 
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compression  on  this  frame.  This  field  is  used  only  by  ImageCodecBandCompress 
(11-688). 
similarity 

Indicates  the  similarity  between  adjacent  frames  when  performing  temporal 
compression.  Your  component  returns  a  fixed-point  number  in  this  field.  That 
value  indicates  the  relative  similarity  between  the  frame  just  compressed  and 
the  previous  frame.  Valid  values  range  from  0  (key  frame)  to  1  (identical).  This 
field  is  used  only  by  ImageCodecBandCompress  (11-688). 

dataRateParams 

Points  to  the  parameters  used  when  performing  data  rate  constraint, 
reserved 

Reserved. 

majorSourceChangeSeed 

Contains  an  integer  value  that  is  incremented  each  time  a  data  source  is  added 
or  removed.  This  provides  a  fast  way  for  a  codec  to  know  when  it  needs  to 
redetermine  which  data  source  inputs  are  available. 

minorSourceChangeSeed 

Contains  an  integer  value  that  is  incremented  each  time  a  data  source  is  added 
or  removed,  or  the  data  contained  in  any  of  the  data  sources  changes.  This 
provides  a  way  for  a  codec  to  know  if  the  data  available  to  it  has  changed. 
sourceData 

Contains  a  pointer  to  a  CDSequenceDataSource  (IV-2165)  structure.  This 
structure  contains  a  linked  list  of  all  data  sources.  Because  each  data  source 
contains  a  link  to  the  next  data  source,  a  codec  can  access  all  data  sources  from 
this  field. 

preferredPacketSizeln Bytes 

Specifies  the  preferred  packet  size  for  data. 
requestedBufferWi dth 

Specifies  the  the  width  of  the  image  buffer  to  use,  in  pixels.  For  this  value  to  be 
used,  the  codecWantsSpeci  al  Seal  i  ng  flag  in  the  CodecCapabi  1  i  ti  es  structure 
must  be  set. 
requestedBufferHei ght 

Specifies  the  the  height  of  the  image  buffer  to  use,  in  pixels.  For  this  value  to  be 
used,  the  codecWantsSpeci  al  Seal  i  ng  flag  in  the  CodecCapabi  1  i  ti  es  structure 
must  be  set. 
wantedSourcePixelType 
Undocumented 
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compressed Data Si ze 

The  size  of  the  compressed  image,  in  bytes.  If  this  field  is  nonzero,  it  overrides 
the  dataSi  ze  field  of  the  ImageDescri  pti  on  (IV-2285)  structure.  This  provides  a 
safer  way  for  asynchronous  compressors  to  return  the  size  of  the  compressed 
frame  data,  because  the  dataSi  ze  field  of  ImageDescri  pti  on  maybe  referenced 
by  an  unlocked  handle. 
taskWei ght 

The  preferred  weight  for  multiprocessing  tasks  implementing  this  operation. 
You  should  assign  a  value  by  means  of  the  Mac  OS  function  MPSetTaskWei  ght. 

taskName 

The  preferred  type  for  multiprocessing  tasks  implementing  this  operation.  You 
should  assign  a  value  by  means  of  the  Mac  OS  function  MPSetTaskType. 

conditionFlags  Constants 

codecCondi ti onFi rstBand 

An  input  flag  that  indicates  if  this  is  the  first  band  in  the  frame.  If  this  flag  is  set 
to  1,  then  your  component  is  being  called  for  the  first  time  for  the  current  frame. 

codecCondi ti on  Last Band 

An  input  flag  that  indicates  if  this  is  the  last  band  in  the  frame.  If  this  flag  is  set 
to  1,  then  your  component  is  being  called  for  the  last  time  for  the  current  frame. 
If  the  codecCondi  ti  onFi  rstBand  flag  is  also  set  to  1,  this  is  the  only  time  the 
Image  Compression  Manager  is  calling  your  component  for  the  current  frame. 

codecCondi ti onCodecChangedMask 

An  output  flag  that  indicates  that  the  component  has  changed  the  mask  bits.  If 
your  image  decompressor  component  can  mask  decompressed  images  and  if 
some  of  the  image  pixels  should  not  be  written  to  the  screen,  set  to  0  the 
corresponding  bits  in  the  mask  defined  by  the  maskBi  ts  field  in  the 
decompression  parameter  structure.  In  addition,  set  this  flag  to  1.  Otherwise, 
set  this  flag  to  0. 

callerFlags  Constants 

codec FI  a g Update P rev i ous 

Controls  whether  your  compressor  updates  the  previous  image  during 
compression.  This  flag  is  only  used  with  sequences  that  are  being  temporally 
compressed.  If  this  flag  is  set  to  1,  your  compressor  should  copy  the  current 
frame  into  the  previous  frame  buffer  at  the  end  of  the  frame-compression 
sequence.  Use  the  source  image, 
codec FI  a g Was Compressed 

Indicates  to  your  compressor  that  the  image  to  be  compressed  has  been 
compressed  before.  This  information  may  be  useful  to  compressors  that  can 
compensate  for  the  image  degradation  that  may  otherwise  result  from  repeated 
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compression  and  decompression  of  the  same  image.  This  flag  is  set  to  1  to 
indicate  that  the  image  was  previously  compressed.  This  flag  is  set  to  0  if  the 
image  was  not  previously  compressed. 

codecFlagUpdatePrevi o us Comp 

Controls  whether  your  compressor  updates  the  previous  image  buffer  with  the 
compressed  image.  This  flag  is  only  used  with  temporal  compression.  If  this 
flag  is  set  to  1,  your  compressor  should  update  the  previous  frame  buffer  at  the 
end  of  the  frame-compression  sequence,  allowing  your  compressor  to  perform 
frame  differencing  against  the  compression  results.  Use  the  image  that  results 
from  the  compression  operation.  If  this  flag  is  set  to  0,  your  compressor  should 
not  modify  the  previous  frame  buffer  during  compression. 

codecFl  agLi  veGrab 

Indicates  whether  the  current  sequence  results  from  grabbing  live  video.  When 
working  with  live  video,  your  compressor  should  operate  as  quickly  as  possible 
and  disable  any  additional  processing,  such  as  compensation  for  previously 
compressed  data.  This  flag  is  set  to  1  when  you  are  compressing  from  a  live 
video  source. 

Discussion 

Compressor  components  accept  the  parameters  that  govern  a  compression 

operation  in  the  form  of  the  CodecCompressParams  structure.  This  structure  is  used  by 

ImageCodecBandCompress  (11-688)  and  ImageCodecPreCompress  (11-730). 

Version  Notes 

Some  of  the  fields  in  CodecCompressParams  were  added  for  various  versions  of 

QuickTime  starting  with  version  2.1 .  See  comments  in  the  C  interface  file  for  details. 

Associated  Functions 

ImageCodecBandCompress  (11-688) 

Programming  Info 

C  interface  file:  ImageCodec.  h 

See  Also 

See  ImageCodecBandCompress  (11-688). 


CodecDecompressParams 


The  basic  parameter  block  that  is  passed  to  a  decompressor. 

struct  CodecDecompressParams  { 

ImageSequence  sequencelD; 

ImageDescriptionHandle  imageDescription; 

Ptr  data; 
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1  ong 

buf f erSi ze ; 

1  ong 

f rameNumber ; 

1  ong 

startLine; 

1  ong 

stopLi  ne ; 

1  ong 

condi ti onFl ags  ; 

CodecFl ags 

cal  1 erFl ags  ; 

CodecCapabi 1 i ti es  * 

capabi 1 i ti es  ; 

ICMProgressProc Record 

prog  res s P roc Record ; 

ICMCompl eti on P roc Record 

compl eti onProcRecord ; 

ICMDataProcRecord 

dataProcRecord ; 

CGraf Ptr 

port ; 

Pi xMap 

dstPi xMap ; 

Bi tMapPtr 

maskBi ts  ; 

Pi xMapPtr 

mattePi xMap ; 

Rect 

srcRect; 

MatrixRecord  * 

matrix; 

CodecQ 

accuracy ; 

short 

transferMode ; 

ICMFrameTimePtr 

f rameT i me ; 

1  ong 

reserved[l] ; 

SInt8 

matrixFl  ags ; 

SInt8 

matri xType ; 

Rect 

dstRect ; 

UIntl6 

ma jorSourceChangeSeed ; 

UIntl6 

mi norSourceChangeSeed ; 

CDSequenceDataSourcePtr 

sourceData ; 

RgnHandl e 

maskRegi on ; 

OSType  ** 

wantedDesti nati on  Pixel  Types ; 

1  ong 

screen  FI oodMethod ; 

1  ong 

screenFl oodVal ue; 

short 

prefer redOff screen  Pi xel Si ze ; 

ICMFrameT i me  Inf oPtr 

syncFrameTime; 

Bool ean 

needllpdateOnTi  meChange ; 

Bool ean 

enabl  eBl  ackLi  ni  ng  ; 

Bool ean 

needllpdateOnSourceChange ; 

Bool ean 

pad ; 

1  ong 

unused ; 

CGraf Ptr 

f  i  nal Desti nati on  Port ; 

1  ong 

requested Buf ferWi dth  ; 

1  ong 

requested Buf ferHei ght ; 

Rect 

di  spl  ayabl  eAreaOf Request edBuffer ; 

Bool ean 

requestedSi  ngleField; 

Bool ean 

needllpdateOnNextldle; 

Bool ean 

pa d 2 [ 2 ]  ; 

f  i  xed 

buf ferGamma Level  ; 

UInt32 

taskWeight; 

OSType 

taskName; 
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sequencelD 

Contains  the  unique  sequence  identifier.  If  the  image  to  be  decompressed  is 
part  of  a  sequence,  this  field  contains  the  sequence  identifier  that  was  assigned 
by  DecompressSequenceBegi  n  (1-238).  If  the  image  is  not  part  of  a  sequence,  this 
field  is  set  to  0. 
i mageDescri pti on 

Contains  a  handle  to  the  ImageDescription  (IV-2285)  that  describes  the  image 
to  be  decompressed. 

data 

Points  to  the  compressed  image  data.  This  must  be  a  32-bit  clean  address.  The 
bufferSi  ze  field  indicates  the  size  of  this  data  buffer.  If  the  entire  compressed 
image  does  not  fit  in  memory,  the  application  should  provide  a  data-loading 
function,  identified  by  the  dataProc  field  of  the  data-loading  function  structure 
stored  in  the  dataProcRecord  field.  This  field  is  used  only  by 
I  mageCodecB  and  Decompress  (11-689). 
bufferSi ze 

Specifies  the  size  of  the  image  data  buffer.  This  field  is  used  only  by 
I  mageCodecB  and  Decompress  (11-689). 
f rameNumber 

Contains  a  frame  identifier.  Indicates  the  relative  frame  number  within  the 
sequence.  The  Image  Compression  Manager  increments  this  value  for  each 
frame  in  the  sequence.  This  field  is  used  only  by  ImageCodecBandDecompress 
(11-689). 

startLi ne 

Specifies  the  starting  line  for  the  band.  The  line  number  refers  to  the  pixel  row 
in  the  image,  starting  from  the  top  of  the  image.  The  first  row  in  the  image  is 
row  number  0.  This  field  is  used  only  by  ImageCodecBandDecompress  (11-689). 
stopLi ne 

Specifies  the  ending  line  for  the  band.  The  line  number  refers  to  the  pixel  row 
in  the  image,  starting  from  the  top  of  the  image.  The  first  row  is  row  number  0. 
The  image  band  includes  the  row  specified  by  this  field.  So,  to  define  a  band 
that  contains  one  row  of  pixels  at  the  top  of  an  image,  you  set  the  startLi  ne  field 
to  0  and  the  stopLi  ne  field  to  1.  This  field  is  used  only  by 
ImageCodecBandDecompress  (11-689). 
condi  ti  onFl  ags 

Contains  flags  (see  below)  that  identify  the  condition  under  which  your 
component  has  been  called  (in  order  to  save  the  component  some  work).  The 
flags  in  this  field  are  passed  to  the  component  by  ImageCodecBandCompress 
(11-688)  and  ImageCodecPreDecompress  (11-731)  when  conditions  change,  to  save 
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it  some  work.  In  addition,  these  fields  contain  information  about  actions  taken 
by  your  component. 

cal  1 erFl ags 

Contains  flags  (see  below)  that  provide  further  control  information.  This  field 
is  used  only  by  ImageCodecBandCompress  (11-688). 

capabi 1 i ti es 

Points  to  a  CodecCapabi  1  i  ti  es  (IV-2179)  structure.  The  Image  Compression 
Manager  uses  this  parameter  to  determine  the  capabilities  of  your 
decompressor  component.  This  field  is  used  only  by  ImageCodecPreDecompress 
(11-731). 

prog ressProc Record 

Contains  a  ICMProgressProcRecord  (IV-2284)  structure.  During  the 
decompression  operation,  your  decompressor  may  occasionally  call  a  function 
that  the  application  provides  in  order  to  report  your  progress.  This  field 
contains  a  structure  that  identifies  the  progress  function.  If  the  progressProc 
field  of  this  structure  is  set  to  NIL,  the  application  did  not  provide  a  progress 
function.  This  field  is  used  only  by  ImageCodecBandDecompress  (11-689). 

comp! eti onProcRecord 

Contains  an  ICMCompl  eti  onProcRecord  (IV-2279)  structure.  This  field  governs 
whether  you  perform  the  decompression  asynchronously.  If  the 
compl  eti  on P roc  field  in  this  structure  is  set  to  NIL,  perform  the  decompression 
synchronously.  If  this  field  is  not  N I L,  it  specifies  an  application  completion 
function.  Perform  the  decompression  asynchronously  and  call  that  completion 
function  when  your  component  is  finished.  If  this  field  has  a  value  of  -1, 
perform  the  operation  asynchronously  but  do  not  call  the  application's 
completion  function.  This  field  is  used  only  by  ImageCodecBandDecompress 
(11-689). 

dataProcRecord 

Contains  an  ICMDataProcRecord  (IV-2279)  structure.  If  the  data  stream  is  not  all 
in  memory,  your  component  may  call  an  application  function  that  loads  more 
compressed  data.  This  field  contains  a  structure  that  identifies  that 
data-loading  function.  If  the  application  did  not  provide  a  data-loading 
function,  the  dataProc  field  in  this  structure  is  set  to  NI L.  In  this  case,  the  entire 
image  must  be  in  memory  at  the  location  specified  by  the  data  field.  This  field 
is  used  only  by  ImageCodecBandDecompress  (11-689). 

port 

Points  to  the  color  graphics  port  that  receives  the  decompressed  image. 
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dstPi xMap 

Points  to  the  pixel  map  where  the  decompressed  image  is  to  be  displayed.  The 
GDevi  ce  global  variable  is  set  to  the  destination  graphics  device.  The  contents  of 
this  pixel  map  differ  from  a  standard  pixel  map  in  two  ways.  First,  the  rowBytes 
field  is  a  full  16-bit  value;  the  high-order  bit  is  not  necessarily  set  to  1.  Second, 
the  baseAddr  field  must  contain  a  32-bit  clean  address. 
maskBi ts 

Contains  an  update  mask.  If  your  component  can  mask  result  data,  use  this 
mask  to  indicate  which  pixels  in  the  destination  pixel  map  to  update.  Your 
component  indicates  whether  it  can  mask  with  the  codecCanMask  flag  in  the 
flags  field  of  the  CodecCapabi  1  i  ti  es  (IV-2179)  structure  referred  toby  the 
capabilities  field.  This  field  is  updated  in  response  to  the 
ImageCodecPreDecompress  (11-731)  request.  If  the  mask  has  not  changed  since  the 
last  I mageCodecBand Decompress  request,  the  codecConditionCodecChangedMask 
flag  in  the  condi  tionFlags  field  is  set  to  0 .  This  field  is  used  only  by 
I  mageCodecBand  Decompress  (11-689). 

mattePi xMap 

Points  to  a  pixel  map  that  contains  a  blend  matte.  The  matte  can  be  defined  at 
any  supported  pixel  depth;  the  matte  depth  need  not  correspond  to  the  source 
or  destination  depths.  The  matte  must  be  in  the  coordinate  system  of  the  source 
image.  If  the  application  does  not  want  to  apply  a  blend  matte,  this  field  is  set 
to  NIL.  The  contents  of  this  pixel  map  differ  from  a  standard  pixel  map  in  two 
ways.  First,  the  rowBytes  field  is  a  full  16-bit  value;  the  high-order  bit  is  not 
necessarily  set  to  1.  Second,  the  baseAddr  field  must  contain  a  32-bit  clean 
address.  This  field  is  used  only  by  ImageCodecBandDecompress  (11-689). 
srcRect 

Points  to  a  rectangle  defining  the  portion  of  the  image  to  decompress.  This 
rectangle  must  lie  within  the  boundary  rectangle  of  the  compressed  image, 
which  is  defined  by  the  width  and  height  fields  of  the  image  description 
structure  referred  to  by  the  i mageDescri  pti  on  field, 
matri x 

Points  to  a  matrix  structure  that  specifies  how  to  transform  the  image  during 
decompression, 
accuracy 

Constant  (see  below)  that  specifies  the  accuracy  desired  in  the  decompressed 
image.  Values  for  this  parameter  are  on  the  same  scale  as  compression  quality; 
see  Compress  Image  (1-113). 
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transferMode 

Specifies  the  QuickDraw  transfer  mode  for  the  operation;  see  "Graphics 
Transfer  Modes"  (IV-2670). 
frameTime 

Contains  a  pointer  to  an  ICMFrameT  i  me  Record  (IV-2281)  structure.  This  structure 
contains  a  frame's  time  information  for  scheduled  asynchronous 
decompression  operations. 
matrixFl  ags 

Flag  (see  below)  specifying  the  transformation  matrix.  Set  to  0  for  no 
transformation, 
matri xType 

Contains  the  type  of  the  transformation  matrix,  as  returned  by  GetMatri  xType 
(1-419). 

dstRect 

The  destination  rectangle.  It  is  the  result  of  transforming  the  source  rectangle 
(the  srcRect  parameter)  by  the  transformation  matrix  (the  matri x  parameter). 

ma jorSourceChangeSeed 

Contains  an  integer  value  that  is  incremented  each  time  a  data  source  is  added 
or  removed.  This  provides  a  fast  way  for  a  codec  to  know  when  it  needs  to 
redetermine  which  data  source  inputs  are  available, 
mi norSourceChangeSeed 

Contains  an  integer  value  that  is  incremented  each  time  a  data  source  is  added 
or  removed,  or  the  data  contained  in  any  of  the  data  sources  changes.  This 
provides  a  way  for  a  codec  to  know  if  the  data  available  to  it  has  changed. 
sourceData 

Contains  a  pointer  to  a  CDSequenceDataSource  (IV-2165)  structure.  This 
structure  contains  a  linked  list  of  all  data  sources.  Because  each  data  source 
contains  a  link  to  the  next  data  source,  a  codec  can  access  all  data  sources  from 
this  field. 

maskRegi on 

If  the  maskRegi  on  field  is  not  N I L,  it  contains  a  QuickDraw  region  that  is 
equivalent  to  the  bit  map  contained  in  the  maskBi  ts  field.  For  some  codecs, 
using  the  QuickDraw  region  may  be  more  convenient  than  the  mask  bit  map. 
wantedDesti nati on  Pixel  Types 

Filled  in  by  the  codec  during  the  execution  of  ImageCodecPreDecompress  (11-731). 
Contains  a  handle  to  a  zero-terminated  list  of  non-RGB  pixels  that  the  codec  can 
decompress  to.  Leave  set  to  N I L  if  the  codec  does  not  support  non-RGB  pixel 
spaces.  The  ICM  copies  this  data  structure,  so  it  is  up  to  the  codec  to  dispose  of 
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it  later.  Since  the  predecompress  call  can  be  called  often,  it  is  suggested  that 
codecs  allocate  this  handle  during  the  Open  function  and  dispose  of  it  during 
the  Close  function. 

screenFl oodMethod 

A  constant  (see  below)  for  codecs  that  require  key-color  flooding. 
screenFl oodVal ue 

If  screenFl  oodMethod  is  kScreenFl  oodMethodKeyCol  or,  contains  the  index  of  the 
color  that  should  be  used  to  flood  the  image  area  on  screen  when  a  refresh 
occurs.  This  is  valid  for  both  indexed  and  direct  screen  devices  (e.g.,  for  devices 
with  16  bit  depth,  it  should  contain  the  5-5-5  RGB  value).  If  screenFl  oodMethod 
is  kScreenFl  oodMethodAl  pha,  contains  the  value  that  the  alpha  channel  should  be 
flooded  with. 

p ref er redOff screen  Pi xel Size 

Should  be  filled  in  ImageCodecPreDecompress  (11-731)  with  the  preferred  depth 
of  an  offscreen  buffer  should  the  ICM  have  to  create  one.  It  is  not  guaranteed 
that  an  offscreen  buffer  will  actually  be  of  this  depth.  A  codec  should  still  be 
sure  to  specify  what  depths  it  can  decompress  to  by  using  the  capabilities 
field.  A  codec  might  use  this  field  if  if  was  capable  of  decompressing  to  several 
depths,  but  was  faster  decompressing  to  a  particular  depth. 

syncFrameTime 

Apointer  to  an  ICMFrameTimelnfo  (IV-2281)  structure.  This  structure  contains 
timing  information  about  the  display  of  the  frame. 

needUpdateOnTimeChange 
Undocumented 
enabl eBl ackLi ni ng 

If  TRUE,  indicates  that  the  client  has  requested  blacklining  (displaying  every 
other  line  of  the  image).  Blacklining  increases  the  speed  of  movie  playback 
while  decreasing  the  image  quality. 

needUpdateOnSourceChange 

Undocumented 

pad 

Unused. 

unused 

Unused. 

final DestinationPort 
Undocumented 
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requested Buf ferWi dth 

Specifies  the  width  of  the  image  buffer  to  use,  in  pixels.  For  this  value  to  be 
used,  the  codecWantsSpeci  al  Seal  i  ng  flag  in  CodecCapabi  1  i  ti  es  (IV-2179)  must 
be  set. 

requested Buf ferHei ght 

Specifies  the  height  of  the  image  buffer  to  use,  in  pixels.  For  this  value  to  be 
used,  the  codecWantsSpeci  al  Seal  i  ng  flag  in  CodecCapabi  1  i  ti  es  (IV-2179)  must 
be  set. 

di spl ayabl eAreaOf RequestedBuf fer 

This  field  can  be  used  to  prevent  parts  of  the  requested  buffer  from  being 
displayed.  When  the  codecWantsSpeci  al  Seal  i  ng  flag  is  set,  this  rectangle  can  be 
filled  in  to  indicate  what  portion  of  the  requested  buffer's  width  and  height 
should  be  used.  The  buffer  rectangle  created  by  the  requested  buffer  is  always 
based  at  (0,0),  so  this  coordinate  system  is  also  used  by 

di  spl  ayabl  eAreaOf  RequestedBuffer.  If  this  field  is  not  filled  in,  a  default  value 
of  (0,0,0,0)  is  used,  and  the  entire  buffer  is  displayed.  Use  this  field  if  you  are 
experiencing  edge  problems  with  FlashPix  images. 
requestedSi ngl eFi el d 
Undocumented 
needllpdateOnNextldl  e 
Undocumented 

pad2 

Unused. 

buf ferGamma Level 

The  gamma  level  of  the  data  buffer. 
taskWei ght 

The  preferred  weight  for  multiprocessing  tasks  implementing  this  operation. 
You  should  assign  a  value  by  means  of  the  Mac  OS  function  MPSetTaskWei  ght. 

taskName 

The  preferred  type  for  multiprocessing  tasks  implementing  this  operation.  You 
should  assign  a  value  by  means  of  the  Mac  OS  function  MPSetTaskType. 

conditionFlags  Constants 

codecCondi ti onFi rstBand 

An  input  flag  that  indicates  if  this  is  the  first  band  in  the  frame.  If  this  flag  is  set 
to  1,  then  your  component  is  being  called  for  the  first  time  for  the  current  frame. 

codecCondi ti on  Last Band 

An  input  flag  that  indicates  if  this  is  the  last  band  in  the  frame.  If  this  flag  is  set 
to  1,  then  your  component  is  being  called  for  the  last  time  for  the  current  frame. 
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If  the  codecCondi  ti  onFi  rstBand  flag  is  also  set  to  1,  this  is  the  only  time  the 
Image  Compression  Manager  is  calling  your  component  for  the  current  frame. 

codecCondi tionFirstFrame 

An  input  flag  that  indicates  that  this  is  the  first  frame  to  be  decompressed  for 
this  image  sequence. 

codecCondi tionNewDepth 

An  input  flag  that  indicates  that  the  depth  of  the  destination  has  changed  for 
this  image  sequence. 
codecCondi ti onNewT  ransform 

An  input  flag  that  indicates  that  the  transformation  matrix  has  changed  for  this 
sequence. 

codecCondi ti onNewSrcRect 

An  input  flag  that  indicates  that  the  source  rectangle  has  changed  for  this 
sequence. 

codecCondi ti onNewMatte 

An  input  flag  that  indicates  that  the  matte  pixel  map  has  changed  for  this 
sequence. 

codecCondi ti onNewT  ransferMode 

An  input  flag  that  indicates  that  the  transfer  mode  has  changed  for  this 
sequence. 

codecCondi ti onNewCl ut 

An  input  flag  that  indicates  that  the  color  lookup  table  has  changed  for  this 
sequence. 

codecCondi ti onNewAccuracy 

An  input  flag  that  indicates  to  the  component  that  the  accuracy  parameter  has 
changed  for  this  sequence. 
codecCondi tionNewDesti nation 

An  input  flag  that  indicates  to  the  component  that  the  destination  pixel  map  has 
changed  for  this  sequence. 

codecCondi tionCodecChangedMask 

An  output  flag  that  indicates  that  the  component  has  changed  the  mask  bits.  If 
your  image  decompressor  component  can  mask  decompressed  images  and  if 
some  of  the  image  pixels  should  not  be  written  to  the  screen,  set  the 
corresponding  bits  in  the  mask  (defined  by  the  mas  kBi  ts  field)  to  0.  In  addition, 
set  this  flag  to  1.  Otherwise,  set  this  flag  to  0. 
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codecCondi ti onFi rstScreen 

Indicates  when  the  codec  is  decompressing  an  image  to  the  first  of  multiple 
screens.  That  is,  if  the  decompressed  image  crosses  multiple  screens,  then  the 
codec  can  look  at  this  flag  to  determine  if  this  is  the  first  time  an  image  is  being 
decompressed  for  each  of  the  screens  to  which  it  is  being  decompressed.  A 
codec  that  depends  on  the  mas  kBi  ts  field  of  this  structure  being  a  valid 
RgnHandl  e  on  ImageCodecPreDecompress  (11-731)  needs  to  know  that  in  this  case 
it  is  not  able  to  clip  images  since  the  region  handle  is  only  passed  for  the  first  of 
the  screens;  clipping  would  be  incorrect  for  the  subsequent  screen  for  that 
image. 

codecCondi ti on DoCur so r 

Set  to  1  if  the  decompressor  component  should  shield  and  unshield  the  cursor 
for  the  current  decompression  operation.  This  flag  should  be  set  only  if  the 
codec  has  indicated  its  ability  to  handle  cursor  shielding  by  setting  the 
codecCanShi  el  dCursor  flag  in  the  capabi  1  i  ti  es  field  during 
ImageCodecPreDecompress  (11-731). 

codecCondi  ti  onCatchllpDi  f  f 

Indicates  if  the  current  frame  is  a  "catch-up"  frame.  Set  this  flag  to  1  if  the 
current  frame  is  a  catch-up  frame.  Note  that  you  must  also  set  the 
codecFlagCatchllpDiff  flag  to  1.  This  maybe  useful  to  decompressors  that  can 
drop  frames  when  playback  is  falling  behind. 
codecCondi ti onMaskMayBeChanged 

The  Image  Compression  Manager  has  always  included  support  for 
decompressors  that  could  provide  a  bit  mask  of  pixels  that  were  actually  drawn 
when  a  particular  frame  was  decompressed.  If  a  decompressor  can  provide  a 
bit  mask  of  pixels  that  changed,  the  Image  Compression  Manager  transfers  to 
the  screen  only  the  pixels  that  actually  changed.  QuickTime  2.1  extended  this 
capability  by  adding  this  new  condition  flag.  The  decompressor  should  write 
back  the  mask  only  if  this  flag  is  set.  This  flag  is  used  only  by  ImageCodecFlush 
(11-708). 

codecCondi ti onToBuffer 

Set  to  1  if  the  current  decompression  operation  is  decompressing  into  an 
offscreen  buffer. 

callerFlags  Constants 

codec FI  a g Update P rev i ous 

Controls  whether  your  compressor  updates  the  previous  image  during 
compression.  This  flag  is  only  used  with  sequences  that  are  being  temporally 
compressed.  If  this  flag  is  set  to  1,  your  compressor  should  copy  the  current 
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frame  into  the  previous  frame  buffer  at  the  end  of  the  frame-compression 
sequence.  Use  the  source  image, 
codec  FI  a gWas Compressed 

Indicates  to  your  compressor  that  the  image  to  be  compressed  has  been 
compressed  before.  This  information  may  be  useful  to  compressors  that  can 
compensate  for  the  image  degradation  that  may  otherwise  result  from  repeated 
compression  and  decompression  of  the  same  image.  This  flag  is  set  to  1  to 
indicate  that  the  image  was  previously  compressed.  This  flag  is  set  to  0  if  the 
image  was  not  previously  compressed. 

codecFlagUpdatePrevi o us Comp 

Controls  whether  your  compressor  updates  the  previous  image  buffer  with  the 
compressed  image.  This  flag  is  only  used  with  temporal  compression.  If  this 
flag  is  set  to  1,  your  compressor  should  update  the  previous  frame  buffer  at  the 
end  of  the  frame  compression  sequence,  allowing  your  compressor  to  perform 
frame  differencing  against  the  compression  results.  Use  the  image  that  results 
from  the  compression  operation.  If  this  flag  is  set  to  0,  your  compressor  should 
not  modify  the  previous  frame  buffer  during  compression. 
codecFl  agLi  veGrab 

Indicates  whether  the  current  sequence  results  from  grabbing  live  video.  When 
working  with  live  video,  your  compressor  should  operate  as  quickly  as  possible 
and  disable  any  additional  processing,  such  as  compensation  for  previously 
compressed  data.  This  flag  is  set  to  1  when  you  are  compressing  from  a  live 
video  source. 

accuracy  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 
codecNormal Qual i ty 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 

codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field. 
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codec Los  si essQual i ty 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

matrixFIags  Constants 

matrixFl  agScal  e2x 

Double-scale;  value  is  1L«7. 
matrixFl  agScal  elx 

Single-scale;  value  is  1L«6. 
matrixFl  agScal  eH a  1  f 

Half-scale;  value  is  1L«5. 

screenFloodMethod  Constants 

kScreenFl oodMethodNone 
No  method;  value  is  0. 
kScreenFl oodMethodKeyCol  or 

Key  color  method;  value  is  1. 
kScreenFl oodMethodAl pha 

Alpha  channel  method;  value  is  2. 

Discussion 

The  Image  Compression  Manager  creates  the  decompression  parameters  structure, 
and  your  image  decompressor  component  is  required  only  to  provide  values  for  the 
wantedDesti  nati  onPi xel  Si  ze  and  wantedDesti  nati  onPi xel  Types  fields  of  the 
structure.  Your  image  decompressor  component  can  also  modify  other  fields  if 
necessary.  For  example,  if  it  can  scale  images,  it  must  set  the 
codecCapabi  1  i  tyCanScal  e  flag  in  the  capabi  1  i  ti  es  field  of  the  structure. 

Version  Notes 

Some  of  the  fields  in  CodecDecompressParams  were  added  for  various  versions  of 
QuickTime  starting  with  version  2.1.  See  comments  in  the  C  interface  file  for  details. 

Associated  Functions 

I mageCodecBand Decompress  (11-689) 

Programming  Info 

C  interface  file:  ImageCodec.h 

See  Also 

See  ImageCodecBandDecompress  (11-689). 
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Describes  the  capabilities  of  a  compressor. 


ict  Codeclnfo  { 

Str31 

typeName ; 

short 

versi on ; 

short 

revi si onLevel  ; 

1  ong 

vendor ; 

1  ong 

decompressFl ags ; 

1  ong 

compressFl ags ; 

1  ong 

formatFl ags ; 

UInt8 

comp  res si  on Accuracy  ; 

UInt8 

decompress! on Accuracy ; 

unsi gned 

short 

compressi onSpeed ; 

unsi gned 

short 

decompress! onSpeed ; 

UInt8 

compressi onLevel ; 

UInt8 

resvd ; 

short 

mi nimumHei ght ; 

short 

mi nimumWi dth ; 

short 

decompress  Pi  pel i ne Latency  ; 

short 

compress  Pi  pel i ne Latency ; 

1  ong 

pri vateData ; 

typeName 

Indicates  the  compression  algorithm  used  by  the  component;  for  example, 

'  Ani  mati  on ' .  This  Pascal  string  may  be  used  to  identify  the  compression 
algorithm  to  the  user.  The  string  always  takes  up  32  bytes  no  matter  how  long 
it  is.  The  32  bytes  consist  of  31  bytes  plus  one  length  byte.  Apple  assigns  these 
type  names.  The  value  of  this  field  should  correspond  to  the  value  of  the 
typeName  field  in  the  appropriate  compressor  name  structure  returned  by 
GetCodecNameLi  st  (1-386). 
versi on 

Indicates  the  version  of  compressed  data  this  component  supports.  The 
contents  of  this  field  should  indicate  the  most  recent  version  of  the  compression 
algorithm  that  the  component  can  understand. 

revi si onLevel 

Indicates  the  version  of  the  component;  for  example,  0x00010001  (1.0.1). 
Developers  of  compressors  assign  these  version  numbers. 
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vendor 

Identifies  the  developer  of  the  component;  for  example,  '  appl ' .  The  value  of 
this  field  corresponds  to  the  manufacturer  code  or  application  signature 
assigned  to  the  developer. 
decompressFl ags 

Contains  flags  (see  below)  that  specify  the  decompression  capabilities  of  the 
component.  Typically,  these  flags  are  of  interest  only  to  developers  of  image 
decompressors, 
compress  FI ags 

Contains  flags  (see  below)  that  specify  the  compression  capabilities  of  the 
component.  Typically,  these  flags  are  of  interest  only  to  developers  of  image 
compressors, 
f ormatFl ags 

Contains  flags  (see  below)  that  describe  the  possible  format  for  compressed 
data  produced  by  this  component  and  the  format  of  compressed  files  that  the 
component  can  handle  during  decompression.  Typically,  these  flags  are  of 
interest  only  to  developers  of  compressor  components, 
comp res  si  on Accuracy 

Indicates  the  relative  accuracy  of  the  compression  algorithm  employed  by  the 
component.  Valid  values  for  this  field  range  from  0  to  255.  A  value  of  0  means 
that  the  accuracy  is  unknown.  Values  from  1  to  255  provide  a  gauge  for  the 
relative  accuracy  of  the  compression  algorithm;  higher  values  indicate  better 
accuracy.  The  Image  Compression  Manager  examines  this  field  to  determine 
which  compressor  component  can  most  accurately  compress  a  given  image. 
The  compressi  onAccuracy  field  can  only  approximate  the  accuracy  of  a 
compression  algorithm.  Typically,  compression  algorithms  produce  results  of 
varying  quality  based  on  a  variety  of  parameters,  including  image  size  and 
content.  Since  this  information  is  not  available  until  a  compression  request  is 
issued,  a  precise  measure  of  accuracy  is  not  possible.  However,  the  value  of  this 
field  should  still  give  a  rough  idea  of  the  accuracy  of  the  supported  algorithm. 

decompress! onAccuracy 

Indicates  the  relative  accuracy  of  the  decompression  algorithm  employed  by 
the  component.  Valid  values  for  this  field  range  from  0  to  255.  A  value  of  0 
means  that  the  accuracy  is  unknown.  Values  from  1  to  255  indicate  the  relative 
accuracy  of  the  decompression  technique;  higher  values  mean  better  accuracy. 
The  Image  Compression  Manager  examines  this  field  to  determine  which 
decompressor  component  can  most  accurately  decompress  a  given  image.  The 
decompressi  onAccuracy  field  can  only  approximate  the  accuracy  of  a 
decompression  algorithm.  Typically,  decompression  algorithms  produce 
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results  of  varying  quality  based  on  a  variety  of  parameters,  including  image 
size  and  content.  Since  this  information  is  not  available  until  a  decompression 
request  is  issued,  a  precise  measure  of  accuracy  is  not  possible.  However,  the 
value  of  this  field  should  still  give  a  rough  idea  of  the  accuracy  of  the  supported 
algorithm. 

compressi onSpeed 

Indicates  the  relative  speed  of  the  component  for  compression  operations. 
Valid  values  for  this  field  lie  in  the  range  from  0  to  65,535.  A  value  of  0  means 
that  the  speed  is  unknown.  Values  from  1  to  65,535  correspond  to  the  number 
of  milliseconds  the  component  requires  to  compress  a  320-by-240  pixel  image 
on  a  Macintosh  II  computer.  The  Image  Compression  Manager  examines  this 
field  to  determine  which  compressor  component  can  most  quickly  compress  a 
given  image. 

decomp  res si onSpeed 

Indicates  the  relative  speed  of  the  component  for  decompression  operations. 
Valid  values  for  this  field  lie  in  the  range  from  0  to  65,535.  A  value  of  0  means 
that  the  speed  is  unknown.  Values  from  1  to  65,535  correspond  to  the  number 
of  milliseconds  the  component  requires  to  decompress  a  320-by-240  pixel 
image  on  a  Macintosh  II  computer.  The  Image  Compression  Manager  examines 
this  field  to  determine  which  compressor  component  can  most  quickly 
decompress  a  given  image. 

compressi onLevel 

Indicates  the  relative  compression  achieved  by  this  component.  Valid  values 
for  this  field  lie  in  the  range  from  0  to  255.  A  value  of  0  means  that  the 
compression  level  is  unknown.  Values  from  1  to  255  map  to  percentage  values 
of  relative  compression;  lower  values  mean  lesser  compression.  A  value  of  1 
means  no  compression  (0  percent);  a  value  of  255  means  maximum 
compression  (100  percent).  The  Image  Compression  Manager  examines  this 
field  to  determine  which  available  compressor  component  will  yield  the 
smallest  resulting  data  for  a  given  image.  The  compressi  onLevel  field  can  only 
approximate  the  effectiveness  of  a  compression  algorithm.  Typically, 
compression  algorithms  produce  results  of  varying  quality  based  on  a  variety 
of  parameters,  including  image  size  and  content.  Since  this  information  is  not 
available  until  a  compression  request  is  issued,  a  precise  measure  of 
compression  is  not  possible.  However,  the  value  of  this  field  should  still  give  a 
rough  idea  of  the  effectiveness  of  the  supported  algorithm. 

resvd 

Reserved;  set  to  0. 
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mi ni mumHei ght 

Specifies  the  height  in  pixels  of  the  smallest  image  the  component  can  handle. 
Together  with  the  mini  mumWi  dth  field,  this  field  defines  the  block  size  for  the 
component.  The  Image  Compression  Manager  does  not  issue  compression  or 
decompression  requests  for  images  smaller  than  the  block  size. 

mi ni mumWi dth 

Specifies  the  width  in  pixels  of  the  smallest  image  the  component  can  handle. 
Together  with  the  minimumHeight  field,  this  field  defines  the  block  size  for  the 
component.  The  Image  Compression  Manager  does  not  issue  compression  or 
decompression  requests  for  images  smaller  than  the  block  size. 

decompress  Pi  pel i ne Latency 

Decompression  pipeline  latency  in  milliseconds,  for  asynchronous  codecs. 
compressPi pel i neLatency 

Compression  pipeline  latency  in  milliseconds,  for  asynchronous  codecs, 
pri vateData 

Reserved  for  future  use.  This  field  must  be  set  to  0. 

decompressFlags  and  compressFlags  Constants 

codecInfoDoesl 

Codec  can  work  with  1-bit  pixels. 
codecInfoDoes2 

Codec  can  work  with  2-bit  pixels. 
codecInfoDoes4 

Codec  can  work  with  4-bit  pixels. 
codecInfoDoes8 

Codec  can  work  with  8-bit  pixels. 
codecInfoDoesl6 

Codec  can  work  with  16-bit  pixels. 
codecInfoDoes32 

Codec  can  work  with  32-bit  pixels. 
codecInfoDoesDither 

Codec  can  dither  images, 
codec  I nf oDoes St retch 

Codec  can  stretch  images  to  arbitrary  sizes. 
codecInfoDoesShrink 

Codec  can  shrink  images  to  arbitrary  sizes. 


STR 


Inside  QuickTime:  Data  Structures 


IV-2205 


Data  Structures 


Codeclnfo 


codecInfoDoesMask 

Codec  can  mask  images  to  clipping  regions. 
codecInfoDoesTemporal 

Codec  can  handle  temporal  redundancy, 
codeclnfo Does  Double 

Codec  can  stretch  images  to  exactly  double  size. 
codecInfoDoesQuad 

Codec  can  stretch  images  to  exactly  quadruple  size. 
codecInfoDoesHal f 

Codec  can  shrink  images  to  exactly  half  size, 
codeclnfo DoesQuarter 

Codec  can  shrink  images  to  exactly  quarter  size, 
codeclnfo Does  Rotate 

Codec  can  rotate  images  during  decompression. 
codecInfoDoesHorizFlip 

Codec  can  flip  images  horizontally  during  decompression. 
codecInfoDoesVertFlip 

Codec  can  flip  images  vertically  during  decompression, 
codec  I nfoHas Effect Parameter  Li st 

Codec  implements  QTGetEffectsLi  st  (11-1174). 
codecInfoDoesBlend 

Codec  can  blend  image  during  decompression. 
codecInfoDoesWarp 

Codec  can  warp  image  arbitrarily  during  decompression, 
codec  I nfoDoes Recompress 

Codec  can  recompress  image  without  accumulating  errors, 
codeclnfo DoesSpool 

Codec  can  spool  image  data. 
codecInfoDoesRateConstrain 

Codec  can  constrain  data  rate. 

formatFlags  Constants 

codecInfoDepthl 

Compressed  data  available  at  1  bit-per-pixel  depth. 
codecInfoDepth2 

Compressed  data  available  at  2  bit-per-pixel  depth. 
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codecInfoDepth4 

Compressed  data  available  at  4  bit-per-pixel  depth. 
codecInfoDepth8 

Compressed  data  available  at  8  bit-per-pixel  depth. 
codecInfoDepthl6 

Compressed  data  available  at  16  bit-per-pixel  depth. 
codecInfoDepth24 

Compressed  data  available  at  24  bit-per-pixel  depth. 
codecInfoDepth32 

Compressed  data  available  at  32  bit-per-pixel  depth. 
codecInfoDepth33 

Compressed  data  available  at  1  bit-per-pixel  monochrome  depth. 
codecInfoDepth34 

Compressed  data  available  at  2  bit-per-pixel  grayscale  depth. 
codecInfoDepth36 

Compressed  data  available  at  4  bit-per-pixel  grayscale  depth. 
codecInfoDepth40 

Compressed  data  available  at  8  bit-per-pixel  grayscale  depth. 
codecInfoStoresClut 

Compressed  data  can  have  custom  color  lookup  tables. 
codecInfoDoesLossless 

Compressed  data  can  be  stored  in  lossless  format. 
codecInfoSequenceSensi ti  ve 

Compressed  data  is  sensitive  to  out-of-sequence  decoding. 

Discussion 

Contains  the  description  of  a  codec. 

Version  Notes 

The  codecInfoHasEffectParameterLi  st  constant  was  formerly  codecInfoDoesSkew. 

Associated  Functions 

GetCodecInfo  (1-385) 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

See  Also 

See  the  CodecNameSpec  (IV-2208)  structure  and  the  GetCodecNameLi  st  (1-386) 
function. 
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CodecNameSpec 

Defines  a  compressor  name. 

struct  CodecNameSpec  { 

CodecComponent  codec; 

CodecType  cType; 

Str31  typeName; 

Handle  name; 

}; 

codec 

Uniquely  identifies  the  component  or,  in  some  cases,  contains  a  special  value 
that  selects  all  components.  If  your  application  requests  a  list  of  components, 
the  codec  field  in  each  compressor  name  structure  contains  the  component  ID 
for  that  compressor.  If  your  application  requests  a  list  of  component  types,  the 
codec  field  is  set  to  0  in  each  compressor  name  structure 

cType 

Contains  the  type  identifier  for  the  compressor.  The  value  of  this  field  indicates 
the  compression  algorithm  supported  by  the  component.  See  "Codec 
Identifiers"  (IV-2655)  for  a  list  of  values. 
typeName 

Contains  a  text  string  in  Pascal  format  that  identifies  the  compression  algorithm 
supported  by  the  component.  This  string  may  be  used  to  identify  the 
compression  algorithm  to  the  user.  The  value  of  this  field  should  correspond  to 
the  value  of  the  typeName  field  in  the  appropriate  compressor  information 
structure  returned  by  the  component  in  response  to  GetCodecInfo  (1-385). 

name 

Specifies  the  name  of  the  compressor  component.  You  can  assign  this  name  to 
uniquely  identify  your  product,  and  it  may  be  used  to  identify  the  component 
to  the  user. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

See  Also 

See  the  Codeclnfo  (IV-2202)  structure  and  the  GetCodecInfo  (1-385)  function. 

CodecNameSpecList 

Contains  a  list  of  CodecNameSpec  (IV-2208)  structures. 
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struct  CodecNameSpecLi st  { 
short  count; 

CodecNameSpec  1 i s t  [  1  ] ; 

}; 

count 

Indicates  the  number  of  compressor  name  structures  contained  in  the  list  array 
that  follows. 


list 

Contains  an  array  of  compressor  name  structures.  Each  structure  corresponds 
to  one  compressor  component  or  type  that  meets  the  selection  criteria  your 
application  specifies  when  it  calls  GetCodecNameList  (1-386). 

Associated  Functions 

Di  sposeCodecNameLi  st  (1-257) 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 
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See  Also 

The  GetCodecNameList  (1-386)  function  returns  a  CodecNameSpecLi  st  structure. 


ColorSpec 


Associates  an  RGB  color  value  with  an  index  or  other  value. 

struct  ColorSpec  { 

short  value; 

RGBColor  rgb; 

}; 

val  ue 

The  pixel  value  assigned  by  Color  QuickDraw  for  the  color  specified  in  the  rgb 
field  of  this  structure.  Color  QuickDraw  assigns  a  pixel  value  based  on  the 
capabilities  of  the  user's  screen.  For  indexed  devices,  the  pixel  value  is  an  index 
number  assigned  by  QuickTime  to  the  closest  color  available  on  the  indexed 
device;  for  direct  devices,  this  value  expresses  the  best  available  red,  green,  and 
blue  values  for  the  color  on  the  direct  device. 

rgb 

An  RGBCol  or  (IV-2403)  structure  that  fully  specifies  the  color  whose 
approximation  Color  QuickDraw  specifies  in  the  value  field. 
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Discussion 

When  creating  a  Pi  xMap  (IV-2332)  structure  for  an  indexed  device.  Color 
QuickDraw  creates  a  ColorTable  (IV-2210)  structure  that  defines  the  best  colors 
available  for  the  pixel  image  on  that  graphics  device.  The  Color  Manager  also  stores 
aColorTable  structure  for  the  currently  available  colors  in  the  graphics  device's 

color  lookup  table. 

Programming  Info 

C  interface  file:  Quickdraw.h 

See  Also 

See  Col  orTabl  e  (IV-2210). 

ColorTable 

Provides  a  color  table  for  indexed  color  spaces. 

struct  ColorTable  { 

long  ctSeed; 

short  ctFlags; 

short  ctSize; 

CSpecArray  ctTable; 

}; 

ctSeed 

Identifies  a  particular  instance  of  a  color  table.  The  Color  Manager  uses  the 
ctSeed  value  to  compare  an  indexed  device's  color  table  with  its  associated 
inverse  table  (a  table  it  uses  for  fast  color  lookup).  When  the  color  table  for  a 
graphics  device  has  been  changed,  the  Color  Manager  needs  to  rebuild  the 
inverse  table. 

ctFl  ags 

A  flag  that  distinguishes  pixel  map  color  tables  from  color  tables  in  GDevi  ce 
records.  If  the  high  bit  is  0,  this  is  a  pixel  map  color  table;  if  the  high  bit  is  1,  this 
is  a  color  tables  in  a  GDevi  ce  (IV-2264)  structure. 
ctSi ze 

One  less  than  the  number  of  entries  in  the  table. 
ctTabl e 

An  array  ofColorSpec  (IV-2209)  structures,  each  containing  a  pixel  value  and  a 
color  specified  by  an  RGBCol  or  (IV-2403)  structure. 
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Discussion 

When  creating  a  PixMap  (IV-2332)  structure  for  an  indexed  device.  Color 
QuickDraw  creates  a  Col  orTabl  e  (IV-2210)  structure  that  defines  the  best  colors 
available  for  the  pixel  image  on  that  graphics  device.  The  Color  Manager  also  stores 
aColorTable  structure  for  the  currently  available  colors  in  the  graphics  device's 
color  lookup  table.  Typically,  your  application  needs  to  create  Col  orTabl  e  records 
only  if  it  uses  the  Mac  OS  Palette  Manager. 

Programming  Info 

C  interface  file:  Quickdraw.h 

See  Also 

See  ColorSpec  (IV-2209).  For  the  inverse  structure,  see  I  Tab  (IV-2297). 
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ComponentAliasResource 

Provides  an  alias  to  a  component  that  can  handle  more  than  one  data  type;  for 
example,  a  WAV  importer  can  be  an  alias  to  the  AIFF  importer  code,  which  reads 
WAV  files. 

struct  ComponentAliasResource  { 

ComponentResource  cr; 

ComponentDescri pti on  aliasCD; 

}; 

cr 

Information  needed  to  register  the  component.  This  information  is  used  in  the 
same  way  as  registration  information  for  ordinary  components,  with  one 
exception:  the  specification  of  the  code  resource  for  the  component  is  ignored, 
al i asCD 

The  target  for  the  alias.  The  code  resource  of  the  target  is  used  in  place  of  the 
code  resource  specified  in  the  cr  field. 

Discussion 

To  resolve  a  component  alias,  the  Component  Manager  passes  the  contents  of  the 
al  i  asCD  field  to  Fi  ndNextComponent  (1-360),  just  as  an  application  would.  This  field 
includes  all  the  information  that  is  necessary  to  specify  the  target  component.  If 
there  is  no  component  that  matches  the  specifications,  the  request  to  open  the  alias 
fails.  The  Component  Manager  never  resolves  a  component  alias  until  the  alias  is 
opened.  This  lets  you  register  component  aliases  before  their  target  components  are 
registered.  It  also  lets  you  replace  target  components  with  other  components. 
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Programming  Info 

C  interface  file:  Components .  h 


ComponentDescription 


Describes  a  class  of  components  by  their  attributes. 


struct  ComponentDescription  { 


OSType 
OSType 
OSType 
unsi gned 
unsi gned 


}; 


ong 

ong 


componentType ; 
componentSubType ; 
componentManufacturer ; 
componentFl  ags ; 
component  FI ags Mask ; 


componentType 

A  four-character  code  that  identifies  the  type  of  component.  See  "Codec 
Identifiers"  (IV-2655).  All  components  of  a  particular  type  support  a  common 
set  of  interface  routines.  Your  application  uses  this  field  to  search  for 
components  of  a  given  type. 

componentSubType 

A  four-character  code  that  identifies  the  subtype  of  the  component.  Different 
subtypes  of  a  component  type  may  support  additional  features  or  provide 
interfaces  that  extend  beyond  the  standard  routines  for  a  given  component 
type.  For  example,  the  subtype  of  an  image  compressor  component  indicates 
the  compression  algorithm  employed  by  the  compressor.  Your  application  can 
use  the  componentSubType  field  to  perform  a  more  specific  lookup  operation 
than  is  possible  using  only  the  componentType  field.  Set  this  parameter  to  0  to 
select  a  component  with  any  subtype  value. 

componentManufacturer 

A  four-character  code  that  identifies  the  manufacturer  of  the  component.  This 
field  allows  for  further  differentiation  between  individual  components.  For 
example,  components  made  by  a  specific  manufacturer  may  support  an 
extended  feature  set.  Components  provided  by  Apple  have  a  manufacturer 
value  of  '  appl  ' .  Your  application  can  use  this  field  to  find  components  from  a 
certain  manufacturer.  A  value  of  0  operates  as  a  wildcard 
componentFl ags 

A  32-bit  field  that  contains  flags  describing  your  component's  capabilities.  The 
high-order  8  bits  are  defined  by  the  Component  Manager.  You  should  set  these 
bits  to  0.  The  low-order  24  bits  are  specific  to  each  component  type.  These  flags 
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can  be  used  to  indicate  the  presence  of  features  or  capabilities  in  a  given 
component  (see  below), 
component  FI agsMask 

A  32-bit  field  that  indicates  which  flags  in  the  componentFl  ags  field  are  relevant 
to  a  particular  component  search  operation.  For  each  flag  in  the  componentFl  ags 
field  that  is  to  be  considered  as  a  search  criterion,  your  application  should  set 
the  corresponding  bit  in  this  field  to  1.  To  ignore  a  flag,  set  the  bit  to  0. 

componentFlags  Constants 

canMovi eExportAuxDataHandl e 

Set  this  bit  if  your  export  component  exports  to  an  auxiliary  data  handle.  A 
movie  export  component  that  supports  Movi  eExportGetAuxi  1  i  aryData  (11-923) 
should  set  this  flag  in  its  componentFl  ags  parameter. 
canMovi elmportVal idateHandles 

Set  this  bit  if  your  movie  import  component  can  and  wants  to  validate  handles. 
canMovi elmportVal i dateFi 1 e 

Set  this  bit  if  your  movie  import  component  can  and  wants  to  validate  files. 
dontRegi sterWi thEasyOpen 

Set  this  bit  when  Macintosh  Easy  Open  is  installed  and  you  do  not  want 
QuickTime  to  register  your  component  with  Easy  Open  (preferring  to  handle 
interactions  with  Macintosh  Easy  Open  yourself). 
canMovi e Import  In  PI  ace 

Set  this  bit  if  your  movie  import  component  can  create  a  movie  from  a  file 
without  having  to  write  to  a  separate  disk  file.  Examples  include  MPEG  and 
AIFF  import  components. 

movielmportSubTypelsFi 1 eExtensi  on 

Set  this  bit  if  your  component's  subtype  is  a  file  extension  instead  of  a 
Macintosh  file  type.  For  example,  if  your  import  component  opens  files  with  an 
extension  of  .doc,  you  would  set  this  flag  and  set  your  component  subtype  to 
’DOC  ’. 

canMovi e Import Parti al 

Set  this  bit  if  your  movie  import  component  implements 
Movi  e  Import  SetOff  set  And  Li  mi  t  (11-959). 
hasMovi elmportMIMELi st 

Set  this  bit  if  you  movie  import  component  supports  returning  a  MIME  type 
list.  A  movie  import  component  that  supports  Movi  elmportGetMIMETypeLi  st 
(11-948)  should  set  this  flag  in  the  componentFl  ags  field  of  the  component 
description  record. 
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canMovi e Expo rtFromProcedu res 

Set  this  bit  if  your  movie  export  component  supports 
Movi eExportFromProceduresToDataRef  (11-922). 
canMovi eExportVal i dateMovi e 

Set  this  bit  if  your  movie  export  component  validates  the  movie  passed  to  it. 
movi e Export Needs  Resource  Fork 

Set  this  bit  if  your  export  component  requires  the  creation  of  the  resource  fork 
of  a  Mac  OS  file, 
can Movi el mport Data  References 

Set  this  bit  if  your  movie  import  component  can  accept  a  data  reference  (such 
as  a  handle)  as  the  source  for  the  import, 
movi eExportMustGetSourceMedi aType 

Set  this  bit  if  the  export  component  implements  the  new  exporter  component 
registration  mechanism.  The  component  must  implement 
Movi  eExportGetSourceMedi  aType  (11-927). 

can Mo vi el mportVali date Data  References 

Set  this  bit  if  the  export  component  supports  MovielmportVal  i  dateDataRef 
(11-965). 

canMovi  el mporttlandles 

Set  this  bit  if  your  movie  import  component  can  import  from  a  handle. 
canMovi el mportFiles 

Set  this  bit  if  your  movie  import  component  can  import  files, 
has Movi el mportUserlnter face 

Set  this  bit  if  your  movie  import  component  has  its  own  user  interface. 
canMovi  eExporttlandl  es 

Set  this  bit  if  your  movie  export  component  can  export  to  a  handle. 
canMovi eExportFi 1 es 

Set  this  bit  if  your  movie  export  component  can  export  to  a  file. 
hasMovi eExportUser Interface 

Set  this  bit  if  your  movie  export  component  has  its  own  user  interface. 
dontAutoFileMovielmport 

Set  this  bit  to  turn  off  automatic  file  conversion, 
channel  FlagDontOpenResFile 

Instructs  the  sequence  grabber  not  to  open  your  panel  component's  resource 
file.  By  default,  the  sequence  grabber  opens  your  component's  resource  file  for 
you,  and  then  provides  you  with  the  appropriate  file  reference  number.  In 
general,  this  is  convenient.  However,  if  your  component  is  linked  with  your 
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application  and  does  not  have  its  own  resource  file,  you  may  not  want  the 
sequence  grabber  to  try  to  open  the  resource  file.  In  such  cases,  set  this  flag  to 
1.  For  an  example,  see  SGPanel  GetDi  tl  (III— 1761). 

channel FlagHasDependency 

Lets  you  tell  the  sequence  grabber  that  your  panel  component  requires  special 
digitizing  hardware.  If  you  set  this  flag  to  1,  the  sequence  grabber  gives  your 
component  an  opportunity  to  verify  that  it  can  work  in  the  current  hardware 
environment,  by  calling  your  component's  SGPanel  CanRun  (III— 1759)  function. 

Discussion 

The  Component  Manager  ignores  fields  in  the  component  description  structure  that 
are  set  to  0.  For  example,  if  you  set  all  the  fields  to  0  and  pass  this  structure  to 
CountComponents  (1-143),  the  Component  Manager  counts  the  total  number  of 
components  registered  in  the  system.  If  you  set  all  fields  to  0  except  for  the 
componentManuf  acturer  field,  the  Component  Manager  counts  the  number  of 
registered  components  supplied  by  the  manufacturer  you  specify. 

Associated  Functions 

CountComponents  (1-143) 

Programming  Info 

C  interface  file:  Components .  h 
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ComponentlnstanceRecord 

Undocumented 

struct  ComponentlnstanceRecord  { 
long  data [ 1 ] ; 

}; 

data 

Undocumented 

Discussion 

Undocumented 

Programming  Info 

C  interface  file:  Components .  h 


ComponentMPWorkFunctionHeaderRecord 

Stores  data  for  the  ComponentMPWorkFuncti  onProc  (III— 2077)  callback. 


Inside  QuickTime:  Data  Structures 


IV-2215 


Data  Structures 


ComponentParameters 


struct  ComponentMPWorkFuncti onHeaderRecord  { 


UInt32 

headerSi ze ; 

UInt32 

recordSi ze ; 

UInt32 

workFl ags ; 

UIntl6 

processorCount ; 

UInt8 

unused ; 

UInt8 

i sRunni ng ; 

}; 

headerSi ze 

Undocumented 
recordSi ze 

Undocumented 
workFl ags 

Undocumented 

processorCount 

Undocumented 

unused 

Undocumented 
i sRunni ng 

Undocumented 


Discussion 

Undocumented 

Associated  Functions 

ComponentMPWorkFuncti  onProc  (III — 2077) 

Programming  Info 

C  interface  file:  Components .  h 


ComponentParameters 


Data  structure  passed  by  the  Component  Manager  to  a  component, 
struct  ComponentParameters  { 


UInt8 

fl ags ; 

UInt8 

paramSi ze 

short 

what ; 

1  ong 

params[l] 
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flags 

Reserved. 
paramSi ze 

Size  in  bytes  of  actual  parameters  passed. 

what 

The  type  of  request  (see  below).  Negative  values  are  reserved  for  definition  by 
Apple.  You  can  use  values  greater  than  or  equal  to  0  to  define  other  requests 
that  are  supported  by  your  component, 
params 

Parameters  sent  to  your  component. 

what  Constants 

kComponentOpenSel  ect 

Open  a  connection;  required. 
kComponentCl oseSel ect 

Close  an  open  connection;  required. 
kComponentCanDoSel  ect 

Determine  whether  your  component  supports  a  particular  request;  required. 
kComponentVersi onSel  ect 

Return  your  component's  version  number;  required. 
kComponentRegi sterSel  ect 

Determine  whether  your  component  can  operate  in  the  current  environment. 
kComponentTargetSel  ect 

Call  another  component  whenever  it  would  call  itself  (as  a  result  of  your 
component  being  used  by  another  component). 

kComponentUnregi sterSel  ect 

Perform  any  operations  that  are  necessary  as  a  result  of  your  component  being 
unregistered. 

kComponentGetMPWorkFuncti  onSel  ect 
Undocumented 

kComponentExecuteWi redActi onSel  ect 
Undocumented 

kComponentGetPubl i cResourceSel  ect 
Undocumented 

Discussion 

Whenever  the  Component  Manager  receives  a  request  for  your  component,  it  calls 
your  component's  entry  point  and  passes  any  parameters,  along  with  information 
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about  the  current  connection,  in  this  structure.  The  Component  Manager  also 
passes  a  handle  to  the  global  storage  (if  any)  associated  with  that  instance  of  your 
component.  When  your  component  receives  a  request,  it  should  examine  the 
parameters  to  determine  the  nature  of  the  request,  perform  the  appropriate 
processing,  set  an  error  code  if  necessary,  and  return  an  appropriate  function  result 
to  the  Component  Manager. 

Associated  Functions 

Cal  1  Component  (1-58) 

Programming  Info 

C  interface  file:  Components .  h 


ComponentPlatformlnfo 

Indicates  the  platform  a  component  is  ready  to  run  on. 

struct  ComponentPlatformlnfo  { 

long  componentFl ags ; 

ResourceSpec  component; 

short  pi atformType ; 

}; 

componentFl ags 

Component  flags  (different  for  each  component  type), 
component 

The  resource  where  the  component  code  is  found, 
pi atformType 

Platform  code  (see  below). 

platformType  Constants 

pi atform68k 

Motorola  MC68k  architecture, 
pi atformPowerPC 

IBM  PowerPC  architecture, 
pi  at form Interpreted 
Undocumented 
pi atformWi n32 

Microsoft  Windows  32  architecture, 
pi atformPowerPCNati veEntry Point 
Native  PowerPC  architecture. 
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C  interface  file:  Components .  h 


ComponentPlatformlnfoArray 


Contains  an  array  of  ComponentPl  atformlnfo  (IV-2218)  structures. 

struct  ComponentPlatformlnfoArray  { 
long  count; 

ComponentPl atformlnfo  pi  atformArray[l] ; 

}; 

count 

Number  of  ComponentPl  atformlnfo  (IV-2218)  structures  in  the  array, 
pi atf ormArray 
The  array. 

Programming  Info 

C  interface  file:  Components .  h 
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ComponentRecord 


Undocumented 

struct  ComponentRecord  { 
long  data [ 1 ] ; 

}; 

data 

Undocumented 

Discussion 

Undocumented 

Programming  Info 

C  interface  file:  Components .  h 


ComponentResource 


Defines  the  structure  of  a  component  resource, 
struct  ComponentResource  { 
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ComponentDescri pti on 

cd ; 

ResourceSpec 

component ; 

ResourceSpec 

componentName ; 

ResourceSpec 

componentlnfo ; 

ResourceSpec 

1: 

componentlcon ; 

cd 

A  ComponentDescri  pti  on  (IV-2212)  structure  that  specifies  the  characteristics  of 
the  component, 
component 

A  ResourceSpec  (IV-2402)  structure  that  specifies  the  type  and  ID  of  the 
component  code  resource.  The  resType  field  of  this  structure  may  contain  any 
value.  The  component's  main  entry  point  must  be  at  offset  0  in  the  resource. 

componentName 

A  ResourceSpec  (IV-2402)  structure  that  specifies  the  resource  type  and  ID  for 
the  name  of  the  component.  This  is  a  Pascal  string.  Typically,  the  component 
name  is  stored  in  a  resource  of  type  '  STR  ' . 
componentlnfo 

A  ResourceSpec  (IV-2402)  structure  that  specifies  the  resource  type  and  ID  for 
the  information  string  that  describes  the  component.  This  is  a  Pascal  string. 
Typically,  the  information  string  is  stored  in  a  resource  of  type  'STR  ' .  You 
might  use  the  information  stored  in  this  resource  in  a  Get  Info  dialog  box. 
componentlcon 

A  ResourceSpec  (IV-2402)  structure  that  specifies  the  resource  type  and  ID  for 
the  icon  for  a  component.  Component  icons  are  stored  as  32-by-32  bit  maps. 
Typically,  the  icon  is  stored  in  a  resource  of  type  'ICON'.  Note  that  this  icon  is 
not  used  by  the  Finder;  you  supply  an  icon  only  so  that  other  components  or 
applications  can  display  your  component's  icon  in  a  dialog  box  if  needed. 

Discussion 

You  can  optionally  append  to  the  end  of  this  structure  the  information  defined  by 
ComponentResourceExtensi  on  (IV-2221). 

Associated  Functions 

Regi sterComponentResource  (III — 1453) 

Programming  Info 
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See  Also 

See  ExtComponentResource  (IV-2249). 
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ComponentResourceExtension 


Extends  the  ComponentResource  (IV-2219)  structure. 

struct  ComponentResourceExtension  { 
long  componentVersi on ; 

long  componentRegi sterFl ags ; 

short  componentlconFamily; 

}; 

componentVersi on 

The  version  number  of  the  component.  If  you  specify  the 
componentDoAutoVersi  on  flag  in  componentRegi  sterFl  ags,  the  Component 
Manager  must  obtain  the  version  number  of  your  component  when  your 
component  is  registered.  Either  you  can  provide  a  version  number  in  your 
component's  resource,  or  you  can  specify  a  value  of  0  for  its  version  number.  If 
you  specify  0,  the  Component  Manager  sends  your  component  a  version 
request  to  get  the  version  number  of  your  component. 
componentRegi sterFl  ags 

A  set  of  flags  (see  below)  containing  additional  registration  information, 
component  I  con Fami ly 

The  resource  ID  of  an  icon  family.  You  can  provide  an  icon  family  in  addition 
to  the  icon  provided  in  the  component  I  con  field  of  ComponentResource  (IV-2219). 
Note  that  members  of  this  icon  family  are  not  used  by  the  Finder;  you  supply 
an  icon  family  only  so  that  other  components  or  applications  can  display  your 
component's  icon  in  a  dialog  box  if  needed. 

componentRegisterFlags  Constants 

componentDoAutoVersi  on 

Tells  the  Component  Manager  to  resolve  conflicts  between  different  versions  of 
the  same  component.  If  you  specify  this  flag,  the  Component  Manager  registers 
your  component  only  if  there  is  no  later  version  available.  If  an  older  version  is 
already  registered,  the  Component  Manager  unregisters  it.  If  a  newer  version 
of  the  same  component  is  registered  after  yours,  the  Component  Manager 
automatically  unregisters  your  component.  You  can  use  this  automatic  version 
control  feature  to  make  sure  that  the  most  recent  version  of  your  component  is 
registered,  regardless  of  the  number  of  versions  that  are  installed. 

componentWantsUnregi  ster 

You  want  your  component  to  receive  an  unregister  request  when  it  is 
unregistered. 


STR 
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component AutoVersi onlncludeFlags 

You  want  the  Component  Manager  to  include  the  componentFl  ags  field  of  the 
ComponentDescri  pti  on  (IV-2212)  structure  when  it  searches  for  identical 
components  in  the  process  of  performing  automatic  version  control  for  your 
component.  If  you  do  not  specify  this  flag,  the  Component  Manager  searches 
only  the  componentType,  componentSubType,  and  componentManufacturer  fields. 
When  the  Component  Manager  performs  automatic  version  control  for  your 
component,  it  searches  for  components  with  identical  values  in  the 
componentType,  componentSubType,  and  componentManufacturer  fields  (and 
optionally,  in  the  componentFl  ags  field).  If  it  finds  a  matching  component,  it 
compares  version  numbers  and  registers  the  most  recent  version  of  the 
component.  Note  that  the  setting  of  this  flag  affects  automatic  version  control 
only  and  does  not  affect  the  search  operations  performed  by  Fi  ndNextComponent 
and  CountComponents. 
componentHasMul ti pi ePl atforms 
Undocumented 
component  Load Res i dent 
Undocumented 


Programming  Info 
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Returns  sound  compression  information  to  the  Sound  Manager, 
struct  Compressionlnfo  { 


1  ong 

recordSi ze ; 

OSType 

format ; 

short 

compressionID; 

unsi gned 

short 

sampl esPerPacket ; 

unsi gned 

short 

bytesPerPacket ; 

unsi gned 

short 

bytesPerFrame ; 

unsi gned 

short 

bytesPerSampl e ; 

unsi gned 

short 

f utureUsel ; 

}; 

recordSi ze 

The  size  in  bytes  of  this  structure, 
format 

The  compression  format. 
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compressi onID 

The  compression  ID. 
sampl esPerPacket 

The  number  of  samples  in  each  packet. 
bytesPerPacket 

The  number  of  bytes  in  each  packet. 
bytesPerFrame 

The  number  of  bytes  in  each  frame. 
bytesPerSampl e 

The  number  of  bytes  in  each  sample, 
f utureUsel 

Reserved.  Set  this  field  to  0. 

Discussion 

When  the  Sound  Manager  calls  SoundComponentGetlnfo  (III— 1849)  with  the 
si  Compressi  onFactor  selector,  you  need  to  return  a  pointer  to  this  structure. 

Associated  Functions 

GetCompressionlnfo  (1-398) 

Programming  Info 
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ConnectionSpeedPrefsRecord 

The  record  of  connection  speed. 

struct  ConnectionSpeedPrefsRecord  { 
long  connecti onSpeed ; 

}; 

connecti onSpeed 

Connection  speed. 

Discussion 

The  following  code  shows  a  typical  use  of  Connecti  onSpeedPrefsRecord. 
OSErr  err; 

QTAtomContainer  prefs; 

QTAtom  prefsAtom; 
long  dataSize; 

Ptr  atomData; 
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ConnectionSpeedPrefs Record  prefrec; 


err  =  GetQuickTimePreferencetConnectionSpeedPrefsType,  &prefs); 
if  (err  ==  noErr)  { 

prefsAtom  =  QTFi ndChi 1 dBy I D ( prefs ,  kParentAtomlsContainer , 

Connecti onSpeedPrefsType ,  1,  NIL); 

if  ( IprefsAtom)  { 

//  set  the  default  setting  to  28.8kpbs 
prefrec . connecti onSpeed  =  kDataRate288ModemRate ; 

}  else  { 

err  =  QTGetAtomDataPtrtprefs ,  prefsAtom,  &dataSize,  &atomData); 
if  (dataSize  !=  si zeoft Connecti onSpeedPref sRecord ) )  { 

//  the  prefs  record  wasn't  the  right  size, 

//  so  it  must  be  corrupt  --  set  to  the  default 
prefrec . connecti onSpeed  =  kDataRate288ModemRate ; 

}  else  { 

//  everything  was  fine  --  read  the  connection  speed 
prefrec  =  *( Connecti onSpeedPrefsRecord  *)atomData; 


} 


} 


QTDi  sposeAtomContai ner ( prefs ) ; 

} 


Programming  Info 
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ControlBehaviors 


Provides  data  for  the  ParameterDataBehavior  (IV-2328)  structure. 

struct  ControlBehaviors  { 

QTAtomID  groupID; 

long  control Val ue ; 

}; 

groupID 

Group  under  control  of  this  item, 
control Val ue 

Control  value  for  comparison  purposes. 

Programming  Info 
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See  Also 

See  ParameterDataBehavi or  (IV-2328). 


ConversionBlock 

Undocumented 

{ 

desti nati on ; 
unused ; 
i nputPtr ; 
outputPtr ; 

desti nati on 

Undocumented 

unused 

Undocumented 
i nputPtr 

Undocumented 

outputPtr 

Undocumented 

Programming  Info 
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struct  ConversionBlock 
short 
short 

CmpSoundHeaderPtr 

CmpSoundHeaderPtr 

}; 


STR 


CProcRec 


Provides  data  for  a  GDevi  ce  (IV-2264)  structure. 

struct  CProcRec  { 

Handl e 

Col  orCompl ementUPP 

}; 

nxtComp 

Handle  to  next  CProcRec  structure. 


nxtComp ; 
compProc ; 
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compProc 

A  Universal  Procedure  Pointer  that  accesses  a  Col  orCompl  ementProc  callback; 
see  the  chapter  "Color  Manager"  in  Advanced  Color  Imaging  on  the  Mac  OS  (listed 
in  the  bibliography). 

Programming  Info 

C  interface  file:  Quickdraw.h 


See  Also 

See  the  gdCompProc  field  of  the  GDevi  ce  (IV-2264)  structure. 


CQDProcs 


Accesses  QuickDraw's  low-level  routines. 


struct  CQDProcs  { 

QDTextUPP 

textProc ; 

QDLineUPP 

1 i neProc ; 

QDRectUPP 

rectProc ; 

QDRRectUPP 

rRectProc ; 

QDOval UPP 

oval Proc ; 

QDArcUPP 

arcProc ; 

QDPolyUPP 

polyProc ; 

QDRgnUPP 

rgnProc ; 

QDBitsUPP 

bi tsProc ; 

QDCommentUPP 

commentProc ; 

QDTxMeasUPP 

txMeasProc ; 

QDGetPi cUPP 

getPi cProc ; 

QDPutPi cUPP 

putPi cProc ; 

QDOpcodeUPP 

opcodeProc ; 

Uni versal ProcPtr 

newProcl ; 

QDStdGl yphsUPP 

glyphsProc ; 

QDPrinterStatusUPP 

pri nterStatusProc 

Uni versal ProcPtr 

newProc4 ; 

Uni versal ProcPtr 

newProc5 ; 

Uni versal ProcPtr 

newProc6 ; 

}; 


textProc 

A  pointer  to  the  low-level  routine  that  draws  text.  The  standard  QuickDraw 
routine  is  the  StdText  procedure. 

1 i neProc 

A  pointer  to  the  low-level  routine  that  draws  lines.  The  standard  QuickDraw 
routine  is  the  StdLi  ne  procedure. 
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rectProc 

A  pointer  to  the  low-level  routine  that  draws  rectangles.  The  standard 
QuickDraw  routine  is  the  StdRect  procedure. 
rRectProc 

A  pointer  to  the  low-level  routine  that  draws  rounded  rectangles.  The  standard 
QuickDraw  routine  is  the  StdRRect  procedure. 

oval Proc 

A  pointer  to  the  low-level  routine  that  draws  ovals.  The  standard  QuickDraw 
routine  is  the  StdOval  procedure. 
arcProc 

A  pointer  to  the  low-level  routine  that  draws  arcs.  The  standard  QuickDraw 
routine  is  the  StdArc  procedure. 
polyProc 

A  pointer  to  the  low-level  routine  that  draws  polygons.  The  standard 
QuickDraw  routine  is  the  StdPoly  procedure. 

rgnProc 

A  pointer  to  the  low-level  routine  that  draws  regions.  The  standard  QuickDraw 
routine  is  the  StdRgn  procedure, 
bi tsProc 

A  pointer  to  the  low-level  routine  that  copies  bitmaps.  The  standard 
QuickDraw  routine  is  the  StdBi  ts  procedure. 
commentProc 

A  pointer  to  the  low-level  routine  for  processing  a  picture  comment.  The 
standard  QuickDraw  routine  is  the  StdComment  procedure. 

txMeasProc 

A  pointer  to  the  low-level  routine  for  measuring  text  width.  The  standard 
QuickDraw  routine  is  the  StdTxMeas  function. 
getPi cProc 

A  pointer  to  the  low-level  routine  for  retrieving  information  from  the  definition 
of  a  picture.  The  standard  QuickDraw  routine  is  the  StdGetPi  c  procedure. 
putPi cProc 

A  pointer  to  the  low-level  routine  for  saving  information  as  the  definition  of  a 
picture.  The  standard  QuickDraw  routine  is  the  StdPutPi  c  procedure. 

opcodeProc 

A  Universal  Procedure  Pointer  that  accesses  a  QDOpcodeProc  (III— 2116)  callback. 
newProcl 

The  StdPi x  bottleneck;  see  ImageCompressi  on .  h. 


STR 
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glyphsProc 

A  Universal  Procedure  Pointer  that  accesses  a  QDStdGlyphsProc  (III— 2122) 
callback.  This  callback  is  used  for  Unicode  text  drawing. 
newProc2 

Procedure  used  in  Unicode  text  drawing, 
pri nterStatusProc 

Procedure  used  to  communicate  status  between  printing  code  and  system 
imaging  code. 

newProc3  newProc4  newProc5  newProc6 

Procedures  used  to  communicate  status  between  printing  code  and  system 
imaging  code. 

Programming  Info 
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DataHChokeAtomRecord 

Undocumented 

struct  DataHChokeAtomRecord  { 
long  flags; 

long  param; 

}; 

fl  ags 

A  constant  (see  below)  that  defines  the  metrics  of  the  param  parameter, 
param 

Choke  rate  (see  below) 

flags  Constants 

kDataHChokeToMovi e Data  Rate 
The  param  parameter  is  0. 
kDataHChokeToParam 

The  param  parameter  is  bytes  per  second. 

Programming  Info 
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DataHScheduleRecord 


Provides  scheduling  information  for  scheduled  reads. 


struct  DataHSc 
T i meRecord 
1  ong 
1  ong 
Fi  xed 


heduleRecord  { 
ti meNeededBy ; 
extendedID; 
extendedVers ; 
priority; 


}; 


ti meNeededBy 

Specifies  the  time  at  which  your  data  handler  must  deliver  the  requested  data 
to  the  calling  program.  This  time  value  is  relative  to  the  time  base  that  is 
contained  in  this  time  record.  During  pre-roll  operations,  the  Movie  Toolbox 
may  use  special  values  in  certain  time  record  fields.  The  time  record  fields  in 
question  are  the  scale  and  value  fields.  By  correctly  interpreting  the  values  of 
these  fields,  your  data  handler  can  queue  up  the  pre-roll  read  requests  in  the 
most  efficient  way  for  its  device. 

extendedID 

A  constant  (see  below)  that  indicates  the  type  of  data  that  follows  in  the 
remainder  of  the  structure. 
extendedVers 

Reserved.  This  field  should  always  be  set  to  0. 
pri  ori  ty 

Indicates  the  relative  importance  of  the  data  request.  Client  programs  assign  a 
value  of  100.0  to  data  requests  the  must  be  delivered.  Lower  values  indicate 
relatively  less  critical  data.  If  your  data  handler  must  accommodate  bandwidth 
limitations  when  delivering  data,  your  component  may  use  this  value  as  an 
indication  of  which  requests  can  be  dropped  with  the  least  impact  on  the  client 
program.  As  an  example,  consider  using  priorities  in  a  frame-differenced 
movie.  Key  frames  might  have  priority  values  of  100.0,  indicating  that  they  are 
essential  to  proper  playback.  As  you  move  through  the  frames  following  a  key 
frame,  each  successive  frame  might  have  a  lower  priority  value.  Once  you  drop 
a  frame,  you  must  drop  all  successive  frames  of  equal  or  lower  priority  until 
you  reach  another  key  frame,  because  each  of  these  frames  would  rely  on  the 
dropped  one  for  some  image  data. 

extendedID  Constants 

kDataHExtendedSchedul e 

The  remainder  of  the  structure  contains  extended  scheduling  information. 


STR 
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Discussion 

There  are  two  types  of  preroll  read  operations.  The  first  type  is  a  required  read;  that 
is,  the  Movie  Toolbox  requires  that  the  read  operation  be  satisfied  before  the  movie 
starts  playing.  The  second  type  is  an  optional  read.  If  your  data  handler  can  satisfy 
the  read  operation  as  part  of  the  pre-roll  operation,  it  should  do  so.  Otherwise,  your 
data  handler  may  satisfy  the  request  at  a  specified  time  while  the  movie  is  playing. 
The  Movie  Toolbox  indicates  that  a  preroll  read  request  is  required  by  setting  the 
scale  field  of  the  time  record  to  -1 .  This  literally  means  that  the  request  is  scheduled 
for  a  time  that  is  infinitely  far  into  the  future.  Your  data  handler  should  collect  all 
such  read  requests,  order  them  most  efficiently  for  your  device,  and  process  them 
when  the  Movie  Toolbox  calls  your  component's  DataHFi  ni  shData  (1-182)  function. 
For  optional  preroll  read  requests,  the  Movie  Toolbox  sets  the  scale  field  properly, 
but  negates  the  contents  of  the  value  field.  Your  data  handler  has  the  option  of 
delivering  the  data  for  this  request  with  the  required  data,  if  that  can  be  done 
efficiently.  Otherwise,  your  data  handler  may  deliver  the  data  at  its  schedule  time. 
You  determine  the  scheduled  time  by  negating  the  contents  of  the  value  field  (that 
is,  multiplying  by  -1). 

Programming  Info 
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DataH  V  olumeListRecord 

Contains  data-handler  access  information  for  a  volume. 

struct  DataHVolumeListRecord  { 
short  vRefNum; 

long  flags; 

}; 

vRefNum 

The  volume  reference  number  assigned  to  the  volume, 
fl  ags 

Flags  that  indicate  the  level  of  support  your  data  handler  can  provide  for  this 
volume.  These  flags  are  similar  to  those  defined  for  DataHCanUseDataRef  (1-1 75), 
though  there  is  one  additional  flag.  Your  component  should  set  appropriate 
flags  to  1  and  set  unused  flags  to  0. 

flags  Constants 

kDataHCanRead 

Indicates  that  your  data  handler  can  read  from  the  volume. 
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kDataHSpeci al Read 

Indicates  that  your  data  handler  can  read  from  the  volume  using  a  specialized 
method.  For  example,  your  data  handler  might  support  access  to  networked 
multimedia  servers  using  a  special  protocol.  In  that  case,  your  component 
would  set  this  flag  to  1  whenever  the  volume  resides  on  a  supported  server. 
kDataHSpeci a  1  Read Fi 1 e 

Reserved  for  use  by  Apple. 
kDataHCanWri te 

Indicates  that  your  data  handler  can  write  data  to  the  volume.  In  particular,  use 
this  flag  to  indicate  that  your  data  handler's  DataHPutData  (1-216)  function  will 
work  with  this  volume. 
kDataHSpeci al Wri te 

Indicates  that  your  data  handler  can  write  to  the  volume  using  a  specialized 
method.  As  with  the  kDataHSpeci  al  Read  flag,  your  data  handler  would  use  this 
flag  to  indicate  that  your  component  can  access  the  volume  using  specialized 
support  (for  example,  special  network  protocols). 

kDataHCanStreami ngWri te 

Indicates  that  your  data  handler  can  support  the  special  write  functions  for 
capturing  movie  data  when  writing  to  this  volume. 

kDataHMustCheckDataRef 

Instructs  the  calling  program  that  your  component  must  check  each  data 
reference  before  it  can  accurately  report  its  capabilities.  If  you  set  this  flag  to  1, 
the  Movie  Toolbox  will  call  your  component's  DataHCanUseDataRef  (1-175) 
function  before  it  assigns  a  container  to  your  data  handler.  Note,  however,  that 
this  may  slow  the  data  handler  selection  process  somewhat. 

Programming  Info 
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DataRateParams 


Communicates  information  to  compressors  that  can  constrain  compressed  data  to  a 
specific  data  rate. 

struct  DataRateParams  { 


1  ong 

dataRate; 

1  ong 

dataOverrun ; 

1  ong 

f rameDurati on ; 

1  ong 

keyFrameRate ; 

CodecQ 

mi nSpati al Qual i ty ; 
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DataRateParams 


CodecQ  minTemporal Qual i ty ; 

}; 

dataRate 

Specifies  the  bytes  per  second  to  which  the  data  rate  must  be  constrained. 
dataOverrun 

Indicates  the  current  number  of  bytes  above  or  below  the  desired  data  rate.  A 
value  of  0  means  that  the  data  rate  is  being  met  exactly.  If  your  application 
doesn't  know  the  data  overrun,  it  should  set  this  field  to  0. 
f rameDurati on 

Specifies  the  duration  of  the  current  frame  in  milliseconds. 
keyFrameRate 

Indicates  the  frequency  of  key  frames.  This  frequency  is  normally  identical  to 
the  key  frame  rate  passed  to  the  CompressSequenceBegi  n  (1-119). 
mi nSpati al Qual i ty 

A  constant  (see  below)  that  specifies  the  minimum  spatial  quality  the 
compressor  should  use  to  meet  the  requested  data  rate, 
mi nTemporal Qual i ty 

A  constant  (see  below)  that  specifies  the  minimum  temporal  quality  the 
compressor  should  use  to  meet  the  requested  data  rate. 

minSpatialQuality,  minTemporalQuality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 

codec Normal Qual i ty 

Image  reproduction  of  normal  quality. 
codecHI ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 
codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field. 
codecLosslessQuallty 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 
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Discussion 

The  CodecQ  data  type  defines  a  field  that  identifies  the  quality  characteristics  of  a 
given  image  or  sequence.  Note  that  individual  components  may  not  implement  all 
the  quality  levels  shown  here.  In  addition,  components  may  implement  other 
quality  levels  in  the  range  from  codecMi  nQual  i  ty  to  codecMaxQual  i  ty.  Relative 
quality  should  scale  within  the  defined  value  range.  Values  above 
codecLosslessQuality  are  reserved  for  use  by  individual  components. 

Associated  Functions 

GetCSequenceDataRateParams  (1-403) 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

See  Also 

For  a  given  compression  operation,  your  application  can  determine  the  quality  that 
the  component  supports  by  calling  GetCompressionTime  (1-401). 
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A  data  reference  to  data  of  some  type. 

struct  DataReferenceRecord  { 

OSType  dataRefType; 

Handle  dataRef; 

}; 

dataRefType 

Specifies  the  type  of  data  reference.  For  an  alias  data  reference,  you  set  the 
parameter  to  rAl  i  asType,  indicating  that  the  reference  is  an  alias.  For  a  handle 
data  reference,  set  the  parameter  to  Handl  eDataHandl  erSubType. 

dataRef 

Specifies  the  actual  data  reference.  This  parameter  contains  a  handle  to  the 
information  that  identifies  the  file  to  be  used.  The  type  of  information  stored  in 
the  handle  depends  on  the  value  of  the  dataRefType  parameter.  For  example,  if 
your  application  is  loading  the  movie  from  a  file,  this  parameter  would  contain 
an  alias  to  the  movie  file. 


Programming  Info 

C  interface  file:  Movi  es  .  h 
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Digitizerlnfo 


Contains  information  about  the  capabilities  and  current  status  of  a  video  digitizer 
component. 

struct  Digitizerlnfo  { 


short 

vdi gType ; 

1  ong 

inputCapability Flags; 

1  ong 

outputCapability Flags; 

1  ong 

i nputCurrentFl ags ; 

1  ong 

outputCurrentFlags; 

short 

slot; 

GDHandl e 

gdh  ; 

GDHandl e 

maskgdh ; 

short 

mi nDestHei ght ; 

short 

mi nDestWi dth ; 

short 

maxDestHei ght ; 

short 

maxDestWi dth ; 

short 

bl endLevel s ; 

1  ong 

1; 

reserved ; 

vdi gType 

Constant  (see  below)  that  specifies  the  type  of  video  digitizer  component, 
i nputCapabi 1 i ty FI ags 

Constant  (see  below)  that  specifies  the  capabilities  of  the  video  digitizer 
component  with  respect  to  the  input  video  signal. 
outputCapabilityFlags 

Constant  (see  below)  that  specifies  the  capabilities  of  the  video  digitizer 
component  with  respect  to  the  output  digitized  video  information. 

i nputCurrentFl ags 

Specifies  the  current  status  of  the  video  digitizer  with  respect  to  the  input  video 
signal.  Video  digitizer  components  report  their  current  input  status  by 
returning  a  flags  field  that  contains  1  bit  for  each  of  the  applicable 
i  nputCapabi  1  i  ty  FI  ags  constants  (see  below),  plus  additional  i  nputCurrentFl  ags 
constants  (see  below)  as  appropriate.  The  digitizer  component  sets  these  flags 
to  reflect  its  current  status.  When  reporting  input  status,  for  example,  a  video 
digitizer  component  sets  the  digilnDoesGenLock  flag  to  1  whenever  the  digitizer 
component  is  deriving  its  time  signal  from  the  input  video.  When  reporting  its 
input  capabilities,  the  digitizer  component  sets  this  flag  to  1  to  indicate  that  it 
can  derive  its  timing  from  the  input  video. 
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outputCurrentFlags 

Specifies  the  current  status  of  the  video  digitizer  with  respect  to  the  output 
video  signal.  Video  digitizer  components  report  their  current  output  status  by 
returning  a  flags  field  that  contains  1  bit  for  each  of  the  applicable 
outputCapabi 1 i ty FI ags  constants  (see below) 

si  ot 

Identifies  the  slot  that  contains  the  video  digitizer  interface  card, 
gdh 

Contains  a  handle  to  the  graphics  device  that  defines  the  screen  to  which  the 
digitized  data  is  to  be  written.  Set  this  field  to  N I L  if  your  application  is  not 
constrained  to  a  particular  graphics  device, 
maskgdh 

Contains  a  handle  to  the  graphics  device  that  contains  the  mask  plane.  This 
field  is  used  only  by  digitizers  that  clip  by  means  of  mask  planes, 
mi  nDesthlei  ght 

Indicates  the  smallest  height  value  the  digitizer  component  can  accommodate 
in  its  destination. 

mi  nDestWi dth 

Indicates  the  smallest  width  value  the  digitizer  component  can  accommodate 
in  its  destination. 
maxDestHei ght 

Indicates  the  largest  height  value  the  digitizer  component  can  accommodate  in 
its  destination. 
maxDestWi dth 

Indicates  the  largest  width  value  the  digitizer  component  can  accommodate  in 
its  destination. 

bl  endLevel  s 

Specifies  the  number  of  blend  levels  the  video  digitizer  component  supports, 
reserved 

Reserved.  Set  this  field  to  0. 

vdigType  Constants 

vdTypeBasi c 

Basic  video  digitizer;  does  not  support  any  clipping. 
vdTypeAl pha 

Supports  clipping  by  means  of  an  a  1  pha  channel. 
vdTypeMask 

Supports  clipping  by  means  of  a  mask  plane. 
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vdTypeKey 

Supports  clipping  by  means  of  key  colors. 

inputCapabilityFlags  Constants 

di gi InDoesNTSC 

Indicates  that  the  video  digitizer  supports  National  Television  System 
Committee  (NTSC)  format  input  video  signals.  This  flag  is  set  to  1  if  the 
digitizer  component  supports  NTSC  video. 

di gi InDoesPAL 

Indicates  that  the  video  digitizer  component  supports  Phase  Alternation  Line 
(PAL)  format  input  video  signals.  This  flag  is  set  to  1  if  the  digitizer  component 
supports  PAL  video. 

di gi  InDoesSECAM 

Indicates  that  the  video  digitizer  component  supports  Systeme  Electronique 
Couleur  avec  Memoire  (SECAM)  format  input  video  signals.  This  flag  is  set  to 
1  if  the  digitizer  component  supports  SECAM  video, 
di gi InDoesGenLock 

Indicates  that  the  video  digitizer  component  supports  genlock;  that  is,  the 
digitizer  can  derive  its  timing  from  an  external  time  base.  This  flag  is  set  to  1  if 
the  digitizer  component  supports  genlock. 

di gi  In  Does Compos i te 

Indicates  that  the  video  digitizer  component  supports  composite  input  video. 
This  flag  is  set  to  1  if  the  digitizer  component  supports  composite  input. 

di gi tlnDoesSVi deo 

Indicates  that  the  video  digitizer  component  supports  s-video  input  video.  This 
flag  is  set  to  1  if  the  digitizer  component  supports  s-video  input, 
di gi  In  Does Component 

Indicates  that  the  video  digitizer  component  supports  RGB  input  video.  This 
flag  is  set  to  1  if  the  digitizer  component  supports  RGB  input. 

di gi InVTR„Broadcast 

Indicates  that  the  video  digitizer  component  can  distinguish  between  an  input 
signal  that  emanates  from  a  videotape  player  and  a  broadcast  signal.  This  flag 
is  set  to  1  if  the  digitizer  component  can  differentiate  between  the  two  different 
signal  types. 

di gi  InDoesCol or 

Indicates  that  the  video  digitizer  component  supports  color  input.  This  flag  is 
set  to  1  if  the  digitizer  component  can  accept  color  input. 
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di gi InDoesBW 

Indicates  that  the  video  digitizer  component  supports  grayscale  input.  This  flag 
is  set  to  1  if  the  digitizer  component  can  accept  grayscale  input. 

outputCapabilityFlags  Constants 

di gi OutDoesl 

Indicates  that  the  video  digitizer  component  can  work  with  pixel  maps  that 
contain  1-bit  pixels.  If  this  flag  is  set  to  1,  then  the  digitizer  component  can  write 
images  that  contain  1-bit  pixels.  If  this  flag  is  set  to  0,  then  the  digitizer 
component  cannot  handle  such  images. 

di gi 0utDoes2 

Indicates  that  the  video  digitizer  component  can  work  with  pixel  maps  that 
contain  2-bit  pixels.  If  this  flag  is  set  to  1,  then  the  digitizer  component  can  write 
images  that  contain  2-bit  pixels.  If  this  flag  is  set  to  0,  then  the  digitizer 
component  cannot  handle  such  images. 

di gi 0utDoes4 

Indicates  that  the  video  digitizer  component  can  work  with  pixel  maps  that 
contain  4-bit  pixels.  If  this  flag  is  set  to  1,  then  the  digitizer  component  can  write 
images  that  contain  4-bit  pixels.  If  this  flag  is  set  to  0,  then  the  digitizer 
component  cannot  handle  such  images, 
di gi 0utDoes8 

Indicates  that  the  video  digitizer  component  can  work  with  pixel  maps  that 
contain  8-bit  pixels.  If  this  flag  is  set  to  1,  then  the  digitizer  component  can  write 
images  that  contain  8-bit  pixels.  If  this  flag  is  set  to  0,  then  the  digitizer 
component  cannot  handle  such  images. 

di gi 0utDoesl6 

Indicates  that  the  video  digitizer  component  can  work  with  pixel  maps  that 
contain  16-bit  pixels.  If  this  flag  is  set  to  1,  then  the  digitizer  component  can 
write  images  that  contain  16-bit  pixels.  If  this  flag  is  set  to  0,  then  the  digitizer 
component  cannot  handle  such  images. 

di gi 0utDoes32 

Indicates  that  the  video  digitizer  component  can  work  with  pixel  maps  that 
contain  32-bit  pixels.  If  this  flag  is  set  to  1,  then  the  digitizer  component  can 
write  images  that  contain  32-bit  pixels.  If  this  flag  is  set  to  0,  then  the  digitizer 
component  cannot  handle  such  images, 
di gi OutDoesDi ther 

Indicates  that  the  video  digitizer  component  supports  dithering.  If  this  flag  is 
set  to  1,  the  component  supports  dithering  of  colors.  If  this  flag  is  set  to  0,  the 
digitizer  component  does  not  support  dithering. 
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digiOutDoesStretch 

Indicates  that  the  video  digitizer  component  can  stretch  images  to  arbitrary 
sizes.  If  this  flag  is  set  to  1,  the  digitizer  component  can  stretch  images.  If  this 
flag  is  set  to  0,  the  digitizer  component  does  not  support  stretching, 
di gi OutDoesShri nk 

Indicates  that  the  video  digitizer  component  can  shrink  images  to  arbitrary 
sizes.  If  this  flag  is  set  to  1,  the  digitizer  component  can  shrink  images.  If  this 
flag  is  set  to  0,  the  digitizer  component  does  not  support  shrinking. 

di gi OutDoesMask 

Indicates  that  the  video  digitizer  component  can  handle  clipping  regions.  If  this 
flag  is  set  to  1,  the  digitizer  component  can  mask  to  an  arbitrary  clipping  region. 
If  this  flag  is  set  to  0,  the  digitizer  component  does  not  support  clipping  regions, 
di  gi OutDoesDoubl e 

Indicates  that  the  video  digitizer  component  supports  stretching  to  quadruple 
size  when  displaying  the  output  video.  The  parameters  for  the  stretch 
operation  are  specified  in  the  matrix  structure  for  the  request;  the  component 
modifies  the  scaling  attributes  of  the  matrix.  If  this  flag  is  set  to  1,  the  digitizer 
component  can  stretch  an  image  to  exactly  four  times  its  original  size,  up  to  the 
maximum  size  specified  by  the  maxDestHei  ght  and  maxDestWi  dth  fields.  If  this 
flag  is  set  to  0,  the  digitizer  component  does  not  support  stretching  to 
quadruple  size, 
di gi OutDoesQuad 

Indicates  that  the  video  digitizer  component  supports  stretching  an  image  to  16 
times  its  original  size  when  displaying  the  output  video.  The  parameters  for  the 
stretch  operation  are  specified  in  the  matrix  structure  for  the  request;  the 
component  modifies  the  scaling  attributes  of  the  matrix.  If  this  flag  is  set  to  1, 
the  digitizer  component  can  stretch  an  image  to  exactly  16  times  its  original 
size,  up  to  the  maximum  size  specified  by  the  maxDestHei  ght  and  maxDestWi  dth 
fields.  If  this  flag  is  set  to  0,  the  digitizer  component  does  not  support  this 
capability. 

digiOutDoesQuarter 

Indicates  that  the  video  digitizer  component  can  shrink  an  image  to 
one-quarter  of  its  original  size  when  displaying  the  output  video.  The 
parameters  for  the  shrink  operation  are  specified  in  the  matrix  structure  for  the 
request;  the  component  modifies  the  scaling  attributes  of  the  matrix.  If  this  flag 
is  set  to  1,  the  digitizer  component  can  shrink  an  image  to  exactly  one-quarter 
of  its  original  size,  down  to  the  minimum  size  specified  by  the  minDestHeight 
and  minDestWidth  fields.  If  this  flag  is  set  to  0,  the  digitizer  component  does  not 
support  this  capability. 
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di gi Out Does Si xteenth 

Indicates  that  the  video  digitizer  component  can  shrink  an  image  to  1/16  of  its 
original  size  when  displaying  the  output  video.  The  parameters  for  the  shrink 
operation  are  specified  in  the  matrix  structure  for  the  request;  the  digitizer 
component  modifies  the  scaling  attributes  of  the  matrix.  If  this  flag  is  set  to  1, 
the  digitizer  component  can  shrink  an  image  to  exactly  1/16  of  its  original  size, 
down  to  the  minimum  size  specified  by  the  mi  nDestHei  ght  and  mi  nDestWi  dth 
fields.  If  this  flag  is  set  to  0,  the  digitizer  component  does  not  support  this 
capability, 
di gi OutDoesRotate 

Indicates  that  the  video  digitizer  component  can  rotate  an  image  when 
displaying  the  output  video.  The  parameters  for  the  rotation  are  specified  in  the 
matrix  structure  for  an  operation.  If  this  flag  is  set  to  1,  the  digitizer  component 
can  rotate  the  image.  If  this  flag  is  set  to  0,  the  digitizer  component  cannot  rotate 
the  resulting  image. 

di gi OutDoesHori z  F 1  ip 

Indicates  that  the  video  digitizer  component  can  flip  an  image  horizontally 
when  displaying  the  output  video.  The  parameters  for  the  horizontal  flip  are 
specified  in  the  matrix  structure  for  an  operation.  If  this  flag  is  set  to  1,  the 
digitizer  component  can  flip  the  image.  If  this  flag  is  set  to  0,  the  digitizer 
component  cannot  flip  the  resulting  image, 
di gi OutDoesVertFl i p 

Indicates  that  the  video  digitizer  component  can  flip  an  image  vertically  when 
displaying  the  output  video.  The  parameters  for  the  vertical  flip  are  specified  in 
the  matrix  structure  for  an  operation.  If  this  flag  is  set  to  1,  the  digitizer 
component  can  flip  the  image.  If  this  flag  is  set  to  0,  the  digitizer  component 
cannot  flip  the  resulting  image, 
di gi OutDoesSkew 

Indicates  that  the  video  digitizer  component  can  skew  an  image  when 
displaying  the  output  video.  Skewing  an  image  distorts  it  linearly  along  only  a 
single  axis;  for  example,  drawing  a  rectangular  image  into  a 
parallelogram-shaped  region.  The  parameters  for  the  skew  operation  are 
specified  in  the  matrix  structure  for  the  request.  If  this  flag  is  set  to  1,  the 
digitizer  component  can  skew  an  image.  If  this  flag  is  set  to  0,  the  digitizer 
component  does  not  support  this  capability. 

di gi OutDoesBl end 

Indicates  that  the  video  digitizer  component  can  blend  the  resulting  image  with 
a  matte  when  displaying  the  output  video.  The  matte  is  provided  by  the 
application  by  defining  either  an  al  pha  channel  or  a  mask  plane.  If  this  flag  is 
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set  to  1,  the  digitizer  component  can  blend.  If  this  flag  is  set  to  0,  the  digitizer 
component  does  not  support  this  capability. 

di gi OutDoesWarp 

Indicates  that  the  video  digitizer  component  can  warp  an  image  when 
displaying  the  output  video.  Warping  an  image  distorts  it  along  one  or  more 
axes,  perhaps  nonlinearly,  in  effect  "bending"  the  result  region.  The  parameters 
for  the  warp  operation  are  specified  in  the  matrix  structure  for  the  request.  If 
this  flag  is  set  to  1,  the  digitizer  component  can  warp  an  image.  If  this  flag  is  set 
to  0,  the  digitizer  component  does  not  support  this  capability. 

di gi OutDoesDMA 

Indicates  that  the  video  digitizer  component  can  write  to  any  screen  or  to 
offscreen  memory.  If  this  flag  is  set  to  1,  the  digitizer  component  can  use  DMA 
to  write  to  any  screen  or  memory  location, 
di gi OutDoesHWPl ayThru 

Indicates  that  the  video  digitizer  component  does  not  need  idle  time  in  order  to 
display  its  video.  If  this  flag  is  set  to  1,  your  application  does  not  need  to  grant 
processor  time  to  the  digitizer  component  at  normal  display  speeds. 

di gi OutDoes I LUT 

Indicates  that  the  video  digitizer  component  supports  inverse  lookup  tables  for 
indexed  color  modes.  If  this  flag  is  set  to  1,  the  digitizer  component  uses  inverse 
lookup  tables  when  appropriate. 

di gi Out Does  Key Col  or 

Indicates  that  the  video  digitizer  component  supports  clipping  by  means  of  key 
colors.  If  this  flag  is  set  to  1,  the  digitizer  component  can  clip  to  a  region  defined 
by  a  key  color, 
di gi Out Does AsyncGrabs 

Indicates  that  the  video  digitizer  component  can  operate  asynchronously.  If 
this  flag  is  set  to  1,  your  application  can  use  VDSetupBuf  f  ers  (III— 2055)  and 
VDGrabOneFrameAsync  (III — 2025). 

di gi Out Does Unreadabl eScreenBi ts 

Indicates  that  the  video  digitizer  may  place  pixels  on  the  screen  that  cannot  be 
used  when  compressing  images. 

di gi OutDoesCompress 

Indicates  that  the  video  digitizer  component  supports  compressed  source 
devices.  These  devices  provide  compressed  data  directly,  without  having  to  use 
the  Image  Compression  Manager. 
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digi Out Does Compress Only 

Indicates  that  the  video  digitizer  component  only  provides  compressed  image 
data;  the  component  cannot  provide  displayable  data.  This  flag  only  applies  to 
digitizers  that  support  compressed  source  devices. 
digiOutDoesPl ayThruDuri ngCompress 

Indicates  that  the  video  digitizer  component  can  draw  images  on  the  screen  at 
the  same  time  that  it  is  delivering  compressed  image  data.  This  flag  only 
applies  to  digitizers  that  support  compressed  source  devices. 

inputCurrentFlags  Constants 

di gi InSi gnal Lock 

Indicates  that  the  video  digitizer  component  is  locked  onto  the  input  signal.  If 
this  flag  is  set  to  1,  the  digitizer  component  detects  either  vertical  or  horizontal 
signal  lock. 

Discussion 

Your  application  can  retrieve  information  about  the  capabilities  and  current  status 
of  a  video  digitizer  component.  You  call  VDGetDi  gi  ti  zerlnfo  (III— 1998)  to  retrieve  all 
this  information  from  a  video  digitizer  component.  In  response,  the  component 
formats  a  Di  gi  ti  zerlnfo  structure.  The  contents  of  this  structure  fully  define  the 
capabilities  and  current  status  of  the  video  digitizer  component. 

Associated  Functions 

VDGetDi  gi  ti  zerlnfo  (III — 1998) 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

See  Also 

If  you  are  interested  only  in  the  current  video  digitizer  status  information,  you  can 
call  VDGetCurrentFl  ags  (III— 1996).  This  function  returns  the  input  and  output 
current  flags  of  the  video  digitizer  component. 
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Locates  and  defines  an  edit  segment  within  a  media. 

struct  EditListType  { 

TimeValue  trackDurati on ; 

TimeValue  mediaTime; 

Fixed  media  Rate; 
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trackDurati on 

The  duration  of  this  edit  segment  in  movie  time  scale  units. 
mediaTime 

The  starting  time  within  the  media  of  this  edit  segment,  expressed  in  media 
time  scale  units.  If  -1,  it  is  an  empty  edit. 

medi aRate 

The  relative  rate  at  which  to  play  the  media  for  this  edit  segment. 

Discussion 

This  is  a  struct  inside  the  edit  list  atom,  which  is  part  of  a  movie. 

Programming  Info 

C  interface  file:  MoviesFormat.h 

See  Also 

For  the  atom  structure  that  contains  EditListType  data  structures,  see  the  '  el  st ' 
(IV-2533)  atom. 


EffectsFrameParams 


Contains  information  about  the  current  frame  of  a  video  effect. 


struct  EffectsFrameParams 
ICMFrameTimeRecord 
1  ong 
Bool ean 
unsigned  char 
EffectSourcePtr 
voi  d  * 

1: 


{ 

f rameT i me ; 
effectDurati on ; 
doAsync ; 
pad [ 3 ] ; 
source ; 
refCon ; 


f rameT i me 

Timing  data  for  the  current  frame.  This  structure  includes  information  such  as 
the  total  number  of  frames  being  rendered  in  this  sequence,  and  the  current 
frame  number. 
effectDurati on 

The  duration  of  a  single  effect  frame. 
doAsync 

This  field  contains  TRUE  if  the  effect  can  process  asynchronously. 

pad 

Unused. 
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source 

A  pointer  to  the  input  sources;  see  the  EffectSource  (IV-2243)  structure. 
refCon 

A  pointer  to  storage  for  this  instantiation  of  the  effect. 

Associated  Functions 

ImageCodecEf fectBegi n  (11-698) 

Programming  Info 

C  interface  file:  ImageCodec.h 
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Provides  data  for  the  EffectsFrameParams  (IV-2242)  structure. 

struct  EffectSource  { 

long  effectType; 

Ptr  data; 

SourceData  source; 

Ef f ectSourcePtr  next; 

effectType 

The  type  of  the  effect  or  a  default  effect  type  constant  (see  below).  Enter 
kEf  fectRawSource  if  the  source  is  raw  image  compression  manager  data. 

data 

A  pointer  to  the  track  data  for  the  effect, 
source 

The  source  itself. 


next 

A  pointer  to  the  next  source  in  the  input  chain. 

1 astTransl atedFrameTime 

The  start  frame  time  of  last  converted  frame;  this  value  may  be  -1. 

1 astFrameDurati on 

The  duration  of  the  last  converted  frame;  this  value  may  be  0. 

1 astFrameT i meScal e 

The  time  scale  of  this  source  frame;  this  field  has  meaning  only  if  the 
1  astT ransl  atedFrameT i  me  and  1  astFrameDurati  on  fields  are  valid. 

effectType  Constants 

kEf fectRawSource 

The  source  is  raw  Image  Compression  Manager  data. 
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kEffectGeneri cType 

The  source  is  a  generic  effect  for  combining  other  effects, 
'geff ' 

Value  of  kEffectGeneri  cType. 

Associated  Functions 

Ima  geCodec  Ef  f  ec  t  Con  ve  r  t  Effect  So  urceTo  Format  (11-699) 

Programming  Info 

C  interface  file:  ImageCodec.h 

See  Also 

Seethe  EffectsFrameParams  (IV-2242)  structure. 


EnumListRecord 


Stores  a  constant  enumeration  as  a  struct. 

struct  EnumListRecord  { 

long  enumCount; 

EnumVal uePai r  values[l]; 

1: 


enumCount 

Number  of  enumeration  items  to  follow, 
val ues 

Values  and  names  for  the  enumeration  items,  packed.  See  EnumVal  uePai  r 
(IV-2245). 


Programming  Info 

C  interface  file:  ImageCodec.h 


EnumRangeRecord 


Undocumented 

struct  EnumRangeRecord  { 
long  enumID; 

1: 

enumID 

Undocumented 
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Discussion 

Undocumented 

Programming  Info 

C  interface  file:  ImageCodec.  h 


Enum  V  aluePair 


Provides  data  for  an  EnumLi  stRecord  (IV-2244)  structure. 

struct  EnumValuePair  { 
long  value; 

Str255  name; 


val  ue 

The  enumerated  value. 


STR 


name 

The  corresponding  name. 

Programming  Info 

C  interface  file:  ImageCodec.  h 


See  Also 

Seethe  EnumLi  stRecord  (IV-2244)  structure. 


EQSpectrumBandsRecord 


Undocumented 

struct  EQSpectrumBandsRecord  { 
short  count; 

UnsignedFixedPtr  frequency; 

}; 

count 

Undocumented 

frequency 

Undocumented 


Discussion 

Undocumented 
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Programming  Info 

C  interface  file:  Sound .  h 


EventRecord 

Contains  information  about  a  retrieved  Mac  OS  event. 

struct  EventRecord  { 

EventKi nd 
UInt32 
UInt32 
Poi  nt 

EventModi f i ers 

}; 

what 

A  constant  (see  below)  that  specifies  the  kind  of  event, 
message 

Additional  information  (see  below)  associated  with  the  event.  The 
interpretation  of  this  information  depends  on  the  event  type. 

when 

The  time  when  the  event  was  posted,  in  ticks  since  system  startup, 
where 

For  low-level  events  and  operating-system  events,  this  field  contains  the 
location  of  the  cursor  at  the  time  the  event  was  posted  (in  global  coordinates). 
For  high-level  events,  it  contains  a  second  event  specifier,  the  event  ID.  The 
event  ID  defines  the  particular  type  of  event  within  the  class  of  events  defined 
by  the  message  field  of  the  high-level  event.  For  high-level  events,  you  should 
interpret  the  where  field  as  having  the  data  type  OSType,  not  Poi  nt. 

modi f i ers 

Contains  information  about  the  state  of  the  modifier  keys  and  the  mouse 
button  at  the  time  the  event  was  posted.  For  activate  events,  this  field  also 
indicates  whether  the  window  should  be  activated  or  deactivated.  In  System  7 
it  also  indicates  whether  the  mouse-down  event  caused  your  application  to 
switch  to  the  foreground.  Each  modifier  key  is  represented  by  a  specific  bit  in 
the  modi  f  1  ers  field  of  the  event  record  structure.  The  modifier  keys  include  the 
Option,  Command,  Caps  Lock,  Control,  and  Shift  keys.  If  your  application 
attaches  special  meaning  to  any  of  these  keys  in  combination  with  other  keys  or 
when  the  mouse  button  is  down,  you  can  test  the  state  of  the  modifiers  field  to 
determine  the  action  your  application  should  take.  For  example,  you  can  use 


what ; 
message ; 
when ; 
where ; 
modi  tiers; 
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this  information  to  determine  whether  the  user  pressed  the  Command  key  and 
another  key  to  make  a  menu  choice. 

what  Constants 

nut 1  Event 

The  event  code  indicating  that  there  are  no  other  pending  events.  The  message 
field  is  undefined. 


STR 


mouseDown 

The  event  code  indicating  that  the  mouse  button  has  been  pressed.  The 
message  field  is  undefined. 
mouseUp 

The  event  code  indicating  that  the  mouse  button  has  been  released.  The 
message  field  is  undefined. 

keyDown 

The  event  code  indicating  that  a  key  has  been  pressed.  The  low-order  word  of 
the  message  field  contains  the  character  code  and  virtual  key  code,  which  you 
can  access  with  the  constants  charCodeMask  and  keyCodeMask,  respectively  (see 
below).  For  Apple  Desktop  Bus  (ADB)  keyboards,  the  low  byte  of  the 
high-order  word  contains  the  ADB  address  of  the  keyboard  where  the 
keyboard  event  occurred.  The  high  byte  of  the  high-order  word  is  reserved, 
keyllp 

The  event  code  indicating  that  a  key  has  been  released.  The  low-order  word  of 
the  message  field  contains  the  character  code  and  virtual  key  code,  which  you 
can  access  with  the  constants  charCodeMask  and  keyCodeMask,  respectively  (see 
below).  For  Apple  Desktop  Bus  (ADB)  keyboards,  the  low  byte  of  the 
high-order  word  contains  the  ADB  address  of  the  keyboard  where  the 
keyboard  event  occurred.  The  high  byte  of  the  high-order  word  is  reserved. 
autoKey 

The  event  code  indicating  that  a  key  has  been  repeatedly  held  down.  The 
low-order  word  of  the  message  field  contains  the  character  code  and  virtual  key 
code,  which  you  can  access  with  the  constants  charCodeMask  and  keyCodeMask, 
respectively  (see  below).  For  Apple  Desktop  Bus  (ADB)  keyboards,  the  low 
byte  of  the  high-order  word  contains  the  ADB  address  of  the  keyboard  where 
the  keyboard  event  occurred.  The  high  byte  of  the  high-order  word  is  reserved. 

updateEvt 

The  event  code  indicating  that  a  window  needs  updating.  The  message  field 
contains  a  pointer  to  the  window  to  update. 
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di skEvt 

The  event  code  indicating  that  a  disk  has  been  inserted.  The  message  field 
contains  the  drive  number  in  its  low-order  word  and  the  File  Manager  result 
code  in  its  high-order  word, 
acti vateEvt 

The  event  code  indicating  that  a  window  has  been  activated  or  deactivated.  The 
message  field  contains  a  pointer  to  the  window  to  activate  or  deactivate. 

osEvt 

The  event  code  indicating  a  suspend,  resume,  or  mouse-moved 
operating-system  event. 
kHi ghLevel Event 

A  high-level  event.  The  message  field  and  the  where  field  of  a  high-level  event 
define  the  specific  type  of  high-level  event  received. 
mouseMovedMessage 

The  message  code  indicating  the  mouse-moved  operating-system  event.  The 
mouseMovedMessage  enumerator  is  in  bits  24-31  of  the  message  field.  Bits  2-23  are 
reserved,  and  bit  0  and  bit  1  are  undefined. 

s us pend Res umeMes sage 

The  message  code  indicating  a  suspend  or  resume  operating-system  event.  The 
suspendResumeMessage  enumerator  in  bits  24—31  of  the  message  field  and  a  0  in 
bit  0  indicate  the  event  is  a  suspend  event.  Bit  1  is  undefined,  and  bits  2-23  are 
reserved. 
resumeFl ag 

Flag  for  a  resume  event.  The  suspendResumeMessage  enumerator  in  bits  24-31  of 
the  message  field  and  a  1  (the  resumeFl  ag  enumerator)  in  bit  0  indicate  the  event 
is  a  resume  event.  Bit  1  contains  a  1  (the  converted  i  pboardFl  ag  enumerator)  if 
Clipboard  conversion  is  required,  and  bits  2-23  are  reserved. 
convertCl i pboardFl ag 

Flag  indicating  that  Clipboard  conversion  is  required  for  a  suspend  or  resume 
event. 

message  Mask  Constants 

charCodeMask 

Retrieves  the  character  code  from  the  message  field;  value  is  OxOOOOOOFF. 
keyCodeMask 

Retrieves  the  keyboard  code  from  the  message  field;  value  is  OxOOOOFFOO. 
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adbAddrMask 

Retrieves  the  Apple  Desktop  Bus  code  from  the  message  field;  value  is 
OxOOFFOOOO. 
osEvtMessageMask 

Retrieves  the  Mac  OS  event  code  from  the  message  field;  value  is  OxFFOOOOOO. 

Associated  Functions 

ImageCodecIsStandardParameterDi  al  ogEvent  (11-726) 

Programming  Info 

C  interface  file:  Events  .  h 

See  Also 

For  further  information  about  Mac  OS  events,  see  Inside  Macintosh:  Macintosh 
Toolbox  Essentials  (listed  in  the  bibliography). 
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ExtComponentResource 


Defines  the  extended  structure  of  a  component  resource,  with  platform 
information. 


struct  ExtComponentResource 
ComponentDescri pti on 
ResourceSpec 
ResourceSpec 
ResourceSpec 
ResourceSpec 
1  ong 
1  ong 
short 
1  ong 

Component  PI atformlnfo 

}; 


{ 

cd ; 

component ; 
componentName ; 
componentlnfo; 
componentlcon ; 
componentVersi on ; 
componentRegi sterFl ags ; 
component  I  con Fami ly ; 
count ; 

pi  atformArray[l] ; 


cd 

A  ComponentDescri  pti  on  (IV-2212)  structure  that  specifies  the  characteristics  of 
the  component, 
component 

A  ResourceSpec  (IV-2402)  structure  that  specifies  the  type  and  ID  of  the 
component  code  resource.  The  resType  field  of  this  structure  may  contain  any 
value.  The  component's  main  entry  point  must  be  at  offset  0  in  the  resource. 
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componentName 

A  ResourceSpec  (IV-2402)  structure  that  specifies  the  resource  type  and  ID  for 
the  name  of  the  component.  This  is  a  Pascal  string.  Typically,  the  component 
name  is  stored  in  a  resource  of  type  '  STR  ' . 
componentlnfo 

A  ResourceSpec  (IV-2402)  structure  that  specifies  the  resource  type  and  ID  for 
the  information  string  that  describes  the  component.  This  is  a  Pascal  string. 
Typically,  the  information  string  is  stored  in  a  resource  of  type  'STR  ' .  You 
might  use  the  information  stored  in  this  resource  in  a  Get  Info  dialog  box. 

componentlcon 

A  ResourceSpec  (IV-2402)  structure  that  specifies  the  resource  type  and  ID  for 
the  icon  for  a  component.  Component  icons  are  stored  as  32-by-32  bit  maps. 
Typically,  the  icon  is  stored  in  a  resource  of  type  'ICON'.  Note  that  this  icon  is 
not  used  by  the  Finder;  you  supply  an  icon  only  so  that  other  components  or 
applications  can  display  your  component's  icon  in  a  dialog  box  if  needed. 
componentVersi on 

The  version  number  of  the  component.  If  you  specify  the 
componentDoAutoVersi  on  flag  in  componentRegi  sterFl  ags,  the  Component 
Manager  must  obtain  the  version  number  of  your  component  when  your 
component  is  registered.  Either  you  can  provide  a  version  number  in  your 
component's  resource,  or  you  can  specify  a  value  of  0  for  its  version  number.  If 
you  specify  0,  the  Component  Manager  sends  your  component  a  version 
request  to  get  the  version  number  of  your  component. 
componentRegi sterFl  ags 

A  set  of  flags  (see  below)  containing  additional  registration  information, 
component  I  con Fami ly 

The  resource  ID  of  an  icon  family.  You  can  provide  an  icon  family  in  addition 
to  the  icon  provided  in  the  componentlcon  field  of  Component  Resource  (IV-2219). 
Note  that  members  of  this  icon  family  are  not  used  by  the  Finder;  you  supply 
an  icon  family  only  so  that  other  components  or  applications  can  display  your 
component's  icon  in  a  dialog  box  if  needed, 
count 

Number  of  elements  in  pi  atformArray. 
pi atformArray 

An  array  of  ComponentPl  atformlnfo  (IV-2218)  structures. 

Programming  Info 

C  interface  file:  Components .  h 
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See  Also 

See  ComponentResource  (IV-2219),  ComponentResourceExtensi on  (IV-2221). 


ExtendedScheduledSoundHeader 


Passes  extended  sound  header  fields  to  a  sound  channel. 


struct  ExtendedScheduledSoundHeader  { 


SoundHeaderUni on 

1  ong 

short 

short 

1  ong 

T i meRecord 
1  ong 
1  ong 
1  ong 


u ; 

f 1 ags  ; 
reserved ; 
cal  1 BackParaml ; 
cal  1 BackParam2 ; 
startTime; 
recordSi ze ; 
extendedFl  ags ; 
but f erSi ze ; 


STR 


u 

A  SoundHeaderUni  on  used  to  pass  the  audio  to  the  channel, 
fl  ags 

Modifier  flags  (see  below), 
reserved 

Reserved.  Set  to  0. 
cal  1 BackParaml 

Passed  as  parameters  to  the  sound  callback  associated  with  the  channel, 
cal  1 BackParam2 

Passed  as  parameters  to  the  sound  callback  associated  with  the  channel. 
startTime 

A  T i meRecord  (IV-2486)  structure  indicating  the  time  in  the  future  when  the 
sound  buffer  should  play,  using  the  sound  clock  associated  with  the  channel. 

recordSi ze 

Holds  the  si  ze  of  the  field  in  bytes.  In  the  future  this  may  grow. 
extendedFl ags 

Constants  (see  below)  that  determine  the  interpretation  of  fields  in  different 
data  structures. 
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bufferSi ze 

The  buffer  size  in  bytes.  This  field  is  not  valid  if  the  extendedFl  ags  field's 
kExtendedSoundBufferSi  zeVal  i  d  flag  is  0. 

flags  Constants 

kScheduledSoundDoScheduled 

Indicates  that  the  startTime  field  holds  the  time  when  this  buffer  should  be 
played. 

kScheduledSoundDoCallBack 

Indicates  that  the  callback  should  be  called  when  the  buffer  completes.  This 
typically  is  used  to  chain  buffer  playbacks  together. 

extendedFlags  Constants 

kExtendedSoundSampl eCountNotValid 

The  sample  count  is  not  valid.  This  allows  a  buffer  of  audio  of  bufferSi  ze  bytes 
to  not  declare  the  number  of  audio  samples  that  it  will  generate.  Note  that  if  this 
flag  is  set,  the  bufferSi  ze  field  must  be  valid  and 
kExtendedSoundBufferSi  zeVal  i  d  must  be  1. 
kExtendedSoundBufferSi zeVal i d 

Indicates  if  the  bufferSi  ze  field  is  valid.  If  not  1,  then  you  shouldn't  use  the 
bufferSi  ze  field's  value.  The  QuickTime  4.1  Sound  Media  Handler  passes  the 
buffer  size,  so  this  flag  is  set. 

Discussion 

The  extended  forms  of  the  SoundComponentData  (IV-2448)  and  SoundParamBl  ock 
(IV-2454)  records  are  normally  all  with  which  a  sound  decompressor  implementer 
need  be  concerned. 

Version  Notes 

New  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

See  Schedul  edSoundHeader  (IV-2419). 


ExtendedSoundComponentData 


Provides  an  extended  form  of  the  SoundComponentData  (IV-2448)  structure. 

struct  ExtendedSoundComponentData  { 

SoundComponentData  desc; 

long  recordSize; 
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long  extendedFl  ags ; 

long  bufferSize; 

}; 

desc 

A  SoundComponentData  (IV-2448)  structure  describing  a  sound  buffer.  This  may 
be  an  ExtendedSoundComponentData  (IV-2252)  structure.  To  determine  which, 
check  for  kExtendedSoundData  in  the  f  1  ags  field. 
recordSi ze 

The  number  of  bytes  in  the  buffer.  This  allows  for  cases  where  the  number  of 
bytes  isn't  derivable  directly  from  the  number  of  samples. 

extendedFl ags 

Constants  (see  below)  that  determine  the  interpretation  of  fields  in  different 
data  structures, 
but f erSi ze 

Size  of  the  buffer  in  bytes. 

extendedFlags  Constants 

kExtended Sound Samp! eCountNotVal i d 

The  sample  count  is  not  valid.  This  allows  a  buffer  of  audio  of  buffers  ize  bytes 
to  not  declare  the  number  of  audio  samples  that  it  will  generate.  Note  that  if  this 
flag  is  set,  the  buffers  ize  field  must  be  valid  and 
kExtendedSoundBuf  f  erSi  zeVal  i  d  must  be  1. 

kExtended Sou ndBuf f erSi zeVal i d 

Indicates  if  the  bufferSi  ze  field  is  valid.  If  not  1,  then  you  shouldn't  use  the 
buf  ferSi  ze  field's  value.  The  QuickTime  4.1  Sound  Media  Handler  passes  the 
buffer  size,  so  this  flag  is  set. 

Discussion 

While  the  ability  to  not  specify  the  sample  count  is  of  little  use  where  the  sample 
references  already  describes  the  durations  of  all  the  samples,  it  may  prove  more 
useful  in  other  cases.  One  such  case  involves  sound  conversion  where  the 
decompressor  is  asked  to  generate  audio  samples  until  a  source  buffer  is  exhausted. 
Instead  of  requiring  that  we  know  the  number  of  source  audio  samples  in  advance, 
this  allows  the  client  to  just  feed  audio  until  there  is  no  more.  Another  case  involves 
playback  where  durations  aren't  known. 

Version  Notes 

New  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Sound .  h 
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See  Also 

See  SoundComponentData  (IV-2448). 


ExtendedSoundParamBlock 


Provides  an  extended  form  ofSoundParamBlock  (IV-2454). 

struct  ExtendedSoundParamBlock  { 

SoundParamBl ock  pb; 
short  reserved; 

long  extendedFl  ags ; 

long  bufferSize; 

}; 

pb 

A  SoundParamBl  ock  (IV-2454)  structure.  Measuring  its  recordSi  ze  field  lets  you 
tell  if  it  is  an  ExtendedSoundParamBl  ock  (IV-2254)  structure.  Since  the  embedded 
SoundParamBl  ock  structure  contains  a  SoundComponentData  field,  the 
kExtendedSoundSampl  eCountNotVal  i  d  flag  set  refers  to  the  sampl  eCount  field  of 
that  structure.  The  flags  field  of  the  embedded  SoundComponentData  structure 
should  never  have  its  kExtendedSoundData  flag  set.  This  would  mislead  a  client 
passed  only  a  pointer  to  SoundComponentData  structure  to  misinterpret  it  as  an 
extended  structure, 
reserved 

Reserved;  ignore. 
extendedFl ags 

Constants  (see  below)  that  determine  the  interpretation  of  fields  in  different 
data  structures. 

bufferSi ze 

Size  of  the  buffer  in  bytes. 

extendedFlags  Constants 

kExtendedSoundSampl eCountNotVal id 

The  sample  count  is  not  valid.  This  allows  abutter  of  audio  of  bufferSi  ze  bytes 
to  not  declare  the  number  of  audio  samples  that  it  will  generate.  Note  that  if  this 
flag  is  set,  the  bufferSize  field  must  be  valid  and 
kExtendedSoundBufferSi  zeVal  i  d  must  be  1. 

kExtendedSoundBufferSi zeVal i d 

Indicates  if  the  bufferSi  ze  field  is  valid.  If  not  1,  then  you  shouldn't  use  the 
bufferSi  ze  field's  value.  The  QuickTime  4.1  Sound  Media  Handler  passes  the 
buffer  size,  so  this  flag  is  set. 
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Discussion 

An  ExtendedSoundParamBl  ock  structure  can  be  passed  to  a  sound  component's 
SoundComponentPl  aySourceBuf  f  er  (III— 1854)  routine.  Also,  the  moreRtn  of  the 
SoundParamBlock  (IV-2454)  structure  may  return  a  reference  to  an 
ExtendedSoundParamBl  ock  structure. 

Version  Notes 

New  in  QuickTime  4.1. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

See  SoundParamBl  ock  (IV-2454). 
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ExtSoundHeader 


Stores  sampled-sound  data  that  is  more  complex  than  a  SoundHeader  (IV-2452) 
structure  can  describe. 

struct  ExtSoundHeader  { 


Ptr 

samp! ePtr ; 

unsi gned 

1  ong 

numChannel s ; 

Unsi gnedFi xed 

sampl eRate ; 

unsi gned 

1  ong 

1 oopStart; 

unsi gned 

1  ong 

1 oopEnd ; 

UInt8 

encode ; 

UInt8 

baseFrequency ; 

unsi gned 

1  ong 

numFrames ; 

extended80 

AI FFSampl eRate ; 

Ptr 

markerChunk; 

Ptr 

i  nstrumentChunks ; 

Ptr 

AESRecordi ng ; 

unsi gned 

short 

sampl eSi ze ; 

unsi gned 

short 

f utureUsel ; 

unsi gned 

1  ong 

f utureUse2 ; 

unsi gned 

1  ong 

f utureUse3 ; 

unsi gned 

1  ong 

f utureUse4 ; 

UInt8 

sampleArea[l] ; 

}; 

samp! ePtr 

A  pointer  to  the  sampled-sound  data.  If  the  sampled  sound  is  located  in 
memory  immediately  after  the  f  utureUse4  field,  then  this  field  should  be  set  to 
N I L.  Otherwise,  this  field  is  a  pointer  to  the  memory  location  of  the 
sampled-sound  data. 
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numChannel s 

The  number  of  channels  in  the  sample, 
sampl eRate 

The  sample  rate  at  which  the  frames  were  sampled  before  compression;  see 
"Sound  Sample  Rates"  (IV-2695). 

1 oopStart 

The  starting  point  of  the  portion  of  the  extended  sampled  sound  header  that  is 
to  be  used  by  the  Sound  Manager.  These  loop  points  specify  the  byte  numbers 
in  the  sampled  data  to  be  used  as  the  beginning  and  end  points  to  cycle  through 
when  playing  the  sound.  The  loop  starting  and  ending  points  are  0-based. 

1 oopEnd 

The  end  of  the  loop  points  of  the  sound  before  compression, 
encode 

The  method  of  encoding  (if  any)  used  to  generate  the  sampled-sound  data  (see 
below).  For  a  compressed  sound  header,  you  should  specify  the  constant  cmpSH. 
Encode  option  values  in  the  ranges  0  through  63  and  128  to  255  are  reserved  for 
use  by  Apple.  You  are  free  to  use  numbers  in  the  range  64  through  127  for  your 
own  encode  options. 
baseFrequency 

The  pitch  of  the  original  sampled  sound. 
numFrames 

The  number  of  frames  in  the  sampled-sound  data.  Each  frame  contains 
numChannel  s  bytes  for  8-bit  sound  data. 

AI FFSampl eRate 

The  sample  rate  at  which  the  frames  were  sampled  before  compression,  as 
expressed  in  the  80-bit  extended  data  type  representation  (IEEE  sample  rate). 

markerChunk 

Synchronization  information.  The  markerChunk  field  is  not  presently  used  and 
should  be  set  to  NIL. 
i nstrumentChunks 

AIFF  Instrument  information. 

AESRecordi ng 

Information  related  to  audio  recording  devices, 
sampl eSi ze 

The  number  of  bits  in  each  sample  frame, 
f  uturellsel 
Reserved. 
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f utureUse2 
Reserved, 
f utureUse3 
Reserved, 
f utureUse4 

The  four  f  uturellse  fields  are  reserved  for  use  by  Apple.  To  maintain 
compatibility  with  future  versions  of  system  software,  you  should  always  set 
these  fields  to  0. 
sampl eArea 

An  array  of  interleaved  sample  points,  each  of  which  contains  a  value  similar 
to  the  values  in  a  wave-table  description.  For  8-bit  sampled-sound  data,  these 
values  are  interpreted  as  offset  values,  where  0x80  represents  an  amplitude  of 
0.  The  value  0x00  is  the  largest  negative  amplitude,  and  OxFF  is  the  largest 
positive  amplitude. 

encode  Constants 

cmpSH 

Compressed  sound  header;  value  is  OxFE. 
extSH 

Extended  sound  header;  value  is  OxFF. 
stdSH 

Standard  sound  header;  value  is  0x00. 

Discussion 

Most  of  the  fields  of  the  extended  sound  header  correspond  to  fields  of  the  sampled 
sound  header.  However,  the  extended  sound  header  allows  the  encoding  of  stereo 
sound.  The  numChannel  s  field  contains  the  number  of  channels  of  sound  recorded, 
and  the  numFrames  field  contains  the  number  of  frames  of  sound  recorded  in  each 
channel.  To  compute  the  total  number  of  bytes  of  a  sample,  multiply  the  values  in 
the  numChannel  s,  numFrames,  and  sampl  eSi  ze  fields  and  divide  by  the  number  of  bytes 
per  sample  (typically  8  or  16). 

Version  Notes 

Although  ExtSoundHeader  and  CmpSoundHeader  (IV-2176)  support  the  storage  of 
16-bit  sound,  only  versions  3.0  and  later  of  the  Sound  Manager  can  play  16-bit 
sounds.  If  your  application  uses  16-bit  sound,  you  must  convert  it  to  8-bit  sound 
before  earlier  versions  of  the  Sound  Manager  can  play  it. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

See  CmpSoundHeader  (IV-2176). 
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FieldlnfoImageDescriptionExtension 


FieldlnfoImageDescriptionExtension 

Undocumented 

struct  Fi el dlnfoImageDescri pti onExtensi on  { 
UInt8  fieldCount; 

UInt8  f i el dOrderi ngs ; 

}; 

f i el dCount 

Undocumented 
f i el dOrderi ngs 
Undocumented 

Discussion 

Undocumented 

Programming  Info 

C  interface  file:  ImageCodec.h 


FieldInfoImageDescriptionExtension2 


Remaps  to  Fiel  dlnfoImageDescriptionExtension  (IV-2258). 

struct  Fi el dlnfoImageDescri pti onExtensi on2  { 

UInt8  fields: 

UInt8  detai  1  ; 

}; 

f i el ds 

Undocumented 
detai 1 

Undocumented 

Discussion 

Undocumented 

Programming  Info 

C  interface  file:  ImageCodec.h 


FixedPoint 


Defines  the  position  of  a  geometric  point  in  fixed-point  numbers. 
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struct  FixedPoint  { 

Fixed  x; 

Fixed  y; 

}; 

x 

The  x  (horizontal)  coordinate  of  the  point, 

y 

The  y  (vertical)  coordinate  of  the  point. 

Special  Considerations 

This  function  differs  from  the  Point  (IV-2339)  function  in  that  its  parameters  are 
fixed-point  numbers  and  the  order  of  horizontal  and  vertical  parameters  is 
reversed. 

Associated  Functions 

CurveGetNearestPathPoi  nt  (1-156) 

Programming  Info 

C  interface  file:  MacTypes .  h 
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FixedRangeRecord 


Undocumented. 

struct  FixedRangeRecord  { 
Fixed  minValue; 

Fixed  maxValue; 

Fixed  scaleValue; 

long  preci si onDi gi ts  ; 

}; 

mi nVal ue 

Undocumented 
maxVal ue 

Undocumented 
seal eVal ue 

Undocumented 
preci si onDi gi ts 
Undocumented 


Discussion 

Undocumented 
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Programming  Info 

C  interface  file:  ImageCodec.  h 


FixedRect 

Defines  the  size  and  location  of  a  rectangle  in  fixed-point  numbers. 

struct  FixedRect  { 

Fixed  left; 

Fixed  top; 

Fixed  right; 

Fixed  bottom: 

1: 

1  eft 

The  x  coordinate  of  the  upper-left  comer  of  the  rectangle. 

top 

The  y  coordinate  of  the  upper-left  corner  of  the  rectangle, 
ri  ght 

The  x  coordinate  of  the  lower-right  corner  of  the  rectangle, 
bottom 

The  y  coordinate  of  the  lower-right  corner  of  the  rectangle. 

Special  Considerations 

This  structure  differs  from  the  Rect  (IV-2399)  structure  in  that  its  parameters  are 
fixed-point  numbers  and  their  order  is  different. 

Associated  Functions 

TransformFi xedRect  (III — 1952) 

Programming  Info 

C  interface  file:  MacTypes .  h 

See  Also 

See  Inside  Macintosh:  Imaging  With  QidckDrazv  (listed  in  the  bibliography). 


FlashDescription 

Undocumented 

struct  FlashDescription  { 
long  descSize; 

long  dataFormat; 
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1  ong 

resvdl ; 

short 

resvd2 ; 

short 

dataRef Index; 

1  ong 

versi on ; 

OSType 

decompressorType ; 

1  ong 

fl ags  ; 

}; 

descSi ze 

Undocumented 
data  Format 

Undocumented 

resvdl 

Undocumented 

resvd2 

Undocumented 
dataRef Index 

Undocumented 
versi on 

Undocumented 

decompressorType 

The  decompressor  to  use;  0  for  no  decompression, 
fl  ags 

Undocumented 

Discussion 

Undocumented 

Programming  Info 

C  interface  file:  Movi  es  .  h 

See  Also 

Undocumented 
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Fontlnfo 

Contains  dimensional  information  for  the  current  font. 

struct  Fontlnfo  { 
short  ascent; 
short  descent; 
short  widMax; 
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short  leading; 

}; 

ascent 

The  measurement  in  pixels  from  the  baseline  to  the  ascent  line  of  the  font, 
descent 

The  measurement  in  pixels  from  the  baseline  to  the  descent  line  of  the  font, 
wi dMax 

The  width  in  pixels  of  the  widest  glyph  in  the  font. 

1 eadi ng 

The  measurement  in  pixels  from  the  descent  line  to  the  ascent  line  below  it. 

Associated  Functions 

QDTxMeasProc  (III — 2123) 

Programming  Info 

C  interface  file:  QuickdrawText.h 


FSSpec 


Identifies  a  Mac  OS  file  or  directory. 

struct  FSSpec  { 
short 
1  ong 

StrFi 1 eName 

}; 

vRef Num 

Volume  reference  number. 
parlD 

Directory  ID  of  parent  directory. 

name 

Filename  or  directory  name;  a  Str63  string  on  the  Mac  OS. 

Discussion 

The  FSSpec  structure  provides  a  simple  and  standard  format  for  specifying  files  and 
directories.  You  can  pass  that  specification  directly  to  any  file-manipulation 
routines  that  accept  FSSpec  records. 

Associated  Functions 

ConvertMovi  eToFi  1  e  (1-134) 


vRef Num ; 
parlD; 
name ; 
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Programming  Info 

C  interface  file:  Fi  1  es .  h 


GCInstrumentData 


Provides  data  for  the  GCPart  (IV-2263)  structure. 

struct  GCInstrumentData  { 

ToneDescri pti on  tone; 

long  knobCount; 

long  knob  [  1  ] ; 

}; 

tone 

A  ToneDescri  pti  on  (IV-2487)  structure. 
knobCount 

The  number  of  InstKnobRec  structures  in  the  list. 
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knob 

An  array  of  pointers  to  InstKnobRec  (IV-2293)  structures. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 


GCPart 


Defines  a  part  in  the  QuickTime  Music  Architecture. 

struct  GCPart  { 

1  ong 
short 
1  ong 
1  ong 
1  ong 

GCInstrumentData 

}; 

hwInstrumentNumber 

The  instrument  number  of  the  instrument  for  the  part, 
control  1 er 

An  array  of  128  bits  identifying  the  available  controllers;  see  "Music 
Controllers"  (IV-2682).  Bits  are  numbered  from  1  to  128,  starting  with  the  most 


hwInstrumentNumber ; 
control  1 er[128] ; 
vol ume ; 
polyphony; 
mi di Channel  ; 
i  d ; 


Inside  QuickTime:  Data  Structures 


IV-2263 


Data  Structures 


GDevice 


significant  bit  of  the  long  word  and  continuing  to  the  least  significant  of  the  last 
bit. 

vol ume 

The  sound  volume  for  this  part,  ranging  from  -1.0  to  +1.0.  The  high-order  8  bits 
contain  the  integer  part;  the  low-order  8  bits  contain  the  fractional  part.  A  value 
of  +1.0  constitutes  the  maximum  volume  of  the  user's  computer.  Negative 
values  are  silent  but  retain  the  magnitude  of  the  volume  setting. 

polyphony 

The  maximum  number  of  voices, 
mi di Channel 

The  system  MIDI  channel  or,  for  a  hardware  device,  the  slot  number, 
i  d 

A  GCInstrumentData  (IV-2263)  structure. 

Associated  Functions 

Musi  c Deri  vedSet Instrument  (11-976) 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 


GDevice 


Stores  state  information  for  video  devices  and  offscreen  graphics  worlds, 
struct  GDevice  { 


short 

gdRef Num ; 

short 

gdID ; 

short 

gdType ; 

ITabHandl e 

gdlTabl e ; 

short 

gdResPref ; 

SProcHndl 

gdSearchProc 

CProcHndl 

gdCompProc ; 

short 

gd FI  ags  ; 

Pi xMapHandl e 

gdPMap ; 

1  ong 

gdRefCon ; 

GDHandl e 

gdNextGD ; 

Rect 

gdRect ; 

1  ong 

gdMode ; 

short 

gdCCBytes  ; 

short 

gdCCDepth  ; 

Handl e 

gdCCXData  ; 

Handl  e 

gdCCXMask ; 
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gdRef Num 

The  reference  number  of  the  driver  for  the  screen  associated  with  the  video 
device.  For  most  video  devices,  this  information  is  set  at  system  startup  time. 

gdID 

Reserved.  If  you  create  your  own  GDevice  structure,  set  this  field  to  0. 
gdType 

A  constant  (see  below)  that  identifies  the  general  type  of  graphics  device. 
gdlTabl e 

A  handle  to  the  inverse  table  for  color  mapping. 
gdResPref 

The  preferred  resolution  for  inverse  tables. 
gdSearchProc 

A  handle  to  the  list  of  search  functions.  For  details,  see  the  chapter  "Color 
Manager"  in  Advanced  Color  Imaging  on  the  Mac  OS  (listed  in  the  bibliography). 
Its  value  is  N I L  for  the  default  function. 
gdCompProc 

A  handle  to  a  list  of  complement  functions;  see  CProcRec  (IV-2225). 
gd FI  ags 

Flag  bits  (see  below)  that  describe  the  GDevi  ce  structure's  attributes.  To  set  the 
attribute  bits  in  this  field,  use  SetDevi  ceAttri  bute,  declared  in  the  file 
Qui  ckdraw.  h;  do  not  set  these  flags  directly  in  the  GDevi  ce  structure. 

gdPMap 

A  handle  to  a  Pi  xMap  (IV-2332)  structure  giving  the  dimension  of  the  image 
buffer,  along  with  the  characteristics  of  the  graphics  device  (resolution,  storage 
format,  color  depth,  and  color  table). 
gdRefCon 

A  value  used  by  system  software  to  pass  device-related  parameters.  Since  a 
graphics  device  is  shared,  you  shouldn't  store  data  here. 
gdNextGD 

A  handle  to  the  next  graphics  device  in  the  device  list.  If  this  is  the  last  graphics 
device  in  the  device  list,  the  field  contains  0. 

gdRect 

The  boundary  rectangle  of  the  graphics  device  represented  by  the  GDevice 
structure.  The  main  screen  has  the  upper-left  corner  of  the  rectangle  set  to  (0,0). 
All  other  graphics  devices  are  relative  to  this  point. 


STR 


Inside  QuickTime:  Data  Structures 


IV-2265 


Data  Structures 


GDevice 


gdMode 

The  current  setting  for  the  graphics  device  mode.  This  value  is  passed  to  the 
video  driver  to  set  its  pixel  depth  and  to  specify  color  or  black  and  white; 
applications  don't  need  this  information. 
gdCCBytes 

The  rowBy  tes  value  of  the  expanded  cursor.  Your  application  should  not  change 
this  field. 

gdCCDepth 

The  depth  of  the  expanded  cursor.  Your  application  should  not  change  this 
field. 

gdCCXData 

A  handle  to  the  cursor's  expanded  data.  Your  application  should  not  change 
this  field. 

gdCCXMask 

A  handle  to  the  cursor's  expanded  mask.  Your  application  should  not  change 
this  field. 

gdReserved 

Reserved  for  future  expansion;  it  must  be  set  to  0  for  future  compatibility. 
gdExt 

QuickTime  3.0  private  data. 

gdType  Constants 

cl utType 

CLUT  device;  that  is,  one  whose  colors  are  mapped  with  a  color  lookup  table, 
f i xedType 

Fixed  colors;  that  is,  the  color  lookup  table  can't  be  changed, 
di rectType 

Direct  RGB  colors. 

gdFlags  Constants 

gdDevType 

If  this  bit  is  set  to  0,  the  graphics  device  is  black  and  white;  if  it  is  set  to  1,  the 
graphics  device  supports  color. 

burstDevi ce 

If  this  bit  is  set  to  1,  the  graphics  device  supports  block  transfers. 
ext32Devi ce 

If  this  bit  is  set  to  1,  the  graphics  device  must  be  used  in  32-bit  mode, 
ramlni t 

If  this  bit  is  set  to  1,  the  graphics  device  has  been  initialized  from  RAM. 
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mai nScreen 

If  this  bit  is  set  to  1,  the  graphics  device  is  the  main  screen, 
all  I  m' t 

If  this  bit  is  set  to  1,  all  graphics  devices  were  initialized  from  ■  scrn '  resources. 
screenDevi ce 

If  this  bit  is  set  to  1,  the  graphics  device  is  a  screen. 
noDri ver 

If  this  bit  is  set  to  1,  the  GDevi  ce  structure  has  no  driver. 
screenActi ve 

If  this  bit  is  set  to  1,  the  graphics  device  is  active. 

Discussion 

When  Mac  OS  starts  up,  it  allocates  and  initializes  one  handle  toaGDevice  structure 
for  each  video  device  it  finds.  When  you  create  a  new  offscreen  graphics  world. 
Color  QuickDraw  automatically  creates  a  GDevi  ce  structure  for  it.  The  system  links 
these  GDevi  ce  records  in  a  list,  called  the  device  list.  By  default,  the  GDevi  ce  structure 
corresponding  to  the  first  video  device  found  is  marked  as  the  current  device;  all 
other  graphics  devices  in  the  list  are  initially  marked  as  inactive. 

Special  Considerations 

Your  application  should  never  need  to  change  the  fields  of  a  GDevi  ce  structure 
directly. 

Programming  Info 

C  interface  file:  Quickdraw.h 
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GenericKnobDescription 

Describes  a  knob  for  the  generic  music  component. 


struct  GenericKnobDescription  { 


KnobDescri pti on 

kd ; 

1  ong 

hwl ; 

1  ong 

hw2 ; 

1  ong 

hw3 ; 

}; 

1  ong 

settingsID; 

kd 

hwl 

A  KnobDescri  pti  on  (IV-2299)  structure. 

Undocumented 

Inside  QuickTime:  Data  Structures 
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GenericKnobDescriptionList 


hw2 

Undocumented 

hw3 

Undocumented 
setti ngsID 

Undocumented 

Discussion 

Undocumented 

Associated  Functions 

Musi  cDeri  vedSetKnob  (11-976) 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c . h 


GenericKnobDescriptionList 


Provides  a  list  of  Generi  cKnobDescri  pti  on  (IV-2267)  structures. 

struct  GenericKnobDescriptionList  { 

long  knobCount; 

Generi cKnobDescri pti on  knob  Cl]; 

}; 

knobCount 

The  number  of  Generi  cKnobDescri  pti  on  structures. 

knob 

An  array  of  Generi  cKnobDescri  pti  on  structures. 

Associated  Functions 

Musi  cGeneri  cGetKnobLi  st  (11-984) 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 


GetMovieCompleteParams 


Defines  the  layout  of  the  complete  movie  parameter  structure  used  by 
Medi alni  ti al  i  ze  (11-877). 

struct  GetMovieCompleteParams  { 
short  version: 
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Movi  e 

theMovi e ; 

T  rack 

theTrack; 

Medi  a 

theMedi a ; 

TimeScale 

movi eScal e ; 

TimeScale 

medi aScal e ; 

TimeVal  lie 

movi eDurati on ; 

TimeVal  lie 

trackDurati on ; 

TimeVal  lie 

medi aDurati on ; 

Fi  xed 

ef fecti veRate ; 

TimeBase 

ti meBase ; 

short 

vol ume ; 

Fi  xed 

wi dth ; 

Fi  xed 

hei ght ; 

Matri xRecord 

trackMovi eMatri x 

CGraf Ptr 

movi ePort ; 

GDHandl e 

movi eGD ; 

Pi xMapHandl e 

trackMatte ; 

QTAtomContai ner 

i nputMap ; 

versi on 

Specifies  the  version  of  this  structure.  This  field  is  always  set  to  0. 
theMovi e 

Identifies  the  movie  that  contains  the  current  media's  track.  This  movie 
identifier  is  supplied  by  the  Movie  Toolbox.  Your  component  may  use  this 
identifier  to  obtain  information  about  the  movie  that  is  using  your  media. 
theT  rack 

Identifies  the  track  that  contains  the  current  media.  This  track  identifier  is 
supplied  by  the  Movie  Toolbox.  Your  component  may  use  this  identifier  to 
obtain  information  about  the  track  that  contains  your  media.  For  example,  you 
might  call  GetT rackNextlnteresti  ngT i  me  (1-537)  to  examine  the  track's  edit  list. 
theMedi a 

Identifies  the  current  media.  This  media  identifier  is  supplied  by  the  Movie 
Toolbox.  Your  derived  media  handler  can  use  this  identifier  to  read  samples  or 
sample  descriptions  from  the  current  media,  using  GetMedi  aSampl  e  (IM43)  and 
GetMedi  aSampl  eDescri  pti  on  (1-445). 

movi eScal e 

Specifies  the  time  scale  of  the  movie  that  contains  the  current  media's  track.  If 
the  Movie  Toolbox  changes  the  movie's  time  scale,  the  toolbox  calls  your 
derived  media  handler's  Medi  aSetMovi  eTi  meScal  e  (11-899)  function. 
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medi aScal e 

Specifies  the  time  scale  of  the  current  media.  If  the  Movie  Toolbox  changes  your 
media's  time  scale,  the  toolbox  calls  your  derived  media  handler's 
Medi  aSetMedi  aTimeScal  e  (11-898)  function, 
movi eDurati on 

Contains  the  movie's  duration.  This  value  is  expressed  in  the  movie's  time 
scale. 

trackDurati on 

Contains  the  track's  duration.  This  value  is  expressed  in  the  movie's  time  scale, 
medi aDurati on 

Contains  the  media's  duration.  This  value  is  expressed  in  the  media's  time 
scale. 

effecti veRate 

Contains  the  media's  effective  rate.  This  rate  ties  the  media's  time  scale  to  the 
passage  of  absolute  time,  and  does  not  necessarily  correspond  to  the  movie's 
rate.  This  value  takes  into  account  any  master  time  bases  that  may  be  serving 
the  media's  time  base.  The  value  of  this  field  indicates  the  number  of  time  units 
(in  the  media's  time  scale)  that  pass  each  second.  This  rate  is  represented  as  a 
32-bit,  fixed-point  number.  The  high-order  16  bits  contain  the  integer  portion, 
and  the  low-order  16  bits  contain  the  fractional  portion.  The  rate  is  negative 
when  time  is  moving  backward  for  the  media.  Whenever  the  Movie  Toolbox 
changes  your  media's  effective  rate,  it  calls  your  derived  media  handler's 
Medi  aSetRate  (11-903)  function. 

ti meBase 

Identifies  the  media's  time  base, 
vol urne 

Contains  the  media's  current  volume  setting.  This  value  is  represented  as  a 
16-bit,  fixed-point  number.  The  high-order  8  bits  contain  the  integer  portion; 
the  low-order  8  bits  contain  the  fractional  part.  Volume  values  range  from  -1.0 
to  1.0.  Negative  values  play  no  sound  but  preserve  the  absolute  value  of  the 
volume  setting.  If  QuickTime  changes  your  media's  volume,  it  calls  your 
derived  media  handler's  Medi  aGSetVol  urne  (11-871)  function, 
wi  dth 

Indicates  the  width,  in  pixels,  of  the  track  rectangle.  This  field,  along  with  the 
height  field,  specifies  a  rectangle  that  surrounds  the  image  that  is  displayed 
when  the  current  media  is  played.  This  value  corresponds  to  the  x  coordinate 
of  the  lower-right  corner  of  the  rectangle  and  is  expressed  as  a  fixed-point 
number.  If  the  Movie  Toolbox  modifies  this  rectangle,  the  toolbox  calls  your 
derived  media  handler's  Medi  aSetDi  mensi  ons  (11-891)  function.  Note  that  your 
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media  need  not  present  only  a  rectangular  image.  The  Movie  Toolbox  can  use 
a  clipping  region  to  cause  your  media's  image  to  be  displayed  in  a  region  of 
arbitrary  shape,  and  it  can  use  a  matte  to  control  the  image's  transparency.  The 
toolbox  calls  your  derived  media  handler's  Medi  aSetCl  i  p  (11-890)  function 
whenever  it  changes  your  media's  clipping  region.  The  trackMatte  field  in  this 
structure  specifies  a  matte  region. 

hei ght 

Indicates  the  height,  in  pixels,  of  the  track  rectangle.  This  value  corresponds  to 
the  y  coordinate  of  the  lower-right  corner  of  the  rectangle  and  is  expressed  as  a 
fixed-point  number. 

trackMovi eMatri x 

Specifies  the  matrix  that  transforms  your  media's  pixels  into  the  movie's 
coordinate  system.  The  Movie  Toolbox  obtains  this  matrix  by  concatenating  the 
track  matrix  and  the  movie  matrix.  You  should  use  this  matrix  whenever  you 
are  displaying  graphical  data  from  your  media.  Whenever  the  Movie  Toolbox 
modifies  this  matrix,  it  calls  your  derived  media  handler's  Medi  aSetMatri  x 
(11-897)  function, 
movi ePort 

Indicates  the  movie's  graphics  port.  Whenever  the  Movie  Toolbox  changes  the 
movie's  graphics  world,  it  calls  your  derived  media  handler's  Medi  aSetGWorl  d 
(11-893)  function. 

movi eGD 

Specifies  the  movie's  graphics  device.  Whenever  the  Movie  Toolbox  changes 
the  movie's  graphics  world,  it  calls  your  derived  media  handler's 
Medi  aSetGWorl  d  (11-893)  function. 

trackMatte 

Identifies  the  matte  region  assigned  to  the  track  that  uses  your  media.  This  field 
contains  a  handle  to  a  pixel  map  that  contains  a  blend  matte.  Your  component 
is  not  responsible  for  disposing  of  this  matte.  If  there  is  no  matte,  this  field  is  set 
to  N I L. 
i nputMap 

A  reference  to  the  media's  input  map.  The  media  input  map  should  not  be 
modified  or  disposed. 

Associated  Functions 

Medi  a  Ini  ti  al  i  ze  (11-877) 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 
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GMInstrumentlnfo 


See  Also 

See  Medi  a  Ini  ti  al  i  ze  (11-877). 


GMInstrumentlnfo 


Provides  information  about  a  General  MIDI  instrument  within  an  instrument 
component. 

struct  GMInstrumentlnfo  { 


1  ong 

cmpInstID 

1  ong 

gmlnstNum 

1  ong 

i nstMatch 

1: 

cmpInstID 

The  number  of  the  instrument  within  the  instrument  component. 
gmlnstNum 

The  General  MIDI,  or  standard,  instrument  number, 
i nstMatch 

A  flag  (see  below)  indicating  how  the  instrument  matches  the  requested 
instrument. 

instMatch  Constants 

klnstrumentExactMatch 

The  instrument  exactly  matches  the  request. 
klnstrumentRecommendedSubsti tute 

The  instrument  is  the  approved  substitute. 
klnstrumentQual i ty Fi el d 

The  high-order  8  bits  of  this  field  specify  the  quality  of  the  selected  instrument. 
Higher  values  specify  higher  quality. 

kRol and8Bi tQual i ty 

For  built-in  instruments,  the  value  of  the  high-order  8  bits  is  always 
klnstrumentRol and8Bi tQual i ty. 
klnstrumentRol and8BitQuality 

The  quality  of  an  8-bit  Roland  instrument. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c . h 
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GradientColorRecord 

Stores  color  gradient  information. 

struct  GradientColorRecord  { 
ARGBColor  thisColor; 

Fixed  endi ngPercentai 


STR 


thi sCol or 

Specifies  a  color  used  for  a  gradient, 
endi ngPercentage 

Specifies  the  percentage  of  the  gradient  (expressed  as  value  between  0  and  1, 
where  0  is  the  beginning  of  the  gradient)  at  which  the  specified  color  begins. 

Programming  Info 

C  interface  file:  ImageCodec.h 


GrafPort 


Defines  a  complete  drawing  environment  for  black-and-white  graphics  operations, 
struct  GrafPort  { 


short 

devi ce ; 

Bi tMap 

portBi ts  ; 

Rect 

portRect ; 

RgnHandl e 

v  i  s  Rg  n  ; 

RgnHandl e 

cl  i  pRgn ; 

Pattern 

bkPat ; 

Pattern 

f i 1 1  Pat ; 

Poi  nt 

pnLoc ; 

Poi  nt 

pnSi ze ; 

short 

pnMode ; 

Pattern 

pnPat ; 

short 

pnVi s  ; 

short 

txFont ; 

Styl eFi el d 

txFace ; 

short 

txMode ; 

short 

txSi ze ; 

Fi  xed 

spExtra  ; 

1  ong 

f gCol or ; 

1  ong 

bkCol  or ; 

short 

col rBi t ; 

short 

patStretch 

Handl e 

pi cSave ; 

Inside  QuickTime:  Data  Structures 
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GrafPort 


Handle  rgnSave; 

Handle  polySave; 

QDProcsPtr  grafProcs; 

}; 

devi ce 

See  CGrafPort  (IV-2168). 
portBi ts 

See  CGrafPort  (IV-2168).  In  a  GrafPort  structure,  this  field  contains  a  complete 
14-byte  Bi  tMap  (IV-2164)  structure.  In  a  CGrafPort  structure,  this  field  is  partly 
replaced  by  the  4-byte  portPi xMap  field,  which  contains  a  handle  to  a  Pi xMap 
structure.  In  what  would  be  the  rowBytes  field  of  the  Bi  tMap  structure,  a 
CGrafPort  structure  has  a  2-byte  portVersion  field  in  which  the  two  high  bits  are 
always  set  to  1 .  QuickTime  uses  these  bits  to  distinguish  CGrafPort  records  from 
GrafPort  records,  in  which  the  two  high  bits  of  the  rowBytes  field  are  always  0. 
Following  the  portBi  ts  field  in  the  CGrafPort  structure  are  the  portVersi  on  and 
grafVars  fields.  The  grafVars  field  contains  a  handle  to  a  GrafVars  structure; 
this  handle  is  not  included  in  the  GrafPort  structure.  For  information  about  the 
GrafVars  structure,  see  Inside  Macintosh:  Imaging  With  QirickDrazv  (listed  in  the 
bibliography). 
portRect 

See  CGrafPort  (IV-2168). 
vi  sRgn 

See  CGrafPort  (IV-2168). 
cl i pRgn 

See  CGrafPort  (IV-2168). 
bkPat 

In  a  GrafPort  structure,  the  bkPat,  pnPat,  and  f  i  1 1  Pat  fields  hold  8-byte  bit 
patterns.  In  a  CGrafPort  (IV-2168)  structure,  these  fields  are  partly  replaced  by 
three  4-byte  handles  to  pixel  patterns.  The  resulting  12  bytes  of  additional  space 
in  the  CGrafPort  structure  are  taken  up  by  the  rgbFgColor  and  rgbBkColor  fields, 
which  contain  6-byte  RGBCol  or  (IV-2403)  structures  specifying  the  optimal 
foreground  and  background  colors  for  the  color  graphics  port.  Note  that  the 
closest  matching  available  colors,  which  QuickTime  actually  uses  to  render  the 
foreground  and  background,  are  stored  in  the  f  gCol  or  and  bkCol  or  fields  of  the 
CGrafPort  structure, 
f i 1 1  Pat 

See  the  bkPat  field  (above). 
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pnLoc 

See  CGrafPort  (IV-2168). 
pnSi ze 

See  CGrafPort  (IV-2168). 
pnMode 

See  CGrafPort  (IV-2168). 
pnPat 

See  the  bkPat  field  (above). 
pnVi  s 

See  CGrafPort  (IV-2168). 
txFont 

See  CGrafPort  (IV-2168). 
txFace 

The  character  style  of  the  text,  with  values  from  the  set  defined  by  the  Style 

type,  which  includes  such  styles  as  bold,  italic,  and  shaded.  You  can  apply 

stylistic  variations  either  alone  or  in  combination.  This  field  is  initially  set  to 

plain  text. 
txMode 

See  CGrafPort  (IV-2168). 
txSi ze 

See  CGrafPort  (IV-2168). 
spExtra 

See  CGrafPort  (IV-2168). 
f gCol or 

See  CGrafPort  (IV-2168). 
bkCol  or 

See  CGrafPort  (IV-2168). 
col rBi t 

See  CGrafPort  (IV-2168). 
patStretch 

See  CGrafPort  (IV-2168). 
pi cSave 

See  CGrafPort  (IV-2168). 
rgnSave 

See  CGrafPort  (IV-2168). 
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gxPath 


polySave 

See  CGrafPort  (IV-2168). 
graf Procs 

See  CGrafPort  (IV-2 168).InaGrafPort  structure,  you  can  supply  this  field  with 
a  pointer  toaQDProcs  (IV-2342)  structure;  inaCGrafPort  structure,  you  provide 
this  field  with  a  pointer  toaCQDProcs  (IV-2226)  structure. 

Discussion 

See  CGrafPort  (IV-2168). 

Version  Notes 

The  Graf  Port  structure  has  been  largely  superseded  by  the  CGrafPort  (IV-2168) 
structure,  which  defines  a  full  color  environment.  The  two  structures  are  the  same 
size;  QuickTime  distinguishes  between  them  by  examining  the  portBi  ts  field. 

Programming  Info 

C  interface  file:  Quickdraw.h 

See  Also 

See  CGrafPort  (IV-2168). 


gxPath 


Encapsulates  a  path  contour  geometry. 

struct  gxPath  { 

long  vectors: 

long  control Bi ts [ 1 ] ; 

gxPoint  vector[l]; 

1: 

vectors 

The  number  of  geometric  points  in  the  contour, 
control Bi ts 

Bit  flags  that  indicate  which  geometric  points  are  on  curve  and  which  are 
off-curve  control  points, 
vector 

The  coordinates  of  the  geometric  points. 

Discussion 

A  path  contour  is  a  series  of  connected  points.  The  contour  can  contain  both  straight 
lines  and  curves.  Therefore,  the  geometric  points  that  make  up  a  path  contour  can 
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be  on-curve  points  or  off-curve  control  points.  The  path  shape  allows  you  to  group 
any  number  of  contours  within  a  single  QuickDraw  GX  shape. 

Programming  Info 

C  interface  file:  GXTypes .  h 


gxPaths 


Encapsulates  a  multiple-path  geometry. 

struct  gxPaths  { 

long  contours; 

gxPath  contour[l]; 

}; 

contours 

The  number  of  path  contours, 
contour 

The  path  contours;  see  gxPath  (IV-2276). 

Discussion 

The  contours  field  indicates  the  total  number  of  contours  (in  other  words,  the  total 
number  of  separate  paths),  and  the  contour  field  is  an  array  that  contains  the  path 
geometries.  Since  a  gxPaths  structure  is  of  variable  length  and  every  element  in  it  is 
of  type  long,  you  can  define  a  path  geometry  as  an  array  of  long  integer  values. 

Associated  Functions 

CurveCountPointsInPath  (1-153) 

Programming  Info 

C  interface  file:  GXTypes  .  h 

See  Also 

See  gxPath  (IV-2276). 
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gxPoint 


Defines  a  point  in  vector  graphics. 

struct  gxPoint  { 

Fixed  x; 

Fixed  y; 

}; 
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x 

A  horizontal  distance.  Greater  values  of  the  x  field  indicate  distances  further  to 
the  right. 

y 

A  vertical  distance.  Greater  values  of  the  y  field  indicate  distances  further 
down. 

Discussion 

The  location  of  the  origin  depends  on  the  context  where  you  use  the  point;  for 
example,  it  might  be  the  upper-left  comer  of  a  view  port.  Notice  that  the  x  and  y 
fields  are  of  type  Fixed.  QuickDraw  GX  allows  you  to  specify  fractional  coordinate 
positions. 

Associated  Functions 

CurveGetPathPoi nt  (1-157) 

Programming  Info 

C  interface  file:  GXTypes .  h 


ICMAlignmentProcRecord 


Specifies  an  image  compression  alignment  callback. 

struct  ICMAlignmentProcRecord  { 

ICMA1 i gnmentUPP  al i gnmentProc ; 

long  al i gnmentRefCon ; 

1: 

al i gnmentProc 

Contains  a  Universal  Procedure  Pointer  that  accesses  your  ICMA1  i  gnmentProc 
(III— 2086)  callback, 
al i gnmentRefCon 

Contains  a  reference  constant  for  use  by  your  callback. 

Discussion 

This  structure  defines  a  pointer  to  an  alignment  function.  You  assign  an  alignment 
function  by  passing  a  pointer  to  this  structure. 

Associated  Functions 

Al  i  gnScreenRect  (1-46) 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 
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ICMCompletionProcRecord 

Specifies  an  image  compression  completion  callback. 

struct  ICMCompletionProcRecord  { 

ICMCompl  eti  onLIPP  compl  eti  on P roc ; 

long  compl eti onRefCon ; 


STR 


compl eti onProc 

Contains  a  Universal  Procedure  Pointer  that  accesses  your  ICMCompl  eti  onProc 
(III— 2087)  callback, 
compl eti onRefCon 

Contains  a  reference  constant  for  use  by  your  callback. 

Discussion 

This  structure  governs  whether  you  perform  a  compression  asynchronously.  If  the 
compl  eti  onProc  field  in  this  structure  is  set  to  NIL,  perform  the  compression 
synchronously.  If  this  field  is  not  N I L,  it  specifies  an  application  completion 
function.  Perform  the  compression  asynchronously  and  call  that  completion 
function  when  your  component  is  finished.  If  the  compl  eti  onProc  field  in  this 
structure  has  a  value  of  -1,  perform  the  operation  asynchronously  but  do  not  call 
the  application's  completion  function 

Associated  Functions 

CompressSequenceFrame  (1-124) 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

See  Also 

See  CodecCompressParams  (IV-2184).  For  information  on  calling  completion 
functions,  see  the  chapter  "Image  Compression  Manager"  in  Inside  Macintosh: 
QuickTime  (listed  in  the  bibliography). 


ICMDataProcRecord 


Specifies  an  image  compression  data-loading  function. 

struct  ICMDataProcRecord  { 

ICMDataUPP  dataProc; 

long  dataRefCon; 


Inside  QuickTime:  Data  Structures 
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ICMFlushProcRecord 


dataProc 

Contains  a  pointer  to  your  data-loading  function. 
dataRefCon 

Contains  a  reference  constant  for  use  by  your  data-loading  function. 

Discussion 

If  there  is  no  data-loading  function,  the  Image  Compression  Manager  sets  the 
dataProc  field  to  NIL,  and  the  entire  image  must  be  in  memory  at  the  location 
specified  by  the  codecData  field  of  the  ImageSubCodecDecompressRecord  (IV-2289) 
structure. 

Associated  Functions 

FDecompressImage  (1-355) 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


ICMFlushProcRecord 


Specifies  an  image  compression  data-unloading  callback. 

struct  ICMFlushProcRecord  { 

ICMFlushUPP  flushProc; 

long  flushRefCon; 

1: 

f 1 ushProc 

Contains  a  pointer  to  your  data-unloading  function, 
f 1 ushRefCon 

Contains  a  reference  constant  for  use  by  your  data-unloading  function. 

Discussion 

If  there  is  not  enough  memory  to  store  a  compressed  image,  your  application  may 
provide  a  function  that  unloads  some  of  the  compressed  data.  This  field  contains  a 
structure  that  identifies  that  data-unloading  function.  If  the  application  did  not 
provide  a  data-unloading  function,  the  flushProc  field  in  this  structure  is  set  to  N I L. 
In  this  case,  your  component  writes  the  entire  compressed  image  into  the  memory 
location  specified  by  the  data  field 

Associated  Functions 

FCompressImage  (1-344) 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 
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See  Also 

See  CodecCompressParams  (IV-2184).  See  the  chapter  "Image  Compression  Manager" 
in  Inside  Macintosh:  QuickTime  (listed  in  the  bibliography)  for  more  information 
about  data-unloading  functions. 


ICMFrameT  imelnf  o 


Contains  timing  information  about  the  display  of  a  frame. 

struct  ICMFrameTimelnfo  { 
wide  startTime; 

long  scale; 

long  duration; 

}; 

startTime 

The  start  time  of  the  frame,  expressed  in  media  time  scale  units  from  the 
beginning  of  the  track. 

scale 

The  media  time  scale  in  units  per  second, 
durati on 

The  frame's  duration  in  media  time  scale  units. 


STR 


Programming  Info 

C  interface  file:  ImageCodec.h 


See  Also 

Seethe  CodecDecompressParams  (IV-2190)  structure. 


ICMFrameT  imeRecord 


Contains  a  frame's  time  information  for  scheduled  asynchronous  decompression 
operations. 

struct  ICMFrameTimeRecord  { 


wi  de 

value; 

1  ong 

scale; 

void  * 

base ; 

1  ong 

durati on ; 

Fi  xed 

rate ; 

1  ong 

recordSi ze ; 

1  ong 

f rameNumber ; 

1  ong 

fl ags ; 

Inside  QuickTime:  Data  Structures 
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ICMPixelFormatlnfo 


wide  vi rtualStartTime; 

long  vi rtual Durati on  ; 

}; 

val  ue 

Specifies  the  time  at  which  the  frame  is  to  be  displayed, 
seal  e 

Indicates  the  units  for  the  frame's  display  time. 

base 

Refers  to  the  time  base, 
durati on 

Specifies  the  duration  for  which  the  frame  is  to  be  displayed.  This  must  be  in 
the  same  units  as  specified  by  the  scale  field.  It  is  0  if  the  duration  is  unknown. 

rate 

Indicates  the  time  base's  effective  rate. 
recordSi ze 

Total  number  of  bytes  in  this  structure, 
f rameNumber 

Number  of  frame;  0  if  the  frame  number  is  not  known, 
fl  ags 

Flag  (see  below)  to  indicate  if  vi  rtual  StartTime  and  vi  rtual  Durati  on  are  valid, 
vi rtualStartTime 

Conceptual  start  time, 
vi  rtual Durati on 

Conceptual  duration. 

flags  Constants 

i cmFrameT imeHasVi rtual Star tTi meAndDurati  on 

Indicates  that  vi  rtual  StartT i  me  and  vi  rtual  Durati  on  are  valid. 

Programming  Info 

C  interface  file:  Movi  es .  h 

See  Also 

Seethe  CodecDecompressParams  (IV-2190)  structure. 


ICMPixelFormatlnfo 


Defines  a  pixel  format. 
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struct  ICMPixelFormatlnfo  { 
long  size; 

unsigned  long  formatFlags; 

short  bitsPerPixel [14] ; 

}; 

si  ze 

The  size  of  this  structure.  This  quantity  isn't  necessarily  equal  to 
si  zeof  ( I  CM  Pi  xel  Format  Info)  because  it  is  dependent  on  whether  the  pixel 
format  is  chunky  or  planar,  and,  if  planar,  the  number  of  components  (see 
below), 
f ormatFl ags 

A  constant  (see  below)  indicating  the  pixel  format. 
bitsPerPixel 

An  array  that  defines  the  number  of  bits  for  each  component.  The  element 
bitsPerPixel[0]  contains  the  number  of  bits  for  the  first  component, 
bitsPerPixel  [1]  the  number  of  bits  for  the  second  component,  etc.  The 
meaning  of  this  parameter  depends  on  the  format  flag  (see  below). 

formatFlags  Constants 

k I  CM Pi xel Format  Is  PI anarMask 

If  this  flag  is  1,  the  pixel  format  is  a  planar  mask  and  bi  ts  PerPi  xel  [  ]  represents 
the  bits  for  each  pixel  component.  If  this  flag  is  0,  the  pixel  format  is  chunky  (not 
planar)  and  bi  ts  PerPi  xel  [0]  represents  the  bits  per  pixel.  Chunky  pixel 
formats  pack  the  different  components  together.  For  example,  3  pixels  of  32-bit 
ARGB  is  represented  in  memory  as  ARGBARGBARGB.  Planar  formats  pack 
the  different  components  separately.  If  the  pixel  format  is  planar,  then 
(formatFlags  &  kICMPi  xel  FormatlsPl  anarMask)  is  equal  to  the  number  of 
components. 

kICMPixel Formatlslndexed 

If  the  pixel  format  is  indexed  (which,  by  definition,  means  that  there  are  no 
individual  components)  then  this  flag  is  1.  Generally,  color  modes  of  8  bit  per 
pixel  or  less  are  indexed. 

kICMPixel FormatlsSupportedByQD 

If  this  flag  is  l,you  can  call  QuickDraw  on  PixMap  (IV-2332)  structures  that  store 
this  kind  of  pixel  data.  With  Macintosh,  the  classic  QD  pixel  formats  will  have 
this  set,  but  not  any  of  the  YUV  pixel  formats.  With  Windows,  more  formats 
will  have  this  set,  because  the  Windows  implementation  of  QuickDraw  needs 
to  support  more  pixel  formats. 


STR 
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ICMProgressProcRecord 


Discussion 

You  can  represent  a  format  that  has  from  1  to  14  discrete  components  using  this  data 
structure.  For  ARGB,  there  are  4  components.  RGB  without  an  al  pha  channel  has  3 
components.  A  component  count  of  15  is  reserved  for  future  expansion. 

Associated  Functions 

ICMGetPi  xel  Format  Info  (11-673) 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


ICMProgressProcRecord 


Specifies  an  image  compression  progress  callback. 

struct  ICMProgressProcRecord  { 

ICMProgressUPP  progressProc ; 

long  progressRefCon ; 

}; 

progressProc 

Contains  a  pointer  to  your  progress  function. 

progressRefCon 

Contains  a  reference  constant  for  use  by  your  progress  function. 

Discussion 

During  a  compression  operation,  your  compressor  may  occasionally  call  a  function 
that  the  application  provides  in  order  to  report  your  progress.  This  field  contains  a 
structure  that  identifies  the  progress  function.  If  the  progressProc  field  in  this 
structure  is  set  to  N I L,  the  application  has  not  supplied  a  progress  function 

Associated  Functions 

DrawPi  ctureFi  1  e  (1-310) 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


See  Also 

See  CodecCompressParams  (IV-21 84) .  See  the  chapter  "Image  Compression  Manager" 
in  Inside  Macintosh:  QuickTime  (listed  in  the  bibliography)  for  more  information 
about  progress  functions. 
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ImageDescription 


Defines  the  characteristics  of  a  compressed  image  or  sequence, 
struct  ImageDescription  { 


1  ong 

i  dSi  ze ; 

CodecType 

cType ; 

1  ong 

resvdl ; 

short 

resvd2 ; 

short 

dataRef Index; 

short 

versi on ; 

short 

revi  si onLevel  ; 

1  ong 

vendor ; 

CodecQ 

temporal Qual i ty ; 

CodecQ 

spati al Qual i ty ; 

short 

wi dth ; 

short 

hei ght ; 

Fi  xed 

hRes  ; 

Fi  xed 

vRes  ; 

1  ong 

dataSi ze ; 

short 

f rameCount ; 

Str31 

name ; 

short 

depth ; 

short 

}; 

cl utID; 

i  d  S 1  ze 

Defines  the  total  size  of  this  image  description  structure  with  extra  data 
including  color  lookup  tables  and  other  per-sequence  data. 

cType 

Indicates  the  type  of  compressor  component  that  created  this  compressed 
image  data.  The  value  of  this  field  indicates  the  compression  algorithm 
supported  by  the  component.  The  Codec  data  type  defines  a  field  in  the 
compressor  name  list  structure  that  identifies  the  compression  method 
employed  by  a  given  compressor  component.  Apple  assigns  these  values  so 
that  they  remain  unique.  These  values  correspond,  in  turn,  to  text  strings  that 
can  identify  the  compression  method  to  the  user.  See  "Codec  Identifiers" 
(IV-2655)  for  a  list  of  values, 
resvdl 

Reserved;  set  to  0. 
resvd2 

Reserved;  set  to  0. 
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dataRef Index 

Reserved;  set  to  0. 
versi on 

Indicates  the  version  of  the  compressed  data.  The  contents  of  this  field  should 
indicate  the  version  of  the  compression  algorithm  that  was  used  to  create  the 
compressed  data.  By  examining  this  field,  decompressors  that  support  many 
versions  of  an  algorithm  can  determine  the  proper  way  to  decompress  the 
image. 

revi si onLevel 

Indicates  the  version  of  the  compressor  that  created  the  compressed  image. 
Developers  of  compressors  and  decompressors  assign  these  version  numbers, 
vendor 

Identifies  the  developer  of  the  compressor  that  created  the  compressed  image, 
temporal Qual i ty 

Indicates  the  degree  of  temporal  compression  performed  on  the  image  data 
associated  with  this  description.  This  field  is  valid  only  for  sequences.  See 
Compress  Image  (1-113)  for  a  list  of  values. 

spati al Qual i ty 

Indicates  the  degree  of  spatial  compression  performed  on  the  image  data 
associated  with  this  description.  This  field  is  valid  for  sequences  and  still 
images.  See  Compress  Image  (1-113)  for  a  list  of  values, 
wi  dth 

Contains  the  width  of  the  source  image,  in  pixels, 
hei ght 

Contains  the  height  of  the  source  image,  in  pixels. 

hRes 

Contains  the  horizontal  resolution  of  the  source  image,  in  dots  per  inch. 

vRes 

Contains  the  vertical  resolution  of  the  source  image,  in  dots  per  inch. 
dataSi ze 

Indicates  the  size  of  the  compressed  image,  in  bytes.  This  field  is  valid  only  for 
still  images.  Set  this  field  to  0  if  the  size  is  unknown. 

f rameCount 

Contains  the  number  of  frames  in  the  image  data  associated  with  this 
description. 
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name 

Indicates  the  compression  algorithm  used  to  create  the  compressed  data.  This 
algorithm  is  stored  in  Pascal  string  format.  It  always  takes  up  32  bytes  no  matter 
how  long  the  string  is.  The  32  bytes  consist  of  31  bytes  plus  one  length  byte.  The 
value  of  this  field  should  correspond  to  the  compressor  type  specified  by  the 
cType  field,  as  well  as  to  the  value  of  the  typeName  field  in  the  appropriate 
compressor  name  structure  returned  byGetCodecNameList  (1-386) .  Applications 
may  use  the  contents  of  this  field  to  indicate  the  type  of  compression  used  for 
the  associated  image, 
depth 

Contains  the  pixel  depth  specified  for  the  compressed  image.  Values  of  1,  2, 4, 
8, 16,  24,  and  32  indicate  the  depth  of  color  images.  Values  of  34, 36,  and  40 
indicate  2-bit,  4-bit,  and  8-bit  grayscale,  respectively,  for  grayscale  images. 

cl utID 

Contains  the  ID  of  the  color  table  for  the  compressed  image,  or  other  special 
values.  If  this  field  is  set  to  0,  then  a  custom  color  table  is  defined  for  the 
compressed  image.  You  can  use  the  Get  ImageDescri  pti  onCTabl  e  (1-417) 
function  to  retrieve  the  color  table.  If  this  field  is  set  to  -1,  the  image  does  not 
use  a  color  table. 

Discussion 

Data  in  the  ImageDescri  pti  on  structure  indicates  the  type  of  compression  that  was 
used,  the  size  of  the  image  when  displayed,  the  resolution  at  which  the  image  was 
captured,  and  so  on.  In  addition,  an  image  description  structure  may  contain 
additional  data  in  extensions  and  custom  color  tables.  One  image  description 
structure  may  be  associated  with  one  or  more  compressed  frames. 

Associated  Functions 

Compress  Image  (1-113) 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

See  Also 

For  functions  that  let  you  work  with  custom  color  tables  in  ImageDescription 
structures,  see  GetlmageDescri  pti  onCTabl  e  (1-417)  and  SetlmageDescri  pti  onCTabl  e 
(III— 1593).  For  functions  that  let  you  work  with  ImageDescri  pti  on  structure 
extensions,  see  GetlmageDescri  pti  onExtensi  on  (1-418), 

AddlmageDescri  pti  onExtension  (1-25),  RemovelmageDescri  pti  onExtensi  on  (III-1457), 
CountlmageDescri  pti  onExtensi  onType  (1-143),  and 
GetNextlmageDescri  pti  onExtensi  onType  (1-501).  For  extensions  to  the 
ImageDescri pti on  structure,  see  NCLCCol orlnfoImageDescri pti onExtensi  on 
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ImageRangeRecord 


(IV-2321),  Pi xel  AspectRati  olmageDescri  pti  onExtensi  on  (IV-2332),  and 
Clean AperturelmageDescripti  onExtensi  on  (IV-2174). 


ImageRangeRecord 


Undocumented 

struct  ImageRangeRecord  { 
long  imageFlags; 

OSType  fileType; 

long  repl acedAtoms ; 

}; 

i mageFl ags 

Undocumented 
f i 1 eType 

File  type  to  contain  the  preset  group  (normally  kStandardPresetGroup). 
repl acedAtoms 

Number  of  atoms  at  this  level  replaced  by  this  preset  group. 

Discussion 

Undocumented 

Programming  Info 

C  interface  file:  ImageCodec.  h 


ImageSubCodecDecompressCapabilities 


Returned  by  an  image  decompressor  component  in  response  to 
ImageCodecIni  ti  al  i  ze  (11-724). 

struct  ImageSubCodecDecompressCapabi 1 i ti es  { 
long  recordSize; 

long  decompressRecordSi ze ; 

Boolean  canAsync; 

UInt8  padO; 

recordSi ze 

The  size  of  this  structure  in  bytes. 
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decompress  Record Si  ze 

The  size  of  the  ImageSubCodecDecompressRecord  (IV-2289)  structure  that  your 
image  decompressor  component  requires.  This  structure  is  used  to  pass 
information  from  ImageCodecBegi  nBand  (11-690)  to  ImageCodecDrawBand  (11-697) 
and  ImageCodecEndBand  (11-704). 
canAsync 

Specifies  whether  your  image  decompressor  component  can  perform 
asynchronous  scheduled  decompression.  This  should  be  TRUE  unless  your 
image  decompressor  component  calls  functions  that  cannot  be  called  during 
interrupt  time. 

padO 

Unused. 

Discussion 

The  first  function  call  that  your  image  decompressor  component  receives  from  the 
base  image  decompressor  is  always  a  call  to  ImageCodecInitialize  (11-724).  In 
response  to  this  call,  your  image  decompressor  component  returns  an 
ImageSubCodecDecompressCapabi  1  i  ti  es  structure  that  specifies  its  capabilities. 

Associated  Functions 

ImageCodecIni  ti  al  i  ze  (11-724) 

Programming  Info 

C  interface  file:  ImageCodec.h 

See  Also 

See  ImageCodecInitial  ize  (11-724),  ImageCodecBegi  nBand  (11-690), 
ImageCodecDrawBand  (11-697),  and  ImageCodecEndBand  (11-704). 


ImageSubCodecDecompressRecord 


Contains  information  needed  for  decompressing  a  frame. 


struct  ImageSubCodecDecompressRecord  { 


Ptr 
1  ong 
Ptr 

ICMProgressProc Record 
ICMDataProcRecord 
void  * 

UInt8 
UInt8 
1  ong 


baseAddr ; 

rowBytes ; 

codecData ; 

prog  res s P roc Record ; 

dataProcRecord ; 

user Decompress  Record ; 

f rameType ; 

pad[3] ; 

pri  v  [ 2 ]  ; 
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baseAddr 

The  address  of  the  destination  pixel  map,  which  includes  adjustment  for  the 
offset.  Note  that  if  the  bit  depth  of  the  pixel  map  is  less  than  8,  your  image 
decompressor  component  must  adjust  for  the  bit  offset. 
rowBytes 

The  offset  in  bytes  from  one  row  of  the  destination  pixel  map  to  the  next.  The 
value  of  the  rowBytes  field  must  be  less  than  0x4000. 

codecData 

A  pointer  to  the  data  to  be  decompressed. 
progressProc Record 

An  ICMProgressProcRecord  (IV-2284)  structure  that  specifies  a  progress 
function.  This  function  reports  on  the  progress  of  a  decompression  operation. 
If  there  is  no  progress  function,  the  Image  Compression  Manager  sets  the 
progressProc  field  in  the  ICMProgressProcRecord  structure  to  NIL. 
dataProcRecord 

An  ICMDataProcRecord  (IV-2279)  structure  that  specifies  a  data-loading 
function.  If  the  data  to  be  decompressed  is  not  all  in  memory,  your  component 
can  call  this  function  to  load  more  data.  If  there  is  no  data-loading  function,  the 
Image  Compression  Manager  sets  the  dataProc  field  in  the  ICMDataProcRecord 
structure  to  NIL,  and  the  entire  image  must  be  in  memory  at  the  location 
specified  by  the  codecData  field  of  the  ImageSubCodecDecompressRecord 
structure. 

user Decompress  Record 

A  pointer  to  storage  for  the  decompression  operation.  The  storage  is  allocated 
by  the  base  image  decompressor  after  it  calls  ImageCodecInitialize  (11-724). 
The  size  of  the  storage  is  determined  by  the  decompressRecordSi  ze  field  of  the 
ImageSubCodecDecompressCapabi  1  i  ti  es  structure  that  is  returned  by 
ImageCodecInitialize.  Your  image  decompressor  component  should  use  this 
storage  to  store  any  additional  information  needed  about  the  frame  in  order  to 
decompress  it. 
f rameType 

A  constant  (see  below)  that  indicates  the  frame  type. 

pad 

Unused. 

pri  v 

Private  to  QuickTime;  do  not  use. 
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frameType  Constants 

kCodecFrameTypelln  known 

The  frame  type  is  unknown. 
kCodec FrameType Key 

This  is  a  key  frame. 
kCodecFrameTypeDi fference 
This  is  a  difference  frame. 
kCodecFrameTypeDroppabl  eDi fference 
This  is  a  droppable  difference  frame. 

Associated  Functions 

ImageCodecBegi  nBand  (11-690) 

Programming  Info 

C  interface  file:  ImageCodec.h 
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InstCompInfo 


Contains  a  list  of  all  atomic  instruments  supported  by  an  instrument  component. 


struct  InstCompInfo  { 

1  ong 
Str31 

QTAtomContai ner 
1  ong 

GMInstrumentlnfoHandl e 
1  ong 

GMInstrumentlnfoHandl e 
1  ong 

nonGM Instrument  Inf oHandl 

}; 


i  nf  oSi  ze ; 

Instrument Li  bra ry Name; 
Instrument Li brarylTxt ; 
GMi nstrumentCount ; 

GMi nstrumentlnfo; 
GMdrumCount ; 
GMdrumlnfo; 
non GMi nstrumentCount ; 
e  nonGMinstrumentlnfo; 


i  nf  oSi  ze 

The  size  of  this  structure  in  bytes. 

Instrument Li  bra ry Name 

The  readable  name  of  this  instrument  library,  up  to  31  bytes. 
Instrument Li brarylTxt 

International  text  name  atoms  for  instruments. 

GMi nstrumentCount 

The  number  of  General  MIDI  instruments. 
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GMi nstrumentlnfo 

A  handle  to  a  list  of  General  MIDI  instrument  information  structures. 
GMdrumCount 

The  number  of  General  MIDI  drum  kits. 

GMdrumlnfo 

A  handle  to  a  list  of  General  MIDI  instrument  information  structures, 
non GMi nstrumentCount 

The  number  of  non-General  MIDI  instruments, 
non GMi nstrumentlnfo 

A  handle  to  the  list  of  non-General  MIDI  instruments. 

Associated  Functions 

InstrumentGetlnfo  (11-766) 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 


InstKnobList 

Contains  a  list  of  InstKnobRec  (IV-2293)  structures. 

struct  InstKnobList  { 

Bi gEndi anLong  knobCount; 

Bi  gEndi  anLong  knobFlags; 

InstKnobRec  knob [ 1 ] ; 

}; 

knobCount 

The  number  of  InstKnobRec  structures  in  the  list. 
knobFl  ags 

Constants  (see  below)  that  tell  what  to  do  if  a  requested  knob  is  not  in  the  list. 

knob 

An  array  of  InstKnobRec  (IV-2293)  structures. 

knobFlags  Constants 

klnstKnobMissi  nglln  known 

If  the  requested  knob  is  not  in  the  list,  do  not  set  its  value. 
klnstKnobMissing Default 

If  the  requested  knob  is  not  in  the  list,  use  its  default  value. 
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Programming  Info 

C  interface  file:  QuickTimeMusic.h 


InstKnobRec 


Contains  information  about  an  instrument  knob. 

struct  InstKnobRec  { 

Bi gEndi anLong  number; 

Bi gEndi anLong  value; 

}; 

number 

A  knob  ID  or  index.  A  nonzero  value  in  the  high  byte  indicates  that  it  is  an  ID. 
The  knob  index  ranges  from  1  to  the  number  of  knobs;  the  ID  is  an  arbitrary 
number. 

val  ue 

The  value  the  knob  is  set  to. 
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Programming  Info 

C  interface  file:  QuickTimeMusIc.h 


InstLibDescRec 


Contains  the  name  of  an  instrument  library. 

struct  InstLibDescRec  { 

Str31  liblDName; 

}; 

1  i  blDName 

The  library's  readable  name. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 


InstrumentAboutlnfo 


Contains  the  information  that  appears  in  an  instrument's  About  box  and  is  returned 
by  Musi  cGetlnstrumentAboutlnfo  (11-990). 
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InstrumentlnfoList 


struct 
Pi 
Str255 
Str255 
Str255 

}; 


p; 

author ; 
copy ri ght ; 
other ; 


InstrumentAboutlnfo  { 
cHandl  e 


P 

A  handle  to  a  graphic  for  the  About  box. 
author 

The  author's  name, 
copy ri ght 

The  copyright  information, 
other 

Any  other  textual  information. 

Associated  Functions 

Musi cGetlnstrumentAboutlnfo  (11-990) 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c . h 


See  Also 

See  Musi  cGetlnstrumentAboutlnfo  (11-990). 


InstrumentlnfoList 


Contains  the  list  of  instruments  available  on  a  synthesizer. 

struct  InstrumentlnfoList  { 

1  ong 
Handl e 

QTAtomContai ner 
InstrumentlnfoRecord 

}; 

recordCount 

The  number  of  InstrumentlnfoRecord  (IV-2295)  structures  in  the  list. 
toneNames 

A  string  list  of  the  instrument  names  as  specified  in  their  tone  descriptions, 
i txtNames 

A  list  of  international  text  names,  taken  from  the  name  atoms. 


recordCount ; 
toneNames ; 
i txtNames ; 
i  n  f  o  [  1  ] ; 


IV-2294 


Inside  QuickTime:  Data  Structures 


InstrumentlnfoRecord 


i  nf  o 

An  array  of  InstrumentlnfoRecord  (IV-2295)  structures. 

Associated  Functions 

Musi  cGetlnstrumentlnfo  (11-991) 

Programming  Info 

C  interface  file:  QuickTimeMusIc.h 

See  Also 

See  InstrumentlnfoRecord  (IV-2295). 
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InstrumentlnfoRecord 


Provides  information  about  non-General  MIDI  instruments  within  an  instrument 
component. 

struct  InstrumentlnfoRecord  { 
long  i nstrumentNumber ; 

long  flags; 

long  toneNamelndex; 

long  itxtNameAtomID; 

}; 

i nstrumentNumber 

The  number  of  the  instrument  within  the  instrument  component.  If  the  ID  is  0, 
the  name  is  a  category  name. 

fl  ags 

Unused.  Set  to  0. 
toneNamelndex 

The  instrument's  position  in  the  toneNames  index  stored  in  the  instrument 
information  list  this  structure  is  a  part  of.  The  index  is  a  1 -based  index, 
i txtNameAtomID 

The  instrument's  position  in  the  i  txtNames  index  stored  in  the  instrument 
information  list  this  structure  is  a  part  of. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 
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InstSampleDescRec 


Contains  a  description  of  an  audio  sample,  including  sample  rate,  loop  points,  and 
lowest  and  highest  key  to  play  on. 

struct  InstSampleDescRec  { 


Bi gEndi anOSType 

dataFormat ; 

Bi gEndi anShort 

numChannel s ; 

Bi gEndi anShort 

sampl eSi ze ; 

Bi gEndi anUnsignedFixed 

sampl eRate ; 

Bi gEndi anShort 

sampleDatalD; 

Bi gEndi anLong 

offset ; 

Bi gEndi anLong 

numSampl es ; 

Bi gEndi anLong 

1 oopType ; 

Bi gEndi anLong 

1 oopStart ; 

Bi gEndi anLong 

1 oopEnd ; 

Bi gEndi anLong 

pi tchNormal ; 

Bi gEndi anLong 

pitchLow; 

Bi gEndi anLong 

pi tchHi gh  ; 

}; 

dataFormat 

The  data  format  type  (see  below). 
numChannel s 

The  number  of  channels  of  data  present  in  the  sample, 
sampl eSi ze 

The  size  of  the  sample;  8-bit  or  16-bit. 
sampl eRate 

The  rate  at  which  to  play  the  sample  in  unsigned  fixed-point  16.16. 
sampl eDatalD 

The  ID  number  of  a  sample  data  atom  that  contains  the  sample  audio  data, 
offset 

Reserved.  Set  to  0. 
numSampl es 

The  number  of  data  samples  in  the  sound. 

1 oopType 

A  constant  (see  below)  indicating  the  type  of  loop. 

1 oopStart 

Indicates  the  beginning  of  the  portion  of  the  sample  that  is  looped  if  the  sound 
is  sustained.  The  position  is  given  in  the  number  of  data  samples  from  the  start 
of  the  sound. 
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1 oopEnd 

Indicates  the  end  of  the  portion  of  the  sample  that  is  looped  if  the  sound  is 
sustained.  The  position  is  given  in  the  number  of  data  samples  from  the  start  of 
the  sound, 
pi tchNormal 

The  number  of  the  MIDI  note  produced  if  the  sample  is  played  at  the  rate 
specified  in  sampl  eRate. 

pi  tchLow 

The  lowest  pitch  at  which  to  play  the  sample.  Use  for  instruments,  such  as 
pianos,  that  have  different  samples  to  use  for  different  pitch  ranges, 
pi tchHi gh 

The  highest  pitch  at  which  to  play  the  sample.  Use  for  instruments,  such  as 
pianos,  that  have  different  samples  to  use  for  different  pitch  ranges. 

dataFormat  Constants 

'  twos ' 

Signed  data. 

'  raw  ' 

Unsigned  data. 

loopType  Constants 

kMusi cLoopTypeNormal 
Use  a  regular  loop. 
kMusi cLoopTypePal i ndrome 

Use  a  back-and-forth  loop. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 
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ITab 


Contains  a  Color  QuickDraw  inverse  table. 

struct  ITab  { 

long  iTabSeed; 

short  iTabRes; 

Byte  iTTabl e[l] ; 


iTabSeed 

A  copy  of  the  ctSeed  field  from  the  source  Col  orTabl  e  (IV-2210)  structure. 
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iTabRes 

Channel  resolution  of  the  inverse  table:  3, 4,  or  5  bits. 
iTTabl e 

Byte-length  Col  orTabl  e  (IV-2210)  index  values. 

Programming  Info 

C  interface  file:  Quickdraw.h 

See  Also 

See  Col  orTabl  e  (IV-2210).  For  information  about  inverse  tables,  see  Chapter  7  of 
Advanced  Color  Imaging  on  the  Mac  OS  (listed  in  the  bibliography). 


KaraokeAtom 


Associates  highlighted  runs  of  text  with  movie  times. 

struct  KaraokeAtom  { 

long  numEntries; 

KaraokeRec  karaokeEntri es[l] ; 

1: 

numEntri es 

The  number  of  entries  in  karaokeEntri  es. 
karaokeEntri es 

An  array  of  KaraokeRec  (IV-2298)  data  structures. 

Programming  Info 

C  interface  file:  Movies  Format,  h 


KaraokeRec 


Associates  highlighted  text  with  a  movie  time  value. 

struct  KaraokeRec  { 

TimeVal ue  timeVal  ; 

short  beginHilite; 

short  endHilite; 

1: 


timeVal 

The  time  location  of  the  highlighted  text. 
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begi nHi 1 i te 

Character  number  of  highlighted  text  start  character. 
endHi 1 i te 

Character  number  of  highlighted  text  end  character. 

Programming  Info 

C  interface  file:  Movi  es Format .  h 

See  Also 

See  KaraokeAtom  (IV-2298). 
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KnobDescription 


Contains  sound  parameter  values  for  a  single  knob, 
struct  KnobDescription  { 


Str63 

name ; 

1  ong 

1 owVal ue ; 

1  ong 

hi ghVal ue ; 

1  ong 

def aul tVal ue ; 

1  ong 

f  1  ags  ; 

1  ong 

knobID; 

}; 

name 

The  name  of  the  knob. 

1 owVal ue 

The  lowest  number  you  can  set  the  knob  to. 
hi ghVal ue 

The  highest  number  you  can  set  the  knob  to. 
def aul tVal ue 

A  value  to  use  for  the  default.  A  default  instrument  is  made  of  all  default 
values, 
fl  ags 

Constants  (see  below)  that  provide  various  items  of  information  about  the 
knob. 

knobID 

A  knob  ID  or  index.  A  nonzero  value  in  the  high  byte  indicates  that  it  is  an  ID. 
The  knob  index  ranges  from  1  to  the  number  of  knobs;  the  ID  is  an  arbitrary 
number.  Use  the  knob  ID  to  refer  to  the  knob  in  preference  to  the  knob  index, 
which  may  change. 
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KnobDescription 


flags  Constants 

kKnobReadOnly 

The  knob  value  cannot  be  changed  by  the  user  or  with  a  set  knob  call. 
kKnoblnterruptllnsafe 

Alter  this  knob  only  from  foreground  task  time. 
kKnobKey rangeOverri  de 

The  knob  can  be  overridden  within  a  single  key  range  (software  synthesizer 
only). 

kKnobGroupStart 

The  knob  is  first  in  some  logical  group  of  knobs. 
kKnobFi xedPoi nt8 

Interpret  knob  numbers  as  fixed-point  8-bit. 
kKnobFi xedPoi ntl6 

Interpret  knob  numbers  as  fixed-point  16-bit. 
kKnobTypeNumber 

The  knob  value  is  a  numerical  value. 
kKnobTypeGroupName 

The  name  of  the  knob  is  really  a  group  name  for  display  purposes. 
kKnobTypeBool  ean 

The  knob  is  an  on/ off  knob.  If  the  range  of  the  knob  (as  specified  by  the  low 
value  and  high  value  in  the  knob  description  structure)  is  greater  than  one,  the 
knob  is  a  multi-checkbox  field. 
kKnobTypeNote 

The  knob  value  range  is  equivalent  to  MIDI  keys. 
kKnobTypePan 

The  knob  value  is  the  pan  setting  and  is  within  a  range  (as  specified  by  the  low 
value  and  high  value  in  the  knob  description  structure)  that  goes  from  left  to 
right. 

kKnobType Instrument 

The  knob  value  is  a  reference  to  another  instrument  number. 
kKnobTypeSetti  ng 

The  knob  value  is  one  of  several  different  discrete  settings;  for  example,  items 
on  a  pop-up  menu. 

kKnobTypeMilliseconds 

The  knob  value  is  in  milliseconds. 
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kKnobType Percentage 

The  knob  value  is  a  percentage  of  the  range. 
kKnobTypeHertz 

The  knob  value  represents  frequency. 
kKnobTypeButton 

The  knob  is  a  momentary  trigger  push  button. 

Associated  Functions 

Musi  cGetDrumKnobDescri  pti  on  (11-988) 

Programming  Info 

C  interface  file:  QuickTimeMusIc.h 
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LeftOverBlock 


Holds  the  contents  of  the  1  eftOverSampl  es  field  of  a  CmpSoundHeader  (IV-2176) 
structure. 

struct  LeftOverBlock  { 

unsigned  long  count; 

SInt8  sampl eArea [32] ; 

}; 

count 

The  number  of  bytes  in  the  sampl  eArea  field, 
sampl eArea 

An  array  of  bytes.  This  field  contains  samples  that  are  truncated  across 
invocations  of  the  compression  algorithm.  The  size  of  each  block  is  defined  by 
a  constant  (see  below). 

sampleArea  Constant 

1 eftOverBl ockSi  ze 
Value  is  32. 


Programming  Info 

C  interface  file:  Sound .  h 


LevelMeterlnfo 

Contains  sound  level  meter  readings, 
struct  LevelMeterlnfo  { 
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short  numChannels; 

UInt8  leftMeter; 

UInt8  rightMeter; 

}; 

numChannel s 

Contains  1  for  mono  or  2  for  stereo  source. 
1 eftMeter 

Left  meter  level,  0-255  range, 
ri ghtMeter 

Right  meter  level,  0-255  range. 

Associated  Functions 

Medi  aGetSoundLevel  Meterlnfo  (11-863) 

Programming  Info 

C  interface  file:  Sound .  h 


LongRangeRecord 


Undocumented 

struct  LongRangeRecord  { 
long  minValue; 

long  maxValue; 

long  scaleValue; 

long  preci si onDi gi ts  ; 

1: 

mi nVal ue 

Undocumented 
maxVal ue 

Undocumented 
seal eVal ue 

Undocumented 
preci si onDi gi ts 
Undocumented 


Discussion 

Undocumented 

Programming  Info 

C  interface  file:  ImageCodec.h 
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MacPolygon 


Defines  a  polygon  shape. 

struct  MacPolygon  { 
short  polySize; 

Rect  polyBBox; 

Point  polyPoints[l] ; 

}; 

polySi  ze 

The  size  in  bytes  of  this  structure. 
polyBBox 

The  rectangle  that  bounds  the  polygon. 
polyPoi  nts 

An  array  of  points,  beginning  with  the  starting  point  and  followed  by  each 
successive  point  to  which  a  line  is  drawn. 

Version  Notes 

MacPolygon  supersedes  the  Polygon  structure  to  avoid  name  conflicts  in  Windows. 

Programming  Info 

C  interface  file:  Quickdraw.h 
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MacRegion 

Defines  a  two-dimensional  region  in  Macintosh  graphics. 

struct  MacRegion  { 
unsigned  short 
Rect 

}; 

rgnSi ze 

The  size  in  bytes  of  this  structure.  If  the  region  is  rectangular  or  empty,  rgnSi  ze 
is  10. 
rgnBBox 

The  region's  bounding  rectangle. 

Discussion 

This  structure  can  be  followed  by  additional  data  (in  a  private  format)  if  the  region 
is  not  rectangular. 


rgnSi ze ; 
rgnBBox; 
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Version  Notes 

MacRegi  on  supersedes  the  Region  structure  to  avoid  name  conflicts  with  Windows. 

Programming  Info 

C  interface  file:  Quickdraw.h 


MatrixRecord 


Contains  a  transformation  matrix. 

struct  MatrixRecord  { 

Fixed  matrix[3] [3] ; 

}; 

matri x 

A  3-by-3  array  of  matrix  values. 

Associated  Functions 

GetMovi  eMatri  x  (1-478) 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


MediaEQSpectrumBandsRecord 


Provides  data  for  Medi  aGetSoundEqual  i  zerBands  (11-862)  and 
Medi  aSetSoundEqual  i  zerBands  (11-906). 

struct  MediaEQSpectrumBandsRecord  { 
short  count; 

Unsi gnedFi xedPtr  frequency; 

}; 

count 

Number  of  frequencies  in  this  structure, 
frequency 

Pointer  to  array  of  frequencies. 

Associated  Functions 

Medi  aGetSoundEqual  i  zerBands  (11-862) 

Programming  Info 

C  interface  file:  Medi  aHandl  ers .  h 
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MediaHeader 


Specifies  the  characteristics  of  a  media, 
struct  MediaHeader  { 


1  ong 

fl ags  ; 

1  ong 

creati onTime; 

1  ong 

modi  f  i  cati  onTi me 

TimeVal ue 

ti meScal e ; 

TlmeVal ue 

durati on ; 

short 

1 anguage ; 

short 

quality; 

}; 

fl  ags 

One  byte  of  version  information  followed  by  three  bytes  of  flags.  The  flags 
bytes  are  not  currently  used. 

creati onTime 

Number  of  seconds  since  midnight,  January  1, 1904  to  the  time  when  the  '  mdi  a ' 
(IV— 2560)  atom  was  created, 
modi fi cati onTime 

Number  of  seconds  since  midnight,  January  1, 1904  to  the  time  when  the  '  mdi  a ' 
(IV— 2560)  atom  was  last  changed, 
ti meScal e 

The  number  of  media  time  units  that  pass  during  each  real-time  second, 
durati on 

The  duration  of  the  media  in  media  time  units. 

1 anguage 

The  language  code  for  this  media;  see  "Localization  Codes"  (IV— 2673). 
quality 

Constants  (see  below)  that  describe  the  environment  in  which  this  media  can  be 
most  suitably  played. 

quality  Constants 

0x00000001 

Specifies  a  pixel  depth  of  1  bit  per  pixel. 

0x00000010 

Specifies  a  pixel  depth  of  2  bits  per  pixel. 

0x00000100 

Specifies  a  pixel  depth  of  4  bits  per  pixel. 
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0x00001000 

Specifies  a  pixel  depth  of  8  bits  per  pixel. 

0x00010000 

Specifies  a  pixel  depth  of  16  bits  per  pixel. 

0x00100000 

Specifies  a  pixel  depth  of  32  bits  per  pixel, 
medi aQual i tyDraft 

Specifies  the  lowest  quality  level.  Bits  6  and  7  =  00. 
medi aQual i tyNormal 

Specifies  an  acceptable  quality  level.  Bits  6  and  7  =  01. 
medi aQual i tyBetter 

Specifies  a  higher  quality  level.  Bits  6  and  7  =  10. 
medi aQual i tyBest 

Specifies  the  highest  quality  level.  Bits  6  and  7=11. 

Programming  Info 

C  interface  file:  MoviesFormat.h 

See  Also 

For  the  atom  structure  that  contains  the  Medi  aHeader  data  structure,  see  'mdhd ' 
(IV-2559). 

MediaPacketizerlnfo 


Provides  information  about  a  media  packetizer. 


struct  MediaPacketizerlnfo  { 
OSType 
OSType 
OSType 
UInt32 
UInt8 
UInt8 
1  ong 

RTPPayloadCharacteristic 


medi aType ; 
dataFormat ; 
vendor ; 

capabi 1 i ty FI ags  ; 
canPackMatri xType ; 
pad[3] ; 

characteri sticCount; 
character!' sti c[l]  ; 


medi aType 

Media  type  supported;  see  "Data  References"  (IV-2661).  0  means  all  media 
types. 
dataFormat 

Data  format  supported;  see  "Codec  Identifiers"  (IV-2655).  0  means  all  formats. 
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vendor 

Manufacturer  of  this  packetizer;  e.g.,  '  appl  '  for  Apple, 
capabi  1  i  tyFl  ags 

Constants  (see  below)  that  indicate  the  packetizer's  ability  to  handle 
non-standard  track  characteristics. 

canPackMatrixType 

Constant  (see  below);  the  packetizer  can  pack  any  matrix  type  up  to  this  level. 
Set  to  i  denti  tyMatri xType  for  identity  matrix  (no  translation)  only, 
pad 

Unused. 

character! sti cCount 

The  number  of  RTPPayl  oadCharacteri  sti  c  structures  in  the  characteri  sti  c 
field. 

characteri sti c 

An  array  of  RTPPayl  oadCharacteri  sti  c  (IV-2409)  structures. 

capabilityFlags  Constants 

kMedi aPacketi ze rCa n Pack Ed  i  t Rate 

The  packetizer  can  pack  the  edit  rate  value. 
kMedi aPacketi zerCanPackLayer 

The  packetizer  can  pack  the  layer  number. 
kMedi aPacketi zerCanPackVol  ume 

The  packetizer  can  pack  the  sound  volume  value. 
kMedi aPacketi zerCanPackBal  a  nee 

The  packetizer  can  pack  the  sound  balance  value. 
kMedi aPacketi zerCanPackGraphi  csMode 

The  packetizer  can  pack  the  graphics  transfer  mode  value. 
kMedi aPacketi zerCanPackEmptyEdi t 

The  packetizer  can  pack  the  empty  edit  value. 

canPackMatrixType  Constants 

i denti tyMatri xType 

Matrix  is  identity;  value  is  0x00. 
transl ateMatri xType 

Matrix  translates;  value  is  0x01. 
seal eMatri xType 

Matrix  scales;  value  is  0x02. 
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seal eTranslateMatri xType 

Matrix  translates  and  scales;  value  is  0x03. 

1 i nearMatri xType 

Matrix  is  general  2x2  type;  value  is  0x04. 
linearTranslateMatri xType 

Matrix  is  general  2x2  type  and  translates;  value  is  0x05 
perspectiveMatri xType 

Matrix  is  general  3x3  type;  value  is  0x06. 

Discussion 

The  last  characteristic  is  followed  by  the  payload  name,  defined  by  the 
RTPPayl  oadlnfo  (IV-2409)  structure. 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 


MediaPacketizerRequirements 


Stores  the  functional  requirements  for  a  media  packetizer. 
struct  MediaPacketizerRequirements  { 


OSType 

medi aType ; 

OSType 

dataFormat ; 

UInt32 

capabi 1 i ty FI ags  ; 

UInt8 

canPackMatri xType 

UInt8 

}; 

pad[3] ; 

medi aType 

Media  type  required;  see  "Data  References"  (IV-2661).  0  means  all  media  types. 
dataFormat 

Data  format  required;  see  "Codec  Identifiers"  (IV-2655).  0  means  all  formats, 
capabi 1 i ty FI ags 

Constants  (see  below)  that  indicate  the  packetizer's  ability  to  handle 
non-standard  track  characteristics. 
canPackMatri xType 

Constant  (see  below);  the  packetizer  needs  to  pack  any  matrix  type  up  to  this 
level.  Set  to  i  denti  tyMatri xType  for  identity  matrix  (no  translation)  only. 

pad 

Unused. 


IV-2308 


Inside  QuickTime:  Data  Structures 


MediaPacketizerRequirements 


capabilityFlags  Constants 

kMedi aPacketi ze rCa n Pack Ed i t Rate 

The  packetizer  can  pack  the  edit  rate  value. 
kMedi aPacketi zerCanPackLayer 

The  packetizer  can  pack  the  layer  number. 
kMedi aPacketi zerCanPackVol  ume 

The  packetizer  can  pack  the  sound  volume  value. 
kMedi aPacketi zerCanPackBal  a  nee 

The  packetizer  can  pack  the  sound  balance  value. 
kMedi aPacketi zerCanPackGraphi  csMode 

The  packetizer  can  pack  the  graphics  transfer  mode  value. 
kMedi aPacketi zerCanPackEmptyEdi t 

The  packetizer  can  pack  the  empty  edit  value. 

canPackMatrixType  Constants 

i denti tyMatri xType 

Matrix  is  identity;  value  is  0x00. 
transl at eMatri xType 

Matrix  translates;  value  is  0x01. 
seal eMatri xType 

Matrix  scales;  value  is  0x02. 
scaleTransl ateMatri xType 

Matrix  translates  and  scales;  value  is  0x03. 

1 i nearMatri xType 

Matrix  is  general  2x2  type;  value  is  0x04. 

1 i nearTransl ateMatri xType 

Matrix  is  general  2x2  type  and  translates;  value  is  0x05 
perspecti veMatri xType 

Matrix  is  general  3x3  type;  value  is  0x06. 

Associated  Functions 

QTSFi  ndMedi  aPacketi  zer  (11-1231) 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 
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MediaRecord 


Undocumented 

struct  MediaRecord  { 
long  da ta [ 1  ] ; 

}; 

data 

Undocumented 


Programming  Info 

C  interface  file:  Movi  es .  h 


Menulnfo 


Contains  information  about  a  Mac  OS  menu, 
struct  Menulnfo  { 


short 

menuID ; 

short 

menuWi dth ; 

short 

menuHei ght ; 

Hand! e 

menuProc ; 

1  ong 

enabl eFl ags ; 

Str255 

menuData ; 

1: 

menuID 

A  unique  number  that  identifies  the  menu. 
menuWi dth 

The  menu's  horizontal  dimension  in  pixels. 
menuHei ght 

The  menu's  vertical  dimension  in  pixels. 
menuProc 

A  handle  to  a  menu  definition  function.  The  Mac  OS  uses  this  function  to  draw 
the  menu, 
enabl  e FI  ags 

Bits  that  represent  the  enabled  status  of  the  menu  title  and  the  first  31  items  in 
the  menu.  A  bit  value  of  1  means  that  item  is  enabled.  Items  after  31  are  always 
enabled. 
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menuData 

The  title  of  the  menu. 


Discussion 

Application  software  should  never  directly  change  the  fields  of  this  structure. 

Programming  Info 

C  interface  file:  Menus .  h 


STR 


Modif  ierT  rackGraphicsModeRecord 

Contains  information  that  defines  the  graphics  mode  setting  for  a  track. 

struct  Modi f i erTrackGraphi csModeRecord  { 
long  graphi csMode ; 

RGBColor  opColor; 

}; 

graphi csMode 

Specifies  the  graphics  mode  setting  (see  below). 
opCol or 

Contains  an  RGB  color  structure  indicating  the  opcolor  to  use  with  the  graphics 
mode. 

graphicsMode  Constants 

full  Screen Hi deCursor 

If  this  flag  is  set,  BeginFull  Screen  hides  the  cursor.  This  is  useful  if  you  are  going 
to  play  a  QuickTime  movie  and  do  not  want  the  cursor  to  be  visible  over  the 
movie. 

f ul 1 ScreenAl 1 owEvents 

If  this  flag  is  set,  your  application  intends  to  allow  other  applications  to  run  (by 
calling  Wai  tNextEvent  to  grant  them  processing  time).  In  this  case, 

BeginFull  Screen  does  not  change  the  monitor  resolution,  because  other 
applications  might  depend  on  the  current  resolution. 

full ScreenDontChangeMenuBar 

If  this  flag  is  set,  BeginFullScreen  does  not  hide  the  menu  bar.  This  is  useful  if 
you  want  to  change  the  resolution  of  the  monitor  but  still  need  to  allow  the  user 
to  access  the  menu  bar. 
f ul 1 ScreenPref 1 i ghtSi ze 

If  this  flag  is  set,  BeginFullScreen  doesn't  change  any  monitor  settings,  but 
returns  the  actual  height  and  width  that  it  would  use  if  this  bit  were  not  set.  This 
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allows  applications  to  test  for  the  availability  of  a  monitor  setting  without 
having  to  switch  to  it. 

Discussion 

Data  in  this  structure  indicates  the  graphics  mode  setting  and  the  RGB  opcolor  that 
are  used  with  certain  graphics  modes.  Data  sent  to  the 

kT rackModi  f  i  erTypeGraphi  csMode  track  modifier  input  type  should  be  in  this 
structure. 

Programming  Info 

C  interface  file:  Movi  es .  h 


ModRef 


Provides  data  for  a  SndLi  stResource  (IV-2447)  structure. 

struct  ModRef  { 

unsigned  short  modNumber; 
long  modlnit; 

1: 

modNumber 

Undocumented 
modlni t 

Undocumented 


Programming  Info 

C  interface  file:  Sound .  h 


MotionJPEGApplMarker 


Undocumented 

struct  MotionJPEGApplMarker  { 
long  unused: 

long  tag; 

long  fieldSize; 

long  paddedFi el dSi ze ; 

long  offsetToNextFi el d  ; 

long  qTabl eOffset ; 

long  huffmanTabl eOffset ; 

long  sofOffset; 

long  sosOffset; 

long  soiOffset; 
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}; 

unused 

Undocumented 

tag 

Undocumented 


STR 


fi  el dSi ze 

Undocumented 
paddedFi el dSi ze 
Undocumented 
offsetToNextFi el d 
Undocumented 
qTabl eOffset 

Undocumented 
huffmanTabl eOffset 
Undocumented 
sofOf f set 

Undocumented 
sosOf f set 

Undocumented 
soi Offset 

Undocumented 

Programming  Info 

C  interface  file:  ImageCodec.h 


MovieEditStateRecord 


Undocumented 

struct  MovieEditStateRecord  { 
long  data [ 1 ] ; 

}; 

data 

Undocumented 


Programming  Info 

C  interface  file:  Movi  es  .  h 
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MovieExportGetDataParams 


Parameter  block  used  by  Movi  eExportGetDataProc  (III— 2101). 


struct  MovieExportGetDataParams 
1  ong 
1  ong 

TimeScale 
TimeVal ue 
TimeVal ue 
Ptr 
1  ong 

SampleDescriptionHandle 
OSType 
1  ong 
1  ong 
1  ong 

TimeVal ue 
1  ong 


{ 

recordSi ze ; 
trackID; 

sourceT i meScal e ; 
requestedTime; 
actual T i me ; 
dataPtr ; 
dataSi ze ; 
desc ; 
descType ; 
descSeed ; 

requestedSampleCount; 
actual Sampl eCount ; 
durati onPerSampl e ; 
sampl e  FI ags ; 


}; 


recordSi ze 

Contains  the  total  size  in  bytes  of  the  MovieExportGetDataParams  structure.  This 
is  provided  to  allow  for  additional  parameters  to  be  added  safely  in  the  future. 
trackID 

Specifies  the  data  source.  The  trackID  is  returned  when  the  data  source  is 
added  by  calling  Movi  eExportAddDataSource  (11-919). 
sourceT i meScal e 

Specifies  the  time  scale  for  this  data  source.  This  value  is  the  same  time  scale 
that  is  passed  to  Movi  eExportAddDataSource  (11-919). 

requestedT i me 

Specifies  the  time  of  the  media  requested  by  the  exporter.  The  time  scale  is  the 
same  one  specified  when  adding  a  data  source  with  Movi  eExportAddDataSource 
(11-919). 

actual T i me 

Specifies  the  time  actually  referred  to  by  the  returned  media  data.  This  value  is 
provided  by  Movi  eExportGetDataProc  (III— 2101),  and  is  usually  the  same  as 
requestedTime. 
dataPtr 

Contains  a  32-bit  pointer  to  the  media  data. 
dataSi ze 

Specifies  the  size  mbytes  of  the  data  pointed  to  by  dataPtr. 
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desc 

Contains  a  Sampl  eDescri  pti  onHandl  e  describing  the  format  of  the  data  pointed 
to  by  dataPtr.  For  video  data,  this  is  an  ImageDescri  pti  onHandl  e.  For  sound 
data,  this  is  a  SoundDescri  pti  onHandl  e. 
descType 

Specifies  the  type  of  Sampl  eDescri  pti  onHandl  e;  see  "Component  Types" 
(IV-2621).  For  example,  if  Sampl  eDescri  pti  onHandl  e  is  ImageDescri  pti  onHandl  e, 
descType  is  set  to  Vi  deoMedi  aType. 

descSeed 

Specifies  which  Sampl  eDescri  pti  onHandl  e  represented  by  the  current  value  of 
desc.  Some  data  sources  contain  different  kinds  of  data  at  different  times.  For 
example,  a  video  data  source  may  contain  both  JPEG  and  uncompressed  raw 
data.  Whenever  the  data  source  switches  from  one  type  of  data  to  another, 
change  descSeed  to  notify  the  exporter.  In  the  case  of  an  export  operation  that  is 
providing  its  source  data  from  a  QuickTime  movie  track,  descSeed  is  equal  to 
the  sample  description  index  of  the  sample  being  returned, 
requested Sampl eCount 

Specifies  the  number  of  samples  the  exporter  can  work  with.  The  function  can 
return  more  or  fewer  samples  than  requested.  For  video,  this  value  is  always  1. 
actual Sampl eCount 

Specifies  the  number  of  samples  actually  returned.  Your 
Movi  eExportGetDataProc  (III— 2101)  function  must  fill  in  this  field. 

durati onPerSampl e 

Specifies  the  duration  of  every  sample  returned.  For  sound  data, 
durati  onPerSampl  e  always  contains  1.  For  video  data,  durati  onPerSampl  e 
contains  the  duration  of  the  returned  sample,  expressed  in  the  time  scale 
defined  when  the  data  source  was  created, 
sampl  eFl  ags 

Contains  flags  (see  below)  for  the  returned  samples.  The  only  defined  flag  is 
medi  aSampl  eNotSync.  Your  Movi  eExportGetDataProc  (III— 2101)  function  must  fill 
in  this  field. 

sampleFlags  Constants 

medi aSampl eNotSync 

Returned  for  frame-differenced  video  sample  data. 

Discussion 

Your  Movi  eExportGetDataProc  (III— 2101)  function  is  passed  to 

Movi  eExportAddDataSource  to  define  a  new  data  source  for  an  export  operation.  The 
function  is  used  by  the  exporting  application  to  request  source  media  data  to  be 


STR 
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MovieHeader 


used  in  the  export  operation.  For  example,  in  a  video  export  operation,  frames  of 
video  data  (either  compressed  or  uncompressed)  are  provided.  In  a  sound  export 
operation,  buffers  of  audio  (either  compressed  or  uncompressed)  are  provided. 

The  data  pointed  tobydataPtr  must  remain  valid  until  the  next  call  to  your 
Movi  eExportGetDataProc  function.  Your  Movi eExportGetDataProc  function  is 
responsible  for  allocating  and  disposing  of  the  memory  associated  with  this  data 
pointer. 

Associated  Functions 

Movi  eExportGetDataProc  (III — 2101) 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


MovieHeader 


Specifies  the  top-level  characteristics  of  a  movie, 
struct  MovieHeader  { 


1  ong 

fl ags ; 

1  ong 

creati onT i me  ; 

1  ong 

modi f i cati onT i me ; 

T i meVal 

1  ue 

ti meScal e ; 

T i meVal 

1  ue 

durati on ; 

Fi  xed 

preferredRate ; 

short 

preferredVol ume ; 

short 

reservedl ; 

1  ong 

preferredLongl ; 

1  ong 

preferredLong2 ; 

Matri xRecord 

matri x ; 

T i meVal 

ue 

previ ewT i me ; 

T i meVal 

ue 

previ ewDurati on ; 

T i meVal 

ue 

posterT i me ; 

T i meVal 

ue 

sel ecti onT i me ; 

T i meVal 

ue 

sel ecti onDurati on 

T i meVal 

ue 

currentT i me ; 

1  ong 

nextT  rackID ; 

fl  ags 

One  byte  of  version  information  followed  by  three  bytes  of  flags.  The  flags 
bytes  are  not  currently  used. 


IV-2316 
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creati onT i me 

Number  of  seconds  since  midnight,  January  1, 1904  to  the  time  when  the  '  moov ' 
(IV-2566)  atom  was  created, 
modi f i cati onT i me 

Number  of  seconds  since  midnight,  January  1, 1904  to  the  time  when  the  '  moov ' 
(IV-2566)  atom  was  last  changed. 

ti meScal e 

The  number  of  movie  time  units  that  pass  during  each  real-time  second, 
durati on 

The  duration  of  the  movie  in  movie  time  units, 
pref erredRate 

The  rate  at  which  to  play  this  movie,  ranging  from  -1.0  to  +1.0.  A  value  of  +1.0 
indicates  normal  forward  play.  Negative  values  indicate  that  the  movie  will 
play  backwards. 

preferredVol ume 

The  sound  volume  at  which  to  play  this  movie,  ranging  from  -1.0  to  +1.0.  The 
high-order  8  bits  contain  the  integer  part;  the  low-order  8  bits  contain  the 
fractional  part.  A  value  of  +1.0  constitutes  the  maximum  volume  of  the  user's 
computer.  Negative  values  are  silent  but  retain  the  magnitude  of  the  volume 
setting, 
reservedl 

Reserved;  set  to  0. 
preferredLongl 

Reserved;  set  to  0. 
preferredl_ong2 

Reserved;  set  to  0. 
matri x 

A  Matrix  Re  cord  (IV-2304)  structure  that  contains  the  graphic  transformation 
matrix  for  this  movie, 
previ ewT i me 

The  time  value  in  movie  time  units  at  which  the  preview  begins, 
previ ewDurati on 

The  duration  of  the  movie  preview  in  movie  time  scale  units. 
posterTime 

The  time  value  in  movie  time  units  at  which  the  poster  is  located. 
selectionTime 

The  time  value  in  movie  time  units  at  which  the  current  selection  begins. 
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sel ecti onDurati on 

The  duration  of  the  current  selection  in  movie  time  scale  units. 
currentTime 

The  current  time  value  in  movie  time  units. 
nextT  rackID 

The  next  value  to  use  for  a  track  ID  number  in  this  movie. 


Programming  Info 

C  interface  file:  MoviesFormat.h 


See  Also 

For  the  atom  structure  that  normally  contains  the  MovieHeader  structure,  see  '  mvhd ' 

(IV-2567). 


MovieMediaT  imeRecord 


Undocumented 

struct  MovieMediaTimeRecord  { 
wide  time; 

T imeScal e  seal e  ; 

}; 

time 

The  media  time, 
seal  e 

The  time  scale. 


Programming  Info 

C  interface  file:  Movi  es .  h 


MovieRecord 

Undocumented 

struct  MovieRecord  { 
long  da  ta [ 1 ] ; 

}; 

data 

Undocumented 


IV-2318 
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Programming  Info 

C  interface  file:  Movi  es  .  h 


MoviesUserData 


Stores  user  data  in  movie  and  track  directories. 

struct  MoviesUserData  { 
long  size; 

long  udType; 

char  data [ 1 ] ; 


STR 


si  ze 

Size  in  bytes  of  the  user  data. 
udType 

Type  of  the  user  data. 

data 

User  data. 


Programming  Info 

C  interface  file:  Movi  es  Format .  h 


See  Also 

For  the  atom  type  that  contains  Movi  esUserData  structures,  see  '  udta  '  (IV-2607). 


MusicDescription 


Undocumented 

iption  { 

descSi ze ; 
data  Format ; 
resvdl ; 
resvd2 ; 
dataRef Index; 
musi cFl ags ; 
headerData[l] ; 

descSi ze 

Undocumented 


struct  MusicDescr 
1  ong 
1  ong 
1  ong 
short 
short 
1  ong 

unsigned  long 

}; 
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dataFormat 

Contains  'musi 
resvdl 

Reserved. 

resvd2 

Reserved. 
dataRef Index 

Undocumented 
musi  cFl  ags 

Undocumented 

headerData 

Undocumented 

Programming  Info 

C  interface  file:  Movi  es .  h 


MusicMIDIPacket 


Describes  MIDI  data  passed  by  note  allocation  calls. 

struct  MusicMIDIPacket  { 

unsigned  short  length; 

unsigned  long  reserved; 

UInt8  data[249] ; 

}; 


1 ength 

The  length  of  the  data  in  the  packet, 
reserved 

Contains  0,  or  one  of  the  music  packet  status  constants  (see  below). 

data 

MIDI  data. 

reserved  Constants 

kMusicPacketPortLost 

The  application  has  lost  the  default  input  port. 
kMusicPacketPortFound 

The  application  has  retrieved  the  input  port  from  the  previous  owner. 


IV-2320 
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kMusi cPacketTimeGap 

The  last  byte  of  the  packet  specifies  how  long  (in  milliseconds)  to  keep  the  MIDI 
line  silent  after  sending  the  packet. 

Associated  Functions 

Musi cDeri vedMIDISend  (11-975) 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 
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NCLCColorlnfoImageDescriptionExtension 


Video  color  i  nfo  extension  to  the  ImageDescri  pti  on  (IV-2285)  structure. 

struct  NCLCCol orlnfoImageDescripti onExtensi  on  { 

OSType  col orParamType; 

UIntl6  pri mari es ; 

UIntl6  transferFuncti on ; 

UIntl6  matrix; 

}; 

col orParamType 

Value  is  '  ncl  c ' . 
primaries 

CIE  1931  XY  chromaticity  coordinates. 
transferFuncti on 

Nonlinear  transfer  function  from  RGB  to  ErEgEb. 
matri x 

Matrix  from  ErEgEb  to  EyEcbEcr. 

Programming  Info 

C  interface  file:  ImageCodec.h 


See  Also 

See  ImageDescri  pti  on  (IV-2285). 


nonGMInstrumentlnfo 


Elolds  an  array  of  nonGMInstrumentlnfoRecord  (IV-2322)  structures. 

struct  nonGMInstrumentlnfo  { 

long  recordCount; 
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nonG  Mlnstrumentlnf  oRecord 


Handl e 

QTAtomContai ner 
nonGMInstrumentlnfoRecord 

}; 

recordCount 

Number  of  records  in  instlnfo. 
toneNames 

Name  from  tone  description, 
i txtNames 

International  text  name  atoms  for  instruments, 
instlnfo 

An  array  of  nonGMInstrumentlnfoRecord  (IV-2322)  structures. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 


toneNames ; 
i txtNames ; 

1  n  s  1 1  n  f  o  [  1  ] ; 


nonGMInstrumentlnfoRecord 


Provides  information  about  a  non-General  MIDI  instrument  within  a  QTMA 
instrument  component. 

struct  nonGMInstrumentlnfoRecord  { 
long  cmpInstID; 

long  flags; 

long  toneNamelndex ; 

long  itxtNameAtomID; 

}; 

cmpInstID 

The  number  of  the  instrument  within  the  instrument  component.  If  this  is  0,  the 
name  is  a  category  name, 
fl  ags 

Not  used. 
toneNamelndex 

The  instrument's  position  in  the  toneNames  index  stored  in  the 
InstrumentlnfoList  (IV-2294)  structure  this  structure  is  a  part  of.  The  index  is 
a  one-based  index. 


IV-2322 
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i txtNameAtomID 

The  instrument's  position  in  the  i  txtNames  index  stored  in  the 
InstrumentlnfoLi  st  (IV-2294)  structure  this  structure  is  a  part  of. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 
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See  nonGMInstrumentlnfo  (IV-2321),  InstrumentlnfoLi  st  (IV-2294). 


NoteRequest 


Provides  complete  information  for  allocating  a  note  channel. 

struct  NoteRequest  { 

NoteRequestlnfo  info; 

ToneDescri pti on  tone; 

}; 

i  nf  o 

A  NoteRequestlnfo  (IV-2323)  structure. 

tone 

A  ToneDescri  pti  on  (IV-2487)  structure. 

Associated  Functions 

NAGetNoteRequest  (11-1027) 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 


NoteRequestlnfo 


Contains  information  for  allocating  a  note  channel  in  addition  to  that  included  in  a 
ToneDescripti  on  (IV-2487)  structure. 


struct  NoteRequestI 
UInt8 
UInt8 

Bi gEndi anShort 
Bi gEndi anFi xed 


fo  { 
fl ags ; 
reserved ; 
polyphony; 
typi cal  Polyphony; 


n 
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fl  ags 

Constants  (see  below)  that  specify  what  to  do  if  the  exact  instrument  requested 
in  a  ToneDescri  pti  on  (IV-2487)  structure  is  not  found, 
reserved 

Reserved.  Set  to  0. 
polyphony 

Maximum  number  of  voices, 
typi cal  Polyphony 

Hint  for  level  mixing. 

flags  Constants 

kNoteRequestNoGM 

Don't  use  a  General  MIDI  synthesizer. 
kNoteRequestNoSynthType 

Don't  use  another  synthesizer  of  the  same  type  but  with  a  different  name. 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 


Num  Version 


Contains  software  version  and  release  information  in  little-endian  numeric  format. 

struct  NumVersion  { 

UInt8  nonRelRev; 

UInt8  stage; 

UInt8  mi norAndBugRev ; 

UInt8  majorRev; 

}; 

nonRel Rev 

The  revision  level  of  a  prerelease  version, 
stage 

The  development  stage.  A  constant  (see  below)  that  specifies  pre-alpha,  alpha, 
beta,  or  final  release, 
mi norAndBugRev 

The  minor  revision  level.  This  field  is  a  signed  byte  in  binary-coded  decimal 
format. 


IV-2324 
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ma jorRev 

The  major  revision  level.  This  field  is  a  signed  byte  in  binary-coded  decimal 
format. 

stage  Constants 

devel opStage 

Prealpha  release;  value  is  20. 
al phaStage 

Alpha  release;  value  is  40. 
betaStage 

Beta  release;  value  is  60. 
f i nal Stage 

Final  release;  value  is  80. 

Discussion 

Version  information  is  stored  in  NumVersi  on  in  packed  BCD.  This  NumVersi  on 
structure  is  the  same  as  the  first  four  fields  of  a  Mac  OS  resource  of  type  'vers',  but 
is  accessible  in  little-endian  format.  For  big-endian  format,  reverse  the  order  of  the 
fields.  For  example,  version  4 . 2 .  Ia3  would  be  stored  as  0x04214003. 

Programming  Info 

C  interface  file:  MacTypes .  h 
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OfflineSampleType 


Undocumented 

struct  OfflineSampleType  { 

unsigned  long  numChannels; 

UnsignedFixed  sampleRate; 

unsigned  short  sampleSize; 

}; 

numChannel s 

The  number  of  channels;  mono  =  1,  stereo  =  2. 
sampl eRate 

The  sample  rate  in  Apple  Fixed-point  representation, 
sampl eSi ze 

The  number  of  bits  in  each  sample. 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 
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OpenCPicParams 


Specifies  resolutions  when  creating  images, 
struct  OpenCPicParams  { 


Rect 

srcRect ; 

Fi  xed 

hRes ; 

Fi  xed 

vRes ; 

short 

versi on ; 

short 

reservedl ; 

1  ong 

reserved2 ; 

}; 

srcRect 

The  optimal  bounding  rectangle  for  the  resolution  indicated  by  the  hRes  and 
vRes  fields.  To  display  a  picture  at  a  resolution  other  than  that  specified  in  the 
the  hRes  and  vRes  fields,  your  application  should  compute  an  appropriate 
destination  rectangle  by  scaling  the  image's  width  and  height  by  the 
destination  resolution  divided  by  the  source  resolution. 

hRes 

The  best  horizontal  resolution  for  the  picture.  A  value  of  0x0048000  specifies  a 
horizontal  resolution  of  72  dpi. 

vRes 

The  best  vertical  resolution  for  the  picture.  A  value  of  0x0048000  specifies  a 
vertical  resolution  of  72  dpi. 
versi on 

Always  set  this  field  to  -2. 
reservedl 

Reserved;  set  to  0. 
reserved2 

Reserved;  set  to  0. 

Associated  Functions 

GetPi  ctureFi  1  eHeader  (1-504) 

Programming  Info 

C  interface  file:  Quickdraw.h 


ParameterAlternateDataEntry 


Provides  entries  for  the  ParameterAl  ternateDataType  (IV-2327)  structure. 


IV-2326 
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struct  ParameterAl ternateDataEntry  { 

OSType  dataType; 

QTAtomType  al ternateAtom; 

}; 

dataType 

The  data  type  in  which  this  item  is  stored, 
al ternateAtom 

The  atom  type  in  which  to  store  it. 

Programming  Info 

C  interface  file:  ImageCodec.h 
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See  Also 

See  ParameterAlternateDataType  (IV-2327). 


ParameterAlternateDataType 

Undocumented 

struct  ParameterAlternateDataType  { 

long  numEntries; 

ParameterAl ternateDataEntry  entries[l] ; 

}; 

numEntri es 

The  number  of  entries  in  the  entries  field, 
entri es 

An  array  of  ParameterAl  ternateDataEntry  (IV-2326)  structures. 

Programming  Info 

C  interface  file:  ImageCodec.h 


Parameter  AtomT  ype  AndID 


Undocumented 


struct  ParameterAtomTypeAndID 


QTAtomType 
QTAtomID 
1  ong 
Str255 


atomType ; 
atomID; 
atomFl ags ; 
atomName ; 


{ 
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atomType 

Type  of  the  atom  this  data  comes  from  or  goes  into. 
atomID 

ID  of  the  atom  this  data  comes  from  or  goes  into. 
atomFl ags 

Constants  (see  below)  that  define  options  for  this  atom,  or  0  for  no  options. 
atomName 

Name  of  this  value  type. 

atomFlags  Constants 

'none ' 

Atom  type  for  no  data  gotten  or  set. 

0x00000001 

The  atom  can  never  be  interpolated. 

0x00000002 

The  atom  can  be  interpolated,  but  it  is  an  advanced  user  operation. 
0x00000004 

More  than  one  value  of  the  atom  can  exist,  with  ascending  IDs  (for  example, 
lists  of  colors). 

Programming  Info 

C  interface  file:  ImageCodec.  h 


ParameterDataBehavior 


Undocumented 

struct  ParameterDataBehavior  { 

OSType  behavi orType ; 
long  behavi orFl ags ; 

union  u; 

1: 

behavi orType 

The  type  of  the  behavior;  see  "Parameter  Behaviors"  (IV-2685). 
behavi orFl ags 

Flags  (see  below)  that  define  behavior  options,  or  0  if  there  are  no  options, 
u 

Union  containing  Control  Behavi  ors  (IV-2224)  structures. 
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behaviorFlags  Constants 

kGraphi cs  FI agsGray 

Draw  lines  and  groups  in  gray. 
kGroupAl i gnText 

The  edit  text  items  in  the  group  have  the  same  size. 
kGroupSurroundBox 

The  group  should  be  surrounded  with  a  box. 
kGroupMatri x 

A  side-by-side  arrangement  of  the  group  is  okay. 
kGroupNoName 

The  name  of  the  group  should  not  be  displayed  above  the  box. 
kDi sabl eWhenNot Equal 

With  radio  buttons,  checkboxes,  or  other  controls.  Undocumented. 
kDi sabl eWhenEqual 

With  radio  buttons,  checkboxes,  or  other  controls.  Undocumented. 
kDi sabl eWhenLessThan 

With  radio  buttons,  checkboxes,  or  other  controls.  Undocumented. 
kDi sabl eWhenGreaterThan 

With  radio  buttons,  checkboxes,  or  other  controls.  Undocumented. 
kPopupStoreAsStri  ng 

With  pop-up  menus.  Undocumented. 

Programming  Info 
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ParameterDataT  y  pe 


Undocumented 

struct  ParameterDataType  { 
OSType  dataType; 

}; 

dataType 

Type  of  data  for  this  item. 

Programming  Info 

C  interface  file:  ImageCodec.  h 
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ParameterDataUsage 


Undocumented 

struct  ParameterDataUsage  { 

OSType  usageType; 

}; 

usageType 

Higher-level  purpose  of  the  data  or  group. 

Programming  Info 

C  interface  file:  ImageCodec . h 


ParameterDependancyRecord 


Undocumented 

struct  ParameterDependancyRecord  { 
long  dependCount; 

OSType  depends[l]; 

1: 

dependCount 

Number  of  items  in  the  depends  field, 
depends 

Undocumented 


Programming  Info 

C  interface  file:  ImageCodec.  h 


Pattern 


A  64-bit  image  that  defines  a  repeating  design  or  tone. 

struct  Pattern  { 

UInt8  pat [8] : 

1: 

pat 

A  row  of  the  pattern. 
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Discussion 

A  pattern  is  an  8-by-8  bit  square.  When  it  is  drawn,  adjacent  squares  are  aligned  to 
form  a  continuous  design. 

Programming  Info 

C  interface  file:  Quickdraw.h 
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Picture 


Contains  a  Mac  OS  Pi  cture. 

struct  Picture  { 

short  picSize; 

Rect  picFrame; 

}; 

pi cSi ze 

The  size  of  the  rest  of  this  record  for  a  version  1  picture.  The  information  in  this 
field  is  useful  only  for  version  1  pictures,  which  cannot  exceed  32  KB  in  size. 
Version  2  and  extended  version  2  pictures  can  be  much  larger  than  the  32  KB 
limit  imposed  by  the  2-byte  picSize  field. 

pi cFrame 

The  bounding  rectangle  for  the  picture  defined  in  the  rest  of  this  record.  This 
rectangle  is  used  to  scale  the  picture  if  you  draw  it  into  a  destination  rectangle 
of  a  different  size. 

Discussion 

Mac  OS  Pictures  are  sequences  of  saved  drawing  commands.  They  make  it  easier 
for  your  application  to  draw  complex  images  defined  in  other  applications,  and  for 
other  applications  to  display  images  created  with  your  application. 

Version  Notes 

There  are  three  versions  of  the  Pi  cture  structure.  Version  1  format  supports  only 
black-and-white  drawing  operations  at  72  dpi.  Version  2  format  can  be  used  when 
the  current  graphics  port  is  a  color  graphics  port.  Pictures  created  in  this  format 
support  color  drawing  operations  at  72  dpi.  The  extended  version  2  format  permits 
your  application  to  specify  resolutions  for  pictures  in  color  or  black  and  white.  To 
maintain  compatibility  with  the  version  1  picture  format,  the  picSize  field  was  not 
changed  for  the  version  2  picture  or  extended  version  2  formats. 

Programming  Info 

C  interface  file:  Quickdraw.h 
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PixelAspectRatioImageDescriptionExtension 


See  Also 

For  information  about  Mac  OS  Pictures,  see  Inside  Macintosh:  Imaging  With 
QnickDrazv  (listed  in  the  bibliography). 


PixelAspectRatioImageDescriptionExtension 


Adds  spacing  information  to  an  ImageDescri  pti  on  (IV-2285)  structure. 

struct  Pi xel AspectRati olmageDescri pti onExtensi on  { 

UInt32  hSpacing; 

UInt32  vSpacing; 

}; 

hSpaci ng 

Horizontal  spacing. 
vSpaci ng 

Vertical  spacing. 

Programming  Info 

C  interface  file:  ImageCodec.h 


See  Also 


See  ImageDescri  pti  on  (IV-2285). 


PixMap 


Contains  information  about  the  dimensions  and  contents  of  a  pixel  image,  as  well 
as  its  storage  format,  depth,  resolution,  and  color  usage. 

struct  PixMap  { 


Ptr 

baseAddr ; 

short 

rowBytes ; 

Rect 

bounds ; 

short 

pmVersi on ; 

short 

packType ; 

1  ong 

packSi ze ; 

Fi  xed 

hRes ; 

Fi  xed 

vRes ; 

short 

pi xel Type ; 

short 

pi xel Si ze ; 

short 

cmpCount ; 

short 

cmpSi ze ; 

OSType 

pi xel Format ; 

CTabHandl e 

pmTabl e ; 

IV-2332 
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void  *  pmExt; 

}; 

baseAddr 

For  an  onscreen  pixel  image,  a  pointer  to  the  first  byte  of  the  image.  For  optimal 
performance,  this  should  be  a  multiple  of  4.  The  baseAddr  field  of  the  PixMap 
record  for  an  offscreen  graphics  world  contains  a  handle  instead  of  a  pointer. 
Your  application  should  never  directly  access  the  baseAddr  field  of  the  Pi xMap 
record  for  an  offscreen  graphics  world. 
rowBytes 

The  offset  in  bytes  from  one  row  of  the  image  to  the  next.  The  value  must  be 
even,  less  than  0x4000,  and  for  best  performance  it  should  be  a  multiple  of  4.  The 
high  2  bits  of  rowBytes  are  used  as  flags.  If  bit  15  =  1,  the  data  structure  pointed 
to  is  a  PixMap  structure;  otherwise  it  is  a  Bi  tMap  (IV-2164)  structure, 
bounds 

The  boundary  rectangle,  which  links  the  local  coordinate  system  of  a  graphics 
port  to  QuickDraw's  global  coordinate  system  and  defines  the  area  of  the  bit 
image  into  which  QuickDraw  can  draw.  By  default,  the  boundary  rectangle  is 
the  entire  main  screen.  Do  not  use  the  value  of  this  field  to  determine  the  size 
of  the  screen;  instead  use  the  value  of  the  gdRect  field  of  the  GDevi  ce  (IV-2264) 
structure  for  the  screen. 

pmVersi on 

The  version  number  of  Color  QuickDraw  that  created  this  PixMap  structure.  The 
value  of  pmVersi  on  is  normally  0.  If  pmVersi  on  is  4,  Color  QuickDraw  treats  the 
PixMap  record's  baseAddr  field  as  32-bit  clean.  All  other  flags  are  private.  Most 
applications  never  need  to  set  this  field 
packType 

The  packing  algorithm  used  to  compress  image  data.  Color  QuickDraw 
currently  supports  a  pa  c  kTy  pe  of  0,  which  means  no  packing,  and  values  of  1  to 
4  for  packing  direct  pixels. 
packSi ze 

The  size  of  the  packed  image  mbytes.  When  the  packType  field  contains  the 
value  0,  this  field  is  always  set  to  0. 

hRes 

The  horizontal  resolution  of  the  pixel  image  in  pixels  per  inch.  By  default,  this 
value  is  0x00480000  (for  72  pixels  per  inch). 

vRes 

The  vertical  resolution  of  the  pixel  image  in  pixels  per  inch.  By  default,  this 
value  is  0x00480000  (for  72  pixels  per  inch). 


STR 
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pi xel Type 

The  storage  format  for  a  pixel  image.  Indexed  pixels  are  indicated  by  a  value  of 
0.  Direct  pixels  are  specified  by  a  value  of  RGBDi  rect,  or  16.  In  the  Pi  xMap  record 
of  the  GDevi ce  (IV-2264)  structure  for  a  direct  device,  this  field  is  set  to 
RGBDi  rect  when  the  screen  depth  is  set. 
pi xel Si ze 

The  number  of  bits  used  to  represent  a  pixel.  Indexed  pixels  can  have  sizes  of  1, 
2, 4,  and  8  bits;  direct  pixel  sizes  are  16  and  32  bits. 

cmpCount 

The  number  of  components  used  to  represent  a  color  for  a  pixel.  With  indexed 
pixels,  each  pixel  is  a  single  value  representing  an  index  in  a  color  table,  and 
therefore  this  field  contains  the  value  1;  the  index  is  the  single  component.  With 
direct  pixels,  each  pixel  contains  three  components  (one  integer  each  for  the 
intensities  of  red,  green,  and  blue)  so  this  field  contains  the  value  3. 
cmpSi ze 

The  size  in  bits  of  each  component  for  a  pixel.  Color  QuickDraw  expects  that 
the  sizes  of  all  components  are  the  same,  and  that  the  value  of  the  cmpCount  field 
multiplied  by  the  value  of  the  cmpSi  ze  field  is  less  than  or  equal  to  the  value  in 
the  pi  xel  Si  ze  field. 

For  an  indexed  pixel  value,  which  has  only  one  component,  the  value  of  the 
cmpSi  ze  field  is  the  same  as  the  value  of  the  pi  xel  Si  ze  field;  that  is,  1,  2,  4,  or  8. 
For  direct  pixels  there  are  two  additional  possibilities.  A  16-bit  pixel,  which  has 
three  components,  has  a  cmpSi  ze  value  of  5;  this  leaves  an  unused  high-order 
bit,  which  Color  QuickDraw  sets  to  0.  A  32-bit  pixel,  which  has  three 
components  (red,  green,  and  blue),  has  a  cmpSi  ze  value  of  8;  this  leaves  an 
unused  high-order  byte,  which  Color  QuickDraw  sets  to  0. 

If  presented  with  a  32-bit  image  (for  example,  in  the  Copy  Bi  ts  procedure)  Color 
QuickDraw  passes  whatever  bits  are  there,  and  it  does  not  set  the  high  byte  to 
0.  Generally,  therefore,  your  application  should  clear  the  memory  for  the  image 
to  0  before  creating  a  16-bit  or  32-bit  image, 
pi aneBytes 

The  offset  in  bytes  from  one  drawing  plane  to  the  next.  This  field  is  set  to  0. 
pmTabl e 

A  handle  to  a  Col  orTabl  e  (IV-2210)  structure  for  the  colors  in  this  pixel  map. 
pmReserved 

Reserved.  This  field  must  be  set  to  0  for  future  compatibility. 
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pi xel Format 

The  way  the  pixels  are  arranged;  see  "Pixel  Formats"  (IV-2686). 
pmTabl e 

Color  map  for  this  structure. 
pmExt 

Handle  to  a  PixMapExtension  (IV-2335)  structure.  Set  to  N I L  if  there  is  no 
extension. 

Discussion 

The  pixel  map  for  a  window's  color  graphics  port  always  consists  of  the  pixel  depth, 
color  table,  and  boundary  rectangle  of  the  main  screen,  even  if  the  window  is 
created  on  or  moved  to  an  entirely  different  screen. 

Version  Notes 

Earlier  versions  of  this  structure  were  different  in  the  last  three  fields;  see  the  C 
interface  file  for  details. 

Programming  Info 

C  interface  file:  Quickdraw.h 

See  Also 

See  PixMapExtension  (IV-2335). 
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PixMapExtension 


Extends  the  PixMap  (IV-2332)  structure. 


struct  PixMapExtension  { 


}; 


1  ong 
unsigned  long 
void  * 

1  ong 

unsigned  long 
unsigned  long 
unsigned  long 
1  ong 


extSi ze ; 
pmBi ts ; 
pmGD ; 
pmSeed ; 
reservedO ; 
reservedl ; 
reserved2 ; 

1 ongRowBytes ; 


extSi ze 

The  size  of  this  structure. 
pmBi ts 

The  PixMap  attributes  bitfield. 
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pmGD 

A  handle  to  a  GDevi  ce  (IV-2264)  structure. 
pmSeed 

If  this  structure  changes,  this  number  will  change. 
reservedO 

Reserved  for  future  use. 
reservedl 

Reserved  for  future  use. 
reserved2 

Reserved  for  future  use. 

1 ongRowBytes 

Field  used  when  the  value  of  the  rowBytes  field  of  PixMap  (IV-2332)  is  greater 
than  16382. 

Programming  Info 

C  interface  file:  Quickdraw.h 


PixPat 


Stores  a  pixel  pattern. 


struct  PixPat  { 
short 

Pi xMapHandl e 
Handl e 
Handl e 
short 
Handl e 
Pattern 

}; 


patType ; 
patMap ; 
patData  ; 
patXData  ; 
patXVal i d ; 
patXMap ; 
patlData  ; 


patType 

The  pattern's  type.  The  value  0  specifies  a  basic  QuickDraw  bit  pattern,  the 
value  1  specifies  a  full-color  pixel  pattern,  and  the  value  2  specifies  an  RGB 
pattern. 

patMap 

A  handle  to  a  Pi  xMap  (IV-2332)  structure  that  describes  the  pattern's  pixel 
image.  The  PixMap  structure  can  contain  indexed  or  direct  pixels. 
patData 

A  handle  to  the  pattern's  pixel  image. 
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patXData 

A  handle  to  an  expanded  pixel  image  used  internally  by  Color  QuickDraw. 
patXVal i d 

A  flag  that,  when  set  to  -1,  invalidates  the  expanded  data. 
patXMap 

Reserved. 

patlData 

A  bit  pattern  (typically  50  percent  gray)  to  be  used  when  the  pattern  defined  by 
this  PixPat  structure  is  drawn  into  a  Graf  Port  record. 

Programming  Info 

C  interface  file:  Quickdraw.h 

See  Also 

See  Inside  Macintosh:  Imaging  With  QirickDrazv  (listed  in  the  bibliography). 


PlanarComponentlnfo 


Describes  a  part  of  a  planar  pixel  map. 

struct  PlanarComponentlnfo  { 

SInt32  offset; 

UInt32  rowBytes; 

}; 

offset 

The  offset  to  this  part. 
rowBytes 

The  offset  in  bytes  from  one  row  of  the  image  to  the  next. 

Programming  Info 

C  interface  file:  ImageCodec.h 


See  Also 

Seethe  PI  anarPixMapInfo  (IV-2337)  structure. 


PlanarPixMapInfo 


Holds  an  array  of  PI  anarComponentlnfo  (IV-2337)  structures. 

struct  PlanarPixMapInfo  { 

PI anarComponentlnfo  component  I nfo[l] ; 


STR 
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PlanarPixmapInfoSorensonYUV9 


}; 

componentlnfo 

An  array  of  PI  anarComponentlnfo  (IV-2337)  structures. 

Programming  Info 

C  interface  file:  ImageCodec.h 


PlanarPixmapInf  oSorensonYUV  9 


Undocumented 

struct  PI anarPixmapInfoSorensonYUV9  { 

PI anarComponentlnfo  component  I nfoY ; 

PI  anarComponentlnfo  component  I  nfoLI ; 

PI  anarComponentlnfo  component  I nfoV  ; 

}; 

componentlnfoY 

Undocumented 

componentlnfoU 

Undocumented 

componentlnfoV 

Undocumented 


Programming  Info 

C  interface  file:  ImageCodec.h 


PlanarPixmapInf  oYUV  420 


Undocumented 

struct  PI anarPixmapInfoYUV420  { 

PI anarComponentlnfo  componentlnfoY ; 

PI anarComponentlnfo  component  I nfoCb  ; 

PI anarComponentlnfo  component  I nfoCr ; 

1: 

componentlnfoY 

Undocumented 
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componentlnfoCb 

Undocumented 

componentlnfoCr 

Undocumented 

Programming  Info 

C  interface  file:  ImageCodec.h 


STR 


Point 


Defines  the  position  of  a  point. 

struct  Point  { 
short  v; 

short  h; 

}; 

v 

The  vertical  coordinate  of  the  point, 
h 

The  horizontal  coordinate  of  the  point. 

Programming  Info 

C  interface  file:  MacTypes .  h 


PointerDataRefRecord 


References  data  in  memory  without  using  a  handle. 

struct  PointerDataRefRecord  { 
void  *data; 

Size  dataLength; 

}; 

data 

A  pointer  to  some  data. 
dataLength 

The  length  of  the  data  in  bytes. 
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Discussion 

This  structure  supports  references  to  data  in  memory,  but  does  not  require  that  data 
reside  within  a  block  allocated  by  the  Mac  OS  Memory  Manager.  Here  is  an 
example  of  its  use: 

Componentlnstance  dataHandler; 

Poi nterDataRef  dataref  = 

( Poi nterDataRef ) NewHandl e( si zeof( Poi nterDataRef Record)); 


(**dataref ) .data  =  myPoi nterToSomeMedi a  ; 
(**dataref ) .dataLength  =  theLengthOfTheMedi a ; 


osstat  =  OpenADataHandlertdataRef ,  Poi nterDataHandl erSubType ,  NIL, 

(OSType)O,  NIL,  kDataHCanRead ,  &dataHandl er ) ; 


. . .  etc . 


Version  Notes 

Introduced  in  QuickTime  5. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


PreviewResourceRecord 


Contains  information  about  a  preview. 

struct  PreviewResourceRecord  { 
unsigned  long  modDate; 
short  version; 

OSType  resType; 

short  resID; 

}; 

modDate 

Contains  the  modification  time  (in  the  standard  Macintosh  format  of  seconds 
since  midnight,  January  1, 1904)  of  the  file  for  which  the  preview  was  created. 
This  parameter  allows  you  to  find  out  if  the  preview  is  out  of  date  with  the 
contents  of  the  file, 
versi on 

Contains  the  version  number  of  the  preview  resource.  The  low  bit  of  the 
version  is  a  flag  for  preview  components  that  only  reference  their  data.  If  the  bit 
is  set,  it  indicates  that  the  resource  identified  in  the  preview  resource  is  not 
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owned  by  the  preview  component,  but  is  part  of  the  file.  It  is  not  removed  when 
the  preview  is  updated  or  removed,  as  it  would  if  the  version  number  were  0. 

resType 

Identifies  the  type  of  the  preview  component  used  to  display  the  preview  data 
and  the  type  of  the  atom  containing  the  preview  data. 


STR 


Contains  the  index  (1-based)  of  the  atom  to  be  used.  For  example,  a  resType  of 
PICT  and  a  res  I D  of  2  tells  QuickTime  to  use  the  second  PICT  atom  in  the  file 
for  the  preview  data. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 


PublicHandlerlnfo 


Contains  data  for  a  '  hdl  r '  (IV-2540)  atom, 
struct  PublicHandlerlnfo  { 


1  ong 

fl ags  ; 

1  ong 

componentType ; 

1  ong 

componentSubType ; 

1  ong 

componentManuf acturer 

1  ong 

componentFl ags ; 

1  ong 

component Fl agsMask; 

char 

}; 

componentName[l] ; 

fl  ags 

One  byte  of  version  information  followed  by  three  bytes  of  flags.  The  flags 
bytes  are  not  currently  used. 

componentType 

A  four-character  code  that  identifies  the  type  of  component.  See  "Codec 
Identifiers"  (IV-2655).  All  components  of  a  particular  type  support  a  common 
set  of  interface  routines.  Your  application  uses  this  field  to  search  for 
components  of  a  given  type. 
componentSubType 

A  four-character  code  that  identifies  the  subtype  of  the  component.  Different 
subtypes  of  a  component  type  may  support  additional  features  or  provide 
interfaces  that  extend  beyond  the  standard  routines  for  a  given  component 
type.  For  example,  the  subtype  of  an  image  compressor  component  indicates 
the  compression  algorithm  employed  by  the  compressor.  Your  application  can 
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use  the  componentSubType  field  to  perform  a  more  specific  lookup  operation 
than  is  possible  using  only  the  componentType  field.  Set  this  parameter  to  0  to 
select  a  component  with  any  subtype  value. 

componentManuf act ure r 

A  four-character  code  that  identifies  the  manufacturer  of  the  component.  This 
field  allows  for  further  differentiation  between  individual  components.  For 
example,  components  made  by  a  specific  manufacturer  may  support  an 
extended  feature  set.  Components  provided  by  Apple  have  a  manufacturer 
value  of  '  appl  ' .  Your  application  can  use  this  field  to  find  components  from  a 
certain  manufacturer.  A  value  of  0  operates  as  a  wildcard 

componentFl ags 

A  32-bit  field  that  contains  flags  describing  your  component's  capabilities.  The 
high-order  8  bits  are  defined  by  the  Component  Manager.  You  should  set  these 
bits  to  0.  The  low-order  24  bits  are  specific  to  each  component  type.  These  flags 
can  be  used  to  indicate  the  presence  of  features  or  capabilities  in  a  given 
component. 

componentFl ags Mask 

A  32-bit  field  that  indicates  which  flags  in  the  componentFl  ags  field  are  relevant 
to  a  particular  component  search  operation.  For  each  flag  in  the  componentFl  ags 
field  that  is  to  be  considered  as  a  search  criterion,  your  application  should  set 
the  corresponding  bit  in  this  field  to  1.  To  ignore  a  flag,  set  the  bit  to  0. 

componentName 

The  component's  name. 

Programming  Info 

C  interface  file:  MoviesFormat.h 


See  Also 

See  '  hdl  r '  (IV-2540). 


QDProcs 


Stores  Universal  Procedure  Pointers  to  low-level  drawing  routines. 


struct  QDProcs  { 
QDTextUPP 

textProc ; 

QDLineUPP 

1 i neProc ; 

QDRectUPP 

rectProc ; 

QDRRectUPP 

rRectProc 

QDOvalUPP 

oval Proc ; 

QDArcUPP 

arcProc ; 

QDPolyUPP 

polyProc ; 

IV-2342 
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QDRgnUPP  rgnProc; 

QDBi tsUPP  bi tsProc ; 

QDCommentUPP  commentProc; 

QDTxMeasUPP  txMeasProc; 

QDGetPicUPP  getPicProc; 

QDPutPicUPP  putPicProc; 

}; 


STR 


textProc 

A  Universal  Procedure  Pointer  to  the  low-level  routine  that  draws  text.  The 
standard  QuickDraw  routine  is  the  StdText  procedure. 

1 i neProc 

A  Universal  Procedure  Pointer  to  the  low-level  routine  that  draws  lines.  The 
standard  QuickDraw  routine  is  the  StdLi  ne  procedure. 
rectProc 

A  Universal  Procedure  Pointer  to  the  low-level  routine  that  draws  rectangles. 
The  standard  QuickDraw  routine  is  the  StdRect  procedure. 
rRectProc 

A  Universal  Procedure  Pointer  to  the  low-level  routine  that  draws  rounded 
rectangles.  The  standard  QuickDraw  routine  is  the  StdRRect  procedure. 

oval Proc 

A  Universal  Procedure  Pointer  to  the  low-level  routine  that  draws  ovals.  The 
standard  QuickDraw  routine  is  the  StdOval  procedure. 
arcProc 

A  Universal  Procedure  Pointer  to  the  low-level  routine  that  draws  arcs.  The 
standard  QuickDraw  routine  is  the  StdArc  procedure. 
polyProc 

A  Universal  Procedure  Pointer  to  the  low-level  routine  that  draws  polygons. 
The  standard  QuickDraw  routine  is  the  StdPoly  procedure. 

rgnProc 

A  Universal  Procedure  Pointer  to  the  low-level  routine  that  draws  regions.  The 
standard  QuickDraw  routine  is  the  StdRgn  procedure, 
bi tsProc 

A  Universal  Procedure  Pointer  to  the  low-level  routine  that  copies  bitmaps. 
The  standard  QuickDraw  routine  is  the  StdBi  ts  procedure. 
commentProc 

A  Universal  Procedure  Pointer  to  the  low-level  routine  for  processing  a  picture 
comment.  The  standard  QuickDraw  routine  is  the  StdComment  procedure. 
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txMeasProc 

A  Universal  Procedure  Pointer  to  the  low-level  routine  for  measuring  text 
width.  The  standard  QuickDraw  routine  is  the  StdTxMeas  function. 
getPi cProc 

A  Universal  Procedure  Pointer  to  the  low-level  routine  for  retrieving 
information  from  the  definition  of  a  picture.  The  standard  QuickDraw  routine 
is  the  StdGetPic  procedure. 

putPi cProc 

A  Universal  Procedure  Pointer  to  the  low-level  routine  for  saving  information 
as  the  definition  of  a  picture.  The  standard  QuickDraw  routine  is  the  StdPutPic 
procedure. 

Programming  Info 

C  interface  file:  Quickdraw.h 


QElem 


A  queue  element  for  a  Windows  QHdr  (IV-2345)  structure. 

struct  QElem  { 

struct  QElem  * 
short 
short 

}; 

q L i  nk 

A  pointer  to  the  next  QE1  em  structure. 
qType 

Undocumented 
qData 

Undocumented 

Associated  Functions 

Dequeue  (1-253) 

Programming  Info 

C  interface  file:  OSUti  1  s .  h 

See  Also 

See  QHdr  (IV-2345). 


q L i  nk ; 
qType; 
qData[l]  ; 
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QHdr 


A  Windows  queue  header  structure. 

struct  QHdr  { 
short 
short 
1  ong 

QE1  emPtr 
QE1  emPtr 

}; 

q FI  ags 

Undocumented 

pad 

Unused. 

MutexID 

Undocumented 

qHead 

Undocumented 
q  T  a  i  1 

Undocumented 

Associated  Functions 

CDSequenceSetSourceDataQueue  (1-87) 

Programming  Info 

C  interface  file:  OSUti  1  s  .  h 


q FI  ags  ; 
pad ; 

MutexID; 
qHead ; 
q  T  a  i  1  ; 


STR 


See  Also 

See  QE1  em  (IV-2344). 


QT  AltComponentCheckRecord 


Provides  component  information  for  an  '  rmcd '  (IV-2576)  reference  movie 
component  check  atom. 

struct  QTA1 tComponentCheckRecord  { 
long  flags; 

ComponentDescri pti on  cd; 

unsigned  long  minVersion; 

}; 
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fl  ags 

Unused;  set  to  0. 
cd 

A  ComponentDescri  pti  on  (IV-2212)  data  structure  giving  the  attributes  of  a  class 
of  components, 
mi nVersi on 

The  minimum  version  number  of  the  required  component. 

Programming  Info 

C  interface  file:  MoviesFormat.h 

See  Also 

See  '  rmcd '  (IV-2576). 

QT  AltCPURatingRecord 

Provides  the  user's  CPU  speed  information  for  an  ’  rmcs  ’  (IV-2577)  reference  movie 
CPU  rating  atom. 

struct  QTAltCPURatingRecord  { 

UInt32  flags; 

UIntl6  speed; 

}; 

fl  ags 

Unused;  set  to  0. 
speed 

A  CPU  speed  constant  (see  below). 

speed  Constants 

kQTCPUSpeedlRati  ng 

Slowest  CPU  speed 
kQTCPUSpeed2Rati  ng 

Next-to-slowest  CPU  speed. 
kQTCPUSpeed3Rati  ng 

Medium  CPU  speed. 
kQTCPUSpeed4Rati  ng 

Next-to-fastest  CPU  speed. 
kQTCPUSpeed5Rati  ng 
Fastest  CPU  speed. 
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Programming  Info 

C  interface  file:  Movi  es Format .  h 


See  Also 

See  '  rmcs '  (IV-2577). 


QT  AltDataRateRecord 

Provides  data  rate  information  for  an  '  rmd  r '  (IV-2578)  reference  movie  data  rate 
atom. 

struct  QTAltDataRateRecord  { 
long  flags; 

long  dataRate; 

}; 

fl  ags 

Unused;  set  to  0. 
dataRate 

A  data  rate  constant  (see  below). 

dataRate  Constants 

kDataRatel44ModemRate 
A  rate  of  14.4  kbps. 
kDataRate288ModemRate 
A  rate  of  28.8  kbps. 
kDataRatelSDNRate 
A  rate  of  56  kbps. 
kDataRateDual ISDNRate 
A  rate  of  112  kbps. 
kDataRateTIRate 

A  rate  of  1.5  Mbps. 
kData Rate  Inf ini  teRate 

A  rate  higher  than  any  given  rate. 

Programming  Info 

C  interface  file:  Movi  es  Format .  h 

See  Also 

See  '  rmdr '  (IV-2578). 


STR 
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QT  AltLanguageRecord 


Provides  language  information  for  an  '  rml  a  '  (IV-2579)  reference  movie  language 
atom. 

struct  QTAltLanguageRecord  { 
long  flags; 

short  language; 

}; 

fl  ags 

Unused;  set  to  0. 

1 anguage 

The  movie's  language.  See  "Localization  Codes"  (IV-2673). 

Programming  Info 

C  interface  file:  Movies  Format,  h 


See  Also 

See  '  rml  a '  (IV-2579). 


QT  AltV  ersionCheckRecord 


Provides  version  information  for  an  '  rmvc '  (IV-2581)  reference  movie  version  check 
atom. 

struct  QTA1 tVersi onCheckRecord  { 


1  ong 

fl ags  ; 

OSType 

gestal tTag ; 

UInt32 

vail; 

UInt32 

val  2 ; 

short 

checkType ; 

}; 

fl  ags 

Unused;  set  to  0. 
gestal tTag 

A  system  capability  code. 

val  1 

A  version  number  (see  discussion  below). 

val  2 

A  version  number  (see  discussion  below). 
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QTAtomSpec 


checkType 

A  checking  mode  constant  (see  below). 

checkType  Constants 

kVersi onCheckMi n 

Field  vail  contains  the  minimum  version  number  required. 
kVersi onCheckMask 

When  field  val  2  is  used  to  mask  the  actual  version  number,  the  result  is  equal 
to  field  vail. 

Discussion 

By  selecting  the  checkType  constant  and  putting  appropriate  values  into  vail  and 
v  a  1 2,  you  can  check  either  for  product  version  numbers  later  than  a  given  release  or 
for  specific  information  within  the  actual  version  number. 
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QTAtomSpec 


Specifies  an  atom  and  its  container. 

struct  QTAtomSpec  { 

QTAtomContai ner 
QTAtom 

}; 

contai ner 

A  QT  atom  container. 

atom 

A  QT  atom. 
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contai ner ; 
atom; 


QTCallBackHeader 

Specifies  the  application-defined  function  for  a  callback  operation, 
struct  QTCallBackHeader  { 
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Data  Structures 


QTCallBackHeader 


long  cal  1 BackFl ags  ; 

long  reserved!.; 

SInt8  qtPri vate[40]  ; 

}; 

cal  1 BackFl ags 

Contains  flags  (see  below)  that  your  component  can  use  to  communicate 
scheduling  information  about  the  callback  event  to  the  Movie  Toolbox.  This 
scheduling  information  tells  the  Movie  Toolbox  what  time  base  events  your 
clock  component  needs  to  know  about  to  support  the  callback  event.  All 
unused  flags  must  be  set  to  0. 

reservedl 

Reserved.  Do  not  use. 
qtPri vate 

Reserved.  Do  not  use. 

callBackFlags  Constants 

qtcbNeedsRateChanges 

Indicates  that  your  clock  component  needs  to  know  about  rate  changes.  If  you 
set  this  flag  to  1,  the  Movie  Toolbox  calls  Cl  ockRateChanged  (1-97)  whenever  the 
rate  of  the  callback  event's  time  base  changes. 
qtcbNeedsTimeChanges 

Indicates  that  your  clock  component  needs  to  know  about  time  changes.  If  you 
set  this  flag  to  1,  the  Movie  Toolbox  calls  ClockTimeChanged  (1-100)  whenever  a 
program  changes  the  time  value  of  the  time  base,  or  when  the  time  value 
changes  by  an  amount  that  is  different  from  the  time  base's  rate. 
qtcbNeedsStartStopChanges 

Indicates  that  your  clock  component  needs  to  know  about  the  time  base's  start 
and  stop  changes.  If  you  set  this  flag  to  1,  the  Movie  Toolbox  calls 
Cl  ockStartStopChanged  (1-99)  whenever  a  program  changes  the  start  or  stop 
time  of  the  time  base. 

Discussion 

Your  clock  component  provides  functions  that  allow  programs  to  use  this  data 
structure,  which  specifies  the  callback  function  for  an  operation.  Your  application 
can  obtain  callback  function  identifiers  by  calling  Cl  ockNewCal  1  Back  (1-96). 
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See  Cl  ockNewCal  1  Back  (1-96). 
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QTChapterlnfoRecord 


Stores  information  for  an  entry  in  a  chapter  list. 

struct  QTChapterlnfoRecord  { 
long  index; 

TimeValue  time; 
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}; 

i  ndex 

An  index  number  for  the  entry.  The  first  chapter  has  index  of  1. 

ti  me 

The  time  in  the  movie  that  the  entry  marks.  Set  this  field  to  -1  if  no  more  chapter 
entries  are  available. 


name 

The  readable  name  of  the  entry. 
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QTCustomActionTargetRecord 


Defines  a  target  for  Cal  1  ComponentExecuteWi  redActi  on  (1-60). 

struct  QTCustomActionTargetRecord  { 

Movie  movie; 

DoMCActi on  U  P  P  doMCActi onCallbackProc; 
long  call BackRef con ; 

Track  track; 

long  trackObjectRefCon ; 

Track  defaultTrack; 

long  defaul tObjectRefCon ; 

long  reservedl; 

long  reserved2; 

}; 

movi  e 

A  movie  identifier  obtained  from  such  functions  as  NewMovi  e  (11-1069), 
NewMovi  eFromFi  1  e  (11-1080),  and  NewMovi  eFromHandl  e  (11-1084). 
doMCActi onCal 1 backProc 

A  Universal  Procedure  Pointer  that  accesses  a  DoMCActi  onProc  (III— 2082) 
callback. 
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QTDoScriptRecord 


cal  1 BackRefcon 

A  reference  constant  to  be  passed  to  the  DoMCActi  on  P  roc  callback.  Use  this  value 
to  point  to  a  data  structure  containing  any  information  the  callback  needs, 
track 

A  track  identifier  obtained  from  such  functions  as  NewMovi eT rack  (11-1092)  and 
GetMovi  eT  rack  (1-497). 

trackObjectRefCon 
Undocumented 
defaul tT  rack 

The  identifier  of  a  default  track,  obtained  from  such  functions  as  NewMovi  eTrack 
(11-1092)  and  GetMovi  eTrack  (1-497). 
defaul t Object Ref Con 
Undocumented 
reservedl 

Reserved. 

reserved2 

Reserved. 
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QTDoScriptRecord 


Provides  information  to  MCDoActi  on  (11-801)  when  mcActi  onDoScri  pt  is  passed  to  it. 

struct  QTDoScriptRecord  { 

long  scri ptTypeFl ags  ; 
char  *  command: 

char  *  arguments: 

1: 

scri ptTypeFl ags 

Constants  (see  below)  that  define  the  type  of  script, 
command 

Pointer  to  the  wired  action  command, 
arguments 

Pointer  to  the  wired  action  arguments. 
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scriptTypeFlags  Constants 

kScri ptlsUnknownType 
Value  is  1L  «  0. 
kScri pt Is JavaScript 
Value  is  1L  «  1, 
kScri pt Is  Li ngo Event 
Value  is  1L  «  2. 
kScri ptlsVBEvent 
Value  is  1L  «  3. 
kScri ptlsProjectorCommand 
Value  is  1L  «  4. 

Version  Notes 

Introduced  in  QuickTime  4.1. 
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See  MCDoAction  (11-801). 
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QTEvaluateExpressionRecord 


Undocumented 

struct  QTEvaluateExpressionRecord  { 
QTAtomSpec  expressi onSpec ; 

float  *  expressi onResul t ; 

1; 

expressi onSpec 
Undocumented 
expressi onResul t 
Undocumented 
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QTEventRecord 

Records  a  user  event  for  QuickTime. 
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QTFetchParameterAsRecord 


struct  QTEventRecord  { 
long  version; 

OSType  eventType; 

Point  where; 

long  flags; 

}; 

versi on 

Undocumented 

eventType 

Undocumented 

where 

The  location  of  the  cursor  at  the  time  the  event  was  posted, 
fl  ags 

Undocumented 

Discussion 

This  structure  is  used  by  the  kActi  onSendQTEventToSpri  te  action. 

Associated  Functions 

ActionsProc  (III — 2075) 
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QTFetchParameterAsRecord 

Undocumented 

struct  QTFetchParameterAsRecord  { 

QTAtomSpec  paramLi stSpec ; 
long  paramlndex; 

long  paramType; 

long  al 1 owedFl ags ; 

void  *  min; 

void  *  max; 

void  *  currentVal ue  ; 

void  *  newValue; 

Boolean  i  stlnsi  gnedVal  ue  ; 

}; 

paramLi stSpec 

Undocumented 
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QTGetChapterTimeRecord 


paramlndex 

Undocumented 

paramType 

Undocumented 
al  1  owedFl  ags 

Undocumented 

mi  n 

Undocumented 

max 

Undocumented 
currentVal  lie 

Undocumented 
newVal ue 

Undocumented 
i  sllnsi  gnedVal  ue 
Undocumented 
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QTGetChapterTimeRecord 


Undocumented 

struct  QTGetChapterTimeRecord  { 
StringPtr  chapterName; 

TimeRecord  chapterTime; 

}; 

chapterName 

Undocumented 
chapterT i me 

Undocumented 
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QTGetCursorByIDRecord 


QTGetCursorByIDRecord 

Undocumented 

struct  QTGetC 
short 
Handl e 
1  ong 

}; 

cursorlD 

Undocumented 
col orCursorData 
Undocumented 
reservedl 

Undocumented 


ursorByIDRecord  { 
cursorlD; 
col orCursorData ; 
reservedl ; 
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QTGetExtemalMovieRecord 

Undocumented 

struct  QTGetExtemalMovieRecord  { 

long  targetType; 

StringPtr  movi eName ; 

long  movielD; 

MoviePtr  theMovie; 

MovieControllerPtr  theController; 

}; 

targetType 

Set  to  kTargetMovi  eName  or  kTar get Movi  elD. 
movi eName 

Undocumented 
movi elD 

Undocumented 
theMovi e 

Undocumented 
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QTMIDIPort 


theControl 1 er 

Undocumented 
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QTMIDIPort 


Provides  information  about  a  MIDI  port, 
struct  QTMIDIPort  { 

Synthes! zerConnecti ons  portConnecti ons ; 

Str63  portName; 

}; 

portConnecti ons 

A  Synthesi  zerConnecti  ons  (IV-2464)  structure. 
portName 

The  name  of  the  output  port. 
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QTMIDIPortList 


Contains  an  array  of  information  structures  about  MIDI  ports. 

struct  QTMIDIPortList  { 

short  portCount; 

QTMIDIPort  port[l]; 

}; 

portCount 

The  number  of  structures  in  the  port  field. 

port 

An  array  of  QTMIDIPort  (IV-2357)  structures. 

Associated  Functions 

NAGetMIDIPorts  (11-1025) 
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QTMovieExportSourcelnfo 


See  Also 

See  QTMIDIPort  (IV-2357). 


QTMovieExportSourcelnfo 


Defines  a  single  movie  export  data  source  by  type,  minimum  and  maximum  sources 
of  that  type,  and  flags  for  that  entry. 

struct  QTMovieExportSourcelnfo  { 

OSType  mediaType; 

UIntl6  minCount; 

UIntl6  maxCount; 

long  flags; 

}; 

medi aType 

Media  type  of  the  source;  see  "Codec  Identifiers"  (IV-2655). 
mi nCount 

Minimum  number  of  sources  of  this  kind  required;  0  if  none  are  required. 
maxCount 

Maximum  number  of  sources  of  this  kind  allowed;  -1  if  unlimited  sources  are 
allowed. 

fl  ags 

Reserved  for  flags. 
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QTMovieExportSourceRecord 


Contains  an  array  of  QTMovieExportSourcelnfo  (IV-2358)  structures. 

struct  QTMovieExportSourceRecord  { 
long  count; 

long  reserved; 

QTMovi e Expo rt Source  Info  sourceArray[l]; 

}; 


count 

The  number  of  structures  in  the  sourceArray  field. 
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QTParamDialogEventRecord 


reserved 

Reserved;  do  not  use. 
sourceArray 

An  array  of  QTMovi eExportSourcelnfo  (IV-2358)  structures. 

Discussion 

A  '  s  r c# '  resource  may  be  associated  with  export  components  that  implement 
Movi eExportFromProceduresToDataRef  (11-922).  The  resource  is  used  to  indicate  the 
types  of  data  sources  the  export  component  can  support.  For  each  type,  it  also 
indicates  the  minimum  and  maximum  number  of  data  sources  of  that  type.  Clients 
can  use  this  information  to  determine  if  the  number  of  data  sources  they  want  to 
export  can  be  handled  directly  by  the  exporter.  If  the  data  source  type  is  supported 
by  fewer  sources  are  allowed,  the  client  application  must  either  export  a  fewer 
number  of  sources  or  combine  the  data  from  its  candidate  sources  itself  to  meet  the 
limitation  imposed  by  the  exporter. 
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QTParamDialogEventRecord 


Contains  information  about  a  user  event  in  a  dialog  box. 

struct  QTParamDialogEventRecord  { 

EventRecord  *  theEvent; 

DialogPtr  whichDialog; 

short  itemHit; 

}; 

theEvent 

Pointer  to  an  EventRecord  (IV-2246)  structure  that  describes  the  event  received 
by  the  dialog  box. 

whi chDi al og 

Pointer  to  the  dialog  box  that  received  the  event, 
i temHi t 

Number  of  the  dialog  item  that  was  hit. 
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Data  Structures 


QTParamFetchPreviewRecord 


QTParamFetchPreviewRecord 


Contains  information  that  defines  a  preview. 

struct  QTParamFetchPreviewRecord  { 

GWorldPtr  theWorld; 

Fixed  percentage; 

}; 

theWorl d 

Apointer  to  the  CGraf  Port  (IV-2168)  that  defines  the  graphics  world  into  which 
to  draw  the  preview, 
percentage 

The  frame  portion  to  be  drawn,  from  0.0  to  1.0. 
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QTParamPreviewRecord 


Contains  information  about  a  preview  image. 

struct  QTParamPreviewRecord  { 
long  sourcelD; 

PicHandle  sourcePi cture ; 

}; 

sourcelD 

The  number  of  the  preview  image. 
sourcePi cture 

The  preview  image. 
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QTPresetlnfo 


Provides  data  for  a  QTPresetLi  stRecord  (IV-2361)  structure. 

struct  QTPresetlnfo  { 

OSType  presetKey; 

UInt32  presetFlags; 
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QTPresetListRecord 


OSType 

setti ngsResourceType ; 

SIntl6 

setti  ngs Resource  ID; 

SIntl6 

paddi ngl ; 

SIntl6 

nameStri ngLi stID ; 

SIntl6 

nameStri nglndex; 

SIntl6 

i  nfoStri ngLi stID ; 

SIntl6 

}; 

i  nfoStri nglndex; 

presetKey 

The  unique  key  for  this  structure  in  the  QTPresetListRecord  (IV-2361 )  structure. 
presetFl ags 

Flags  about  this  preset 
setti ngsResourceType 

Resource  type  of  settings  resource, 
setti ngs Resource  ID 

Resource  id  of  settings  resource 
paddi ngl 
Unused. 

nameStri ngLi stID 

Name  string  list  resource  ID. 
nameStri nglndex 

Name  string  index, 
i  nfoStri  ngLi  stID 

Info  string  list  resource  ID 
i nfoStri nglndex 

Info  string  index. 
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QTPresetListRecord 


Contains  an  array  of  QTPresetlnfo  (IV-2360)  structures. 


struct  QTPresetListRecord  { 


UInt32 

UInt32 

UInt32 


fl ags ; 
count ; 
reserved ; 


QTPresetlnfo  presetsArray[l] ; 


Inside  QuickTime:  Data  Structures 


IV-2361 


Data  Structures 


QTResolutionSettings 


}; 

fl  ags 

Flags  for  the  whole  list, 
count 

The  number  of  elements  in  the  presetsArray  field, 
reserved 

Reserved. 

presetsArray 

An  array  of  QTPresetlnfo  (IV-2360)  structures. 
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QTResolutionSettings 


Provides  data  for  a  '  reso '  (IV-2576)  atom. 

struct  QTResolutionSettings  { 

Fixed  hori zontal Resol uti on ; 

Fixed  verti cal  Resol uti on ; 

}; 

hori zontal Resolution 

The  horizontal  resolution,  in  dots  per  inch, 
verti cal  Resol uti on 

The  vertical  resolution,  in  dots  per  inch. 
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QTRestartAtTimeRecord 


Undocumented 

struct  QTRestartAtTimeRecord  { 
TimeVal ue  startTime ; 

Fixed  rate; 

1: 
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QTRuntimeSpriteDescStruct 


startTime 

The  start  time  in  the  movie  time  scale. 

rate 

The  playback  rate.  If  the  rate  is  0,  the  movie's  current  rate  is  maintained. 
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QTRuntimeSpriteDescStruct 


Provides  a  sprite  description  for  the  Spri  teMedi  aNewSpri  te  (III— 1901)  function. 

QTRuntimeSpriteDescStruct  { 

1  ong 

QTAtomID 
short 

Matri xRecord 
short 
short 

Modi f i erTrackGraphi cs Mode Record 
QTAtomID 

}; 

versi on 
Set  to  0. 
spri telD 

The  QT  atom  ID  of  the  sprite  atom, 
imagelndex 

The  index  of  the  sprite  image.  This  value  must  be  between  1  and  the  number  of 
available  images.  You  can  determine  how  many  images  are  available  by  calling 
Spri  teMedi  aCountlmages  (III — 1886). 
matri x 

A  Matri  xRecord  (IV-2304)  structure  that  defines  the  sprite's  matrix, 
vi  si  bl  e 

Undocumented 
1  ayer 

The  sprite's  layer  number, 
graphi csMode 

A  Modi  f  i  erT rackGraphi  csModeRecord  (IV-2311)  structure  that  defines  the 
graphics  mode  setting  for  the  sprite. 


versi on ; 
spritelD; 
imagelndex; 
matrix; 
vi  si  bl  e ; 

1 ayer ; 

graphi csMode ; 

acti on Hand! i ngSpri telD ; 
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QTSAtomContainerDataStruct 


actionHandlingSpritelD 

Undocumented 
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QTSAtomContainerDataStruct 

Undocumented 

struct  QTSAtomContainerDataStruct  { 
QTAtomContai ner  container: 

QTAtom  parentAtom; 

}; 

contai ner 

A  QT  atom  container. 
parentAtom 

The  container's  parent  atom. 
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QTSAudioParams 


Provides  audio  data  for  the  QTSMediaParams  (IV-2374)  structure, 
struct  QTSAudioParams  { 


SIntl6 

1 eftVol ume ; 

SIntl6 

ri ghtVol ume ; 

SIntl6 

bassLevel ; 

SIntl6 

trebl eLevel ; 

short 

frequencyBandsCount; 

voi  d  * 

f requencyBands ; 

Bool ean 

}; 

level  Me teringEnabled; 

1 eftVol ume 

The  playback  volume  for  the  left  channel,  where  0x0000  represents  no  volume 
and  0x0100  represents  full  volume. 
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QTSBandwidthAlertParams 


ri ghtVol ume 

The  playback  volume  for  the  right  channel,  where  0x0000  represents  no  volume 
and  0x0100  represents  full  volume. 
bassLevel 

Undocumented 
trebl eLevel 

Undocumented 
frequency Bands Count 
Undocumented 
f requencyBands 
Undocumented 
level Meteri ngEnabl ed 

TRUE  if  level  metering  is  enabled,  FALSE  otherwise. 
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QTSBandwidthAlertParams 

Undocumented 

struct  QTSBandwi 
1  ong 

TimeVal ue 
void  * 

}; 

fl  ags 

Undocumented 
restartAt 

Undocumented 
reserved 

Undocumented 


dthAl ertParams  { 
fl ags  ; 
restartAt; 
reserved ; 


Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


Inside  QuickTime:  Data  Structures 


IV-2365 


STR 


Data  Structures 


QTSBufferTimeAtom 


QTSBufferTimeAtom 

Undocumented 

struct  QTSBufferTimeAtom  { 

SInt32  versi onAndFl ags ; 

Fixed  bufferTime; 

}; 

versi onAndFl ags 
Undocumented 
bufferT i me 

Undocumented 
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QTSCanHandleSendDataTypeParams 


Provides  data  type  capability  information  to  the  QTSPresGetlnfo  (11-1272)  structure. 

struct  QTSCanHandleSendDataTypeParams  { 

SInt32  modifierTypeOrlnputlD; 

Boolean  i sModi f i erType ; 

Boolean  returnedCanHandleSendDataType; 

}; 

modifierTypeOrlnputlD 

A  modifier  type  or  input  ID. 
i sModi f i erType 

True  if  modi  f  i  erTypeOrlnputlD  is  a  modifier  type,  FALSE  if  it  is  an  input  ID. 
returnedCanHandleSendDataType 

The  called  component  sets  this  field  to  TRUE  if  it  can  handle  the  data  type. 

Programming  Info 

C  interface  file:  Qui  ckTi  meStreami  ng .  h 


QTScheduledBandwidthRecord 

Provides  information  to  the  QTSchedul  edBandwi  dthRequest  (11-1219)  function. 
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QTSClipRectAtom 


struct  QTSchedul edBandwi dthRecord  { 


1  ong 
1  ong 
1  ong 

CompTimeVal ue 
CompTimeVal ue 
T i meScal e 
T i meBase 


recordSi ze ; 
pri  ori  ty ; 
dataRate; 
startTime; 
durati on ; 
scale; 
base ; 


}; 


recordSi ze 

The  number  of  bytes  in  this  structure, 
pri ori ty 

Undocumented 

dataRate 

The  data  rate. 
startTime 

The  bandwidth  usage  start  time, 
durati on 

Duration  of  bandwidth  usage,  or  0  if  unknown, 
scale 

The  timescale  of  the  duration  field. 
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base 

The  time  base. 
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QTSClipRectAtom 

Undocumented 

struct  QTSClipRectAtom  { 

SInt32  versi onAndFl ags ; 

Rect  clipRect; 

}; 

versi onAndFl ags 
Undocumented 
cl i pRect 

A  Rect  (IV-2399)  structure  that  defines  a  clipping  rectangle. 
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Data  Structures 


QTSDataRateHistoryParams 
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QTSDataRateHistoryParams 


Provides  data  rate  history  information  to  the  QTSPresGetlnfo  (11-1272)  function. 

struct  QTSDataRateHistoryParams  { 

UInt32  changeSeed; 

UInt32  mi  1 1  i  seconds  Be tween  El ements ; 

UInt32  numberOf Interval s ; 

UInt32  *  elements: 

}; 

changeSeed 

This  value  changes  if  the  information  in  the  structure  changes, 
mi  1 1 i seconds  Be tween  El ements 
Undocumented 
numberOf Interval s 
Undocumented 
el ements 

Pointer  to  Undocumented  in  bits  per  second;  callee  allocates;  caller  must  dispose. 

Programming  Info 
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QTSDimensionParams 


Provides  source  dimension  information  to  the  QTSPresGetlnfo  (11-1272)  function. 

struct  QTSDimensionParams  { 

Fixed  width; 

Fixed  height; 

}; 

wi  dth 

The  width  in  pixels, 
hei ght 

The  height  in  pixels. 


IV-2368 
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QTSDirectConnectPrefsRecord 


Programming  Info 

C  interface  file:  Qui ckTi  meStreami  ng .  h 


QTSDirectConnectPrefsRecord 

Undocumented 

struct  QTSDirectConnectPrefsRecord  { 
UInt32  tcpPortID; 

OSType  protocol ; 

}; 

tcpPortID 

Undocumented 

protocol 

Undocumented 


STR 


Programming  Info 

C  interface  file:  Qui  ckTi  meStreami  ng .  h 


QTSDurationAtom 


Provides  duration  information  to  the  QTSPresGetlnfo  (11-1272)  function. 

struct  QTSDurationAtom  { 

SInt32  versi onAndFl ags ; 

TimeScale  timeScale; 

TimeValue64  duration; 

}; 

versi onAndFl ags 

Version  information  and  flags, 
ti meScal e 

The  time  scale, 
durati on 

The  duration. 


Programming  Info 
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Data  Structures 


QTSEditEntry 


QTSEditEntry 


Provides  data  to  the  QTSEdi  t Li  st  (IV-2370)  structure. 

struct  QTSEditEntry  { 

TimeValue64  presentationDuration; 

TimeVal ue64  streamStartTi me ; 

Fixed  streamRate; 

}; 

presentationDuration 

The  duration  of  the  presentation. 
streamStartTime 

Stream  starting  time. 
streamRate 

Streaming  rate. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSEditList 


Contains  an  array  of  QTSEditEntry  (IV-2370)  structures. 

struct  QTSEditList  { 

SInt32  numEdits; 

QTSEditEntry  edi ts[l] ; 

}; 

numEdi ts 

The  number  of  structures  in  the  edi  ts  field, 
edi  ts 

An  array  of  QTSEditEntry  (IV-2370)  structures. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 

See  Also 

See  QTSEditEntry  (IV-2370). 


IV-2370 
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QTSErrorParams 


QTSErrorParams 


Undocumented 

struct  QTSErrorParams  { 

const  char  *  errorstring; 
SInt32  flags; 


STR 


errorStri ng 

A  pointer  to  an  error  message, 
fl  ags 

Undocumented 


Programming  Info 

C  interface  file:  Qui  ckTi  meStreami  ng .  h 


QTSettingsVersionAtomRecord 


Format  of  the  '  vers '  atom  found  in  settings  atom  containers. 

struct  QTSettingsVersionAtomRecord  { 
long  componentVersi on ; 

short  flags; 

short  reserved; 

}; 

componentVersi on 

Standard  compression  component  version, 
fl  ags 

The  low  bit  is  1  if  the  platform  is  little-endian,  0  if  it  is  big-endian. 

reserved 

Reserved;  set  to  0. 


Programming  Info 

C  interface  file:  Qui  ckTi  meComponents  .  h 


QTSGetURLLinkRecord 


Holds  URL  information  for  QTSPresGetlnfo  (11-1272)  and  QTSPresSetlnfo  (11-1293). 
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Data  Structures 


QTSGraphicsModeParams 


struct  QTSGetURLLinkRecord  { 
Point  di spl ayWhere ; 

Handle  returnedURLLi nk ; 

}; 

di spl ayWhere 

Undocumented 
returnedURLLi nk 
Undocumented 


Programming  Info 
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QTSGraphicsModeParams 

Defines  a  source's  graphics  mode. 

struct  QTSGraphicsModeParams  { 

SIntl6  graphi csMode ; 

RGBColor  opColor; 

}; 

graphi csMode 

The  graphics  mode;  see  "Graphics  Transfer  Modes"  (IV-2670). 
opCol or 

The  color  for  use  in  addPi  n,  subPi  n,  bl  end,  and  transparent  operations,  as  an 
RGBColor  (IV-2403)  structure.  If  NIL,  the  source's  opcolor  is  left  unchanged. 

Programming  Info 
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QTSInfoParams 


Undocumented 

struct  QTSInfoParams  { 
OSType  infoType; 

void  *  infoParams; 

}; 


i nfoType 

Undocumented 


IV-2372 


Inside  QuickTime:  Data  Structures 


QTSLostPercentParams 


i nfoParams 

Undocumented 


Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSLostPercentParams 


Records  a  stream's  lost  data  percentage,  combined  with  the  existing  percentage,  for 
QTSPresGetlnfo  (11-1272)  and  QTSPresSetlnfo  (11-1293). 

struct  QTSLostPercentParams  { 

UInt32  recei vedPkts ; 

UInt32  lostPkts; 

Fixed  percent; 

1; 

recei vedPkts 

The  number  of  packets  received. 

1 ostPkts 

The  number  of  packets  lost, 
percent 

The  percent  of  packets  lost. 
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QTSMedialndSampleDescriptionParams 


Identifies  sample  data  for  QTSMedi  aGetlnfo  (11-1245),  QTSMedi  aSetlnfo  (11-1248), 
QTSMedi  aGetlndStreamlnfo  (11-1244),  and  QTSMedi  aSetlndStreamlnfo  (11-1246). 

struct  QTSMedialndSampl eDescri pti onParams  { 

SInt32  index; 

OSType  returnedMedi aType ; 

Sampi eDescri pti onHandl e  returnedSampl eDescri pti on ; 

}; 

i  ndex 

An  index  value  indicating  which  of  the  media's  data  references  contains  the 
sample  data  for  this  sample  description. 
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Data  Structures 


QTSMediaNotificationParams 


returnedMedi aType 

A  media  type;  see  "Data  References"  (IV-2661). 
returnedSampleDescription 

A  handle  to  a  Sampl  eDescri  pti  on  (IV-2414)  structure. 

Programming  Info 

C  interface  file:  QTSMovi e .  h 


QTSMediaNotificationParams 


Identifies  the  notification  process  for  QTSMedi  aGetlnfo  (11-1245),  QTSMedi  aSetlnfo 
(11-1248),  QTSMedi  aGetlndStreamlnfo  (11-1244),  and  QTSMedi  aSetlndStreamlnfo 
(11-1246). 

struct  QTSMediaNotificationParams  { 

QTSNotificationUPP  notificationProc; 
void  *  noti f i cati onRefCon ; 

SInt32  flags; 

}; 

noti f i cati onProc 

A  Universal  Procedure  Pointer  that  accesses  a  QTSNoti  ft  cati  onProc  (III— 2126) 
callback. 

noti f i cati onRefCon 

A  pointer  to  data  that  will  be  passed  to  the  callback, 
fl  ags 

Undocumented 


Programming  Info 

C  interface  file:  QTSMovi  e . h 


QTSMediaParams 


Combines  the  QTSVi deoParams  (IV-2389)  and  QTSAudi  oParams  (IV-2364)  structures. 

struct  QTSMediaParams  { 

QTSVi deoParams  v; 

QTSAudi oParams  a; 

}; 


IV-2374 
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QTSMediaPresentationParams 


v 

A  QTSVideoParams  (IV-2389)  structure, 
a 

A  QTSAudi oParams  (IV-2364)  structure. 

Programming  Info 
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QTSMediaPresentationParams 


Identifies  a  presentation  for  QTSMedi  aGetlnfo  (11-1245),  QTSMedi  aSetlnfo  (11-1248), 
QTSMedi  aGetlndStreamlnfo  (11-1244),  and  QTSMedi  aSetlndStreamlnfo  (11-1246). 

struct  QTSMediaPresentationParams  { 

QTSPresentation  presentationID; 

}; 

presentati onID 

A  pointer  to  a  QTSPresentation  Re  cord  (IV-2379)  structure. 

Programming  Info 
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QTSMediaStreamHeaderAtom 

Undocumented 

struct  QTSMediaStreamHeaderAtom  { 
SInt32  versi onAndFl ags ; 

OSType  medi aTransportType ; 

OSType  mediaTransportDataAID; 

}; 

versi onAndFl ags 
Undocumented 
medi aTransportType 
Undocumented 
medi aTransportDataAID 

The  data  for  this  structure. 


Programming  Info 
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Data  Structures 


QTSNameParams 


QTSNameParams 


Holds  a  presentation  or  stream  name  for  QTSPresGetlnfo  (11-1272). 

struct  QTSNameParams  { 

SInt32  maxNameLength ; 

SInt32  requestedLanguage ; 

SInt32  returnedActual Language ; 

unsigned  char  *  returnedName ; 

}; 

maxNameLength 

The  maximum  number  of  bytes  to  render  the  name. 
requestedLanguage 

The  requested  language  for  the  name;  see  "Localization  Codes"  (IV-2673). 
returnedActual Language 

On  return,  the  actual  language  used  for  the  name;  see  "Localization  Codes" 
(IV-2673). 

returnedName 

Pointer  to  a  Pascal  string  supplied  by  the  caller. 
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QTSNewPresDetectedParams 


Undocumented 

struct  QTSNewPresDetectedParams  { 
void  *  data; 

1: 

data 

Pointer  to  data. 


Programming  Info 
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QTSNewPresentationParams 


Specifies  a  presentation  for  QTSNewPresentati  on  (11-1250). 


IV-2376 
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QTSNewStreamParams 


struct  QTSNewPresentati 
OSType 

const  void  * 

UInt32 

QTSEdi t  Li stHandl e 
SInt32 
T i meScal e 
QTSMedi aParams  * 
QTSNoti  fi  cati  onllPP 
void  * 

}; 


Params  { 
dataType ; 
data  ; 

data  Length ; 

edi  t  Li st ; 

fl ags  ; 

ti meScal e ; 

medi aParams ; 

noti fi cati onProc ; 

noti fi cati onRefCon ; 


dataType 

Undocumented 

data 

Undocumented 
data  Length 

Undocumented 
edi  t Li  st 

A  handle  to  a  QTSEdi  t Li  st  (IV-2370)  structure, 
fl  ags 

Undocumented 
ti meScal e 

The  time  scale;  set  to  0  for  the  default  time  scale, 
medi aParams 

Undocumented 
noti fi cati onProc 

A  pointer  to  a  QTSNoti  f  i  cati  onProc  (III— 2126)  callback, 
noti fi cati onRefCon 

A  reference  constant  to  be  passed  to  the  QTSNoti  fi  cati  onProc  callback. 

Programming  Info 
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QTSNewStreamParams 


Undocumented 

struct  QTSNewStreamParams  { 
QTSStream  stream; 
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Data  Structures 


QTSNoProxyPref 


}; 

stream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure. 

Programming  Info 
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QTSNoProxyPref 

Provides  data  for  the  QTSPref  sGetNoProxyURLs  (11-1263)  function. 

struct  QTSNoProxyPref  { 

UInt32  flags; 

UInt32  seed; 

char  urlListfl]; 

}; 

fl  ags 

Undocumented 

seed 

A  seed  value  from  the  last  time  this  setting  was  read  from  the  system 
preferences, 
url  Li st 

A  null-terminated,  comma-delimited  list  of  URLs. 

Associated  Functions 

QTSPrefsGetNoProxyliRLs  (11-1263) 
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QTSPresentationHeaderAtom 


Undocumented 

struct  QTSPresentationHeaderAtom  { 
SInt32  versi onAndFl ags ; 

OSType  conductorOrDataType ; 

OSType  dataAtomType ; 

}; 


IV-2378 
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QTSPresentationRecord 


versi onAndFl ags 
Undocumented 
conduct orOrDataType 
Undocumented 
dataAtomType 

Where  the  data  is  actually  located. 
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QTSPresentationRecord 


Defines  a  presentation. 

struct  QTSPresentationRecord  { 
long  d  a  t  a [  1  ] ; 

}; 

data 

Array  of  data  that  constitutes  the  presentation. 

Programming  Info 
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QTSPresIdleParams 


Provides  parameters  for  QTSPresIdle  (11-1284). 


struct  QTSPresIdleParams  { 


QTSStream 
T i meVal ue64 
SInt32 
SInt32 


stream; 

movi eTimeToDi spl  ay; 
f 1 ags In  ; 
f 1 agsOut ; 


}; 


stream 

A  pointer  to  a  QTSStream  Re  cord  (IV-2387)  structure, 
movi eTi meToDi spl ay 
Undocumented 
fl agsln 

Undocumented 
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Data  Structures 


QTSpriteButtonBehaviorStruct 


f 1 agsOut 

Undocumented 

Associated  Functions 

QTSPresIdl e  (11-1284) 

Programming  Info 
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See  Also 

See  QTSPres Idle  (11-1284). 


QTSpriteButtonBehaviorStruct 

Contains  ID  information  for  four  sprite  state  atoms. 

struct  QTSpriteButtonBehaviorStruct  { 

QTAtomlD  notOverNotPressedStatelD; 

QTAtomlD  overNotPressedStatel D ; 

QTAtomlD  overPressedStatel D ; 

QTAtomlD  notOverPressedStatel D ; 

}; 

notOverNotPressedStatelD 

Undocumented 

overNotPressedStatelD 

Undocumented 

overPressedStatelD 

Undocumented 

notOverPressedStatelD 

Undocumented 

Programming  Info 

C  interface  file:  Movi  es .  h 


QTSProxyPref 

Provides  data  for  the  QTSPrefsFi ndProxyByType  (11-1260)  function. 

struct  QTSProxyPref  { 

UInt32  flags; 

SInt32  portID; 

UInt32  seed; 


IV-2380 
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QTSProxyPrefsRecord 


Str255  serverNameStr; 

}; 

fl  ags 

Undocumented 

portID 

ID  of  the  port  to  use  for  this  connection  type. 

seed 

A  seed  value  from  the  last  time  this  setting  was  read  from  the  system 
preferences. 
serverNameStr 

A  proxy  server  URL. 

Associated  Functions 

QTSPrefsFi ndProxyByType  (11-1260) 

Programming  Info 
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QTSProxyPrefsRecord 

Undocumented 

struct  QTSProxyPrefsRecord  { 

Str255  serverNameStr; 

UInt32  portID; 

}; 

serverNameStr 

A  proxy  server  URL. 
portID 

ID  of  the  port  to  use  for  this  connection  type. 

Programming  Info 
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QTSSampleDescription 

Undocumented 

struct  QTSSampleDescription  { 
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Data  Structures 


QTS  StatHelperN  extParams 


1  ong 

descSi ze ; 

1  ong 

dataFormat ; 

1  ong 

resvdl ; 

short 

resvd2 ; 

short 

dataRef Index 

UInt32 

versi on ; 

UInt32 

resvd3 ; 

SInt32 

fl ags  ; 

descSi ze 

Undocumented 

dataFormat 

Undocumented 

resvdl 

Reserved;  set  to  0. 
resvd2 

Reserved;  set  to  0. 
dataRef Index 

Undocumented 

verst  on 

Undocumented 

resvd3 

Reserved  set  to  0. 
fl  ags 

Undocumented 


Programming  Info 
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QTSStatHelperNextParams 


Holds  information  about  the  next  streaming  statistic  obtained  byQTSStatHelperNext 
(11-1311). 


struct  QTSStatHelperNextParams  { 

SInt32  flags; 

OSType  returnedStati sti csType ; 

QTSStream  returnedStream ; 

UInt32  maxStatNameLength ; 

char  *  returnedStatName ; 

UInt32  maxStatStri ngLength ; 


IV-2382 
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QTS  StatHelperN  extParams 


char  *  returnedStatStri ng ; 

UInt32  maxStatUni tLength ; 

char  *  returnedStatUni t ; 


fl  ags 

Undocumented 
returnedStati sti csType 
Undocumented 
returnedStream 

On  return,  a  pointer  to  a  QTSStreamRecord  (IV-2387)  structure. 
maxStatName Length 
Undocumented 
returnedStatName 

Undocumented ;  pass  N I L  if  you  don't  want  this  information. 
maxStatStri ngLength 
Undocumented 
returnedStatStri  ng 

Undocumented ;  pass  N I L  if  you  don't  want  this  information. 
maxStatUni tLength 
Undocumented 
returnedStatUni t 

Undocumented ;  pass  N I L  if  you  don't  want  this  information. 

flags  Constants 

kQTSStatHel per Return  Pa  seal  Stri  ngs  Fl  ag 
Undocumented 


Discussion 

When  you  call  QTSStatHel  perNext  (11-1311),  specifying  a  statistic  helper  and  the 
address  of  this  structure,  QuickTime  fills  in  this  structure  with  information  about 
the  next  statistic  obtained  by  the  statistic  helper. 

Associated  Functions 

QTSStatHel  perNext  (11-1311) 

Programming  Info 
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STR 
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Data  Structures 


QTSStatHelperRecord 


QTSStatHelperRecord 


Defines  the  component  instance  of  a  statistics  helper. 

struct  QTSStatHelperRecord  { 
long  data [ 1 ] ; 

}; 

data 

The  component  instance  of  the  statistics  helper. 

Programming  Info 
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QTSStatisticsParams 


Defines  stream  statistics  for  the  QTSPresGetlnfo  (11-1272)  function. 


struct  QTSStatisticsParams  { 

OSType  stati sti csType ; 

QTAtomContai ner  container: 

QTAtom  parentAtom; 

SInt32  flags; 

}; 


stati sti csType 

A  constant  (see  below)  that  defines  the  type  of  statistics, 
contai ner 

A  QT  atom  container. 
parentAtom 

The  parent  atom  of  the  container  parameter, 
fl  ags 

Undocumented 

statisticsType  Constants 

kQTSAl 1 Stati sti csType 

A  full  statistics  helper  for  all  statistics;  constant  value  is  'all 
kQTSShortStati sti csType 

A  short  statistics  helper;  constant  value  is  '  s h rt ' . 
kQTSSummary Stati sti csType 

A  summary  statistics  helper;  constant  value  is  '  s  umm ' . 


IV-2384 
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QTS  StatusParams 


Programming  Info 
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QTSStatusParams 


Undocumented 

struct  QTSStatusParams  { 

UInt32  status; 

const  char  *  statusstring; 

UInt32  detai 1 edStatus ; 

const  char  *  detai 1 edStatusStri ng  ; 

}; 

status 

Undocumented 

statusStri ng 

Undocumented 
detai 1 edStatus 
Undocumented 
detai 1 edStatusStri ng 
Undocumented 


STR 
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QTSStreamBuffer 


Defines  a  stream  buffer  for  QuickTime  streaming. 


struct  QTSStreamBuffer  { 

struct  QTSStreamBuffer  * 
struct  QTSStreamBuffer  * 
struct  QTSStreamBuffer  * 
unsigned  char  * 
unsigned  char  * 

1  ong 

UInt32 

SInt32 

}; 


reservedl ; 
reserved2 ; 
next ; 
rptr ; 
wptr ; 

reserved3 ; 
metadata  [4] ; 
fl ags  ; 
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Data  Structures 


QTSStreamChangedParams 


reservedl 

Reserved;  do  not  use. 
reserved2 

Reserved;  do  not  use. 

next 

A  pointer  to  the  next  message  block  in  a  message. 

rptr 

A  pointer  to  the  first  byte  in  the  data  buffer  that  contains  real  data. 

wptr 

A  pointer  to  the  byte  after  the  last  byte  in  the  data  buffer  that  contains  real  data. 
reserved3 

Reserved;  do  not  use. 
metadata 

Usage  defined  by  message  sender, 
fl  ags 

Reserved;  do  not  use. 

Associated  Functions 

QTSCopyMessage  (11-1220) 

Programming  Info 
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QTSStreamChangedParams 


Undocumented 

struct  QTSStreamChangedParams  { 

QTSStream  stream: 

Component  Instance  medi a Component ; 

1: 

stream 

A  pointer  to  a  QTSStreamRecord  (IV-2387)  structure, 
medi aComponent 

Undocumented ;  could  be  NI L. 
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QTSStreamGoneParams 


QTSStreamGoneParams 


Undocumented 

struct  QTSStreamGoneParams  { 
QTSStream  stream; 

}; 


STR 


stream 

A  pointer  to  a  QTSStream  Re  cord  (IV-2387)  structure. 

Programming  Info 
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QTSStreamRecord 


Contains  a  stream  for  QuickTime  streaming. 

struct  QTSStreamRecord  { 
long  data [ 1 ] ; 

}; 

data 

An  array  of  data  representing  the  stream. 

Programming  Info 
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QTStatusStringRecord 


Passes  status  information  to  an  MCActi  onFi  1  terProc  (III— 2096)  callback. 

struct  QTStatusStringRecord  { 
long  stri  ngTypeFl  ags  ; 
char  *  statusstring; 

}; 

stri  ngTypeFl  ags 

Flags  (see  below)  that  define  the  string  type. 
statusStri ng 

A  pointer  to  the  status  string. 
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QTSTransportPref 


stringTypeFlags  Constants 

kStatusStringlslIRLLink 
The  string  is  a  URL. 
kStatusStringlsStreamingStatus 
Undocumented 
kStatusHasCodeNumber 

The  high  16  bits  is  an  error  code  number. 
kStatusIsError 
Undocumented 

Programming  Info 

C  interface  file:  Movi  es .  h 


QTST  ransportPref 


Records  streaming  transport  preferences. 

struct  QTSTransportPref  { 

OSType  protocol  ; 

SInt32  portID; 

UInt32  flags; 

UInt32  seed; 

}; 

protocol 

Constant  that  identifies  the  streaming  transport  protocol;  see  "Streaming 
Transport  Atoms"  (IV-2695). 
portID 

ID  of  the  port  to  use  for  this  connection  type, 
fl  ags 

Connection  flags  (see  below). 

seed 

A  seed  value  from  the  last  time  this  setting  was  read  from  the  system 
preferences. 

flags  Constants 

kConnecti onActi ve 

The  connection  is  active. 
kConnecti  onllseSy st emPref 

Use  the  system  preferences. 


IV-2388 
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QTSURLParams 


Associated  Functions 

QTSPrefsFi  ndConnecti  onByType  (11-1259) 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSURLParams 

Undocumented 

struct  QTSURLParams  { 

UInt32  urlLength; 

const  char  *  url  ; 

}; 

url  Length 

The  length  of  the  URL. 
url 

Pointer  to  a  URL. 


STR 


Programming  Info 

C  interface  file:  Qui  ckTi meStreami  ng .  h 


QTSVideoParams 


Provides  video  parameter  data  for  the  QTSMedi  a  Pa  rams  (IV-2374)  structure. 


struct  QTSVideoParams  { 


Fi  xed 
Fi  xed 

Matri xRecord 
CGraf Ptr 
GDHandl e 
RgnHandl e 
short 
RGBCol or 


wi  dth ; 
hei ght ; 
matrix; 
gWorl  d ; 
gdHandl e ; 
clip; 

graphi csMode ; 
opCol or ; 


wi  dth 

The  image  width  in  pixels, 
hei ght 

The  image  height  in  pixels. 
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QTSVolumesParams 


matri x 

A  Matri  xRecord  (IV-2304)  structure  representing  the  video  matrix. 
gWorl  d 

A  pointer  to  the  CGraf  Port  (IV-2168)  structure  for  the  video. 
gdHandl e 

A  handle  to  the  GDevi  ce  (IV-2264)  structure  for  the  video. 

cl  i  p 

A  handle  to  MacRegi  on  (IV-2303)  structure  that  defines  the  video  clipping 
region, 
graphi csMode 

The  video's  graphics  mode;  see  "Graphics  Transfer  Modes"  (IV-2670). 
opCol or 

An  RGBCol  or  (IV-2403)  structure  that  defines  the  color  for  use  in  add  Pi  n,  sub  Pi  n, 
blend,  and  transparent  operations.  If  NIL,  the  source's  opcolor  is  left 
unchanged. 

Programming  Info 

C  interface  file:  Qui  ckTimeStreami  ng .  h 


QTSVolumesParams 

Stores  source  sound  volumes  for  streaming. 

struct  QTSVolumesParams  { 

SIntl6  leftVolume; 

SIntl6  rightVolume; 

1: 

1 eftVol ume 

The  playback  volume  for  the  left  channel,  where  0x0000  represents  no  volume 
and  0x0100  represents  full  volume, 
ri ghtVol ume 

The  playback  volume  for  the  right  channel,  where  0x0000  represents  no  volume 
and  0x0100  represents  full  volume. 

Programming  Info 

C  interface  file:  Qui  ckT i meStreami  ng .  h 


IV-2390 


Inside  QuickTime:  Data  Structures 


QTSyncTaskRecord 


QTSyncT  askRecord 


Undocumented 

struct  QTSyncTaskRecord  { 
void  *  qLink; 

QTSyncTaskUPP  proc; 

}; 

q  Li  nk 

Undocumented 

proc 

A  Universal  Procedure  Pointer  that  accesses  a  QTSyncTaskProc  (III— 2127) 
callback. 


Programming  Info 

C  interface  file:  Movi  es  .  h 


QTT  argetDataSize 

Contains  a  setting  for  a  '  dasz '  (IV-2527)  atom. 

struct  QTTargetDataSize  { 

unsigned  long  targetDataSize; 

}; 

targetDataSi ze 

The  target  data  size  setting. 

Discussion 

The  JPEG  graphics  exporter  supports  the  target  data  size  setting,  which  is 
implemented  by  compressing  the  image  repeatedly,  lowering  the  quality  until  the 
target  size  (or  a  maximum  attempt  limit)  is  reached. 

Programming  Info 

C  interface  file:  ImageCompressi  on .  h 

See  Also 

Seethe  'dasz'  (IV-2527)  atom. 


QTT  weenerRecord 

Stores  a  tween  for  the  QTNewTween  (11-1209)  function. 


STR 
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QTVRAreaOflnterest 


struct  QTTweenerRecord  { 
long  da  ta [ 1 ] ; 

}; 

data 

An  array  of  data  that  constitutes  a  tween. 

Programming  Info 

C  interface  file:  Movi  es .  h 


QTVRAreaOflnterest 


Contains  information  passed  to  QTVRSetBackBufferlmagingProc  (11-1411). 
struct  QTVRAreaOflnterest  { 


f  1  oat 

panAngl e ; 

f  1  oat 

ti  1 tAngl e 

f  1  oat 

wi dth ; 

f  1  oat 

height; 

UInt32 

fl ags  ; 

1: 

panAngl e 

The  pan  angle  of  the  upper-left  coordinate  (in  panorama  space)  of  the  area  of 
interest, 
ti 1 tAngl e 

The  tilt  angle  of  the  upper-left  coordinate  (in  panorama  space)  of  the  area  of 
interest. 

wi  dth 

The  width  of  the  area  of  interest, 
hei ght 

The  height  of  the  area  of  interest, 
fl  ags 

A  set  of  bit  flags  (see  below)  that  indicate  when  to  call  the  back  buffer  imaging 
procedure  for  this  area  of  interest. 

flags  Constants 

kQTVRBackBufferEveryUpdate 

If  this  bit  is  set,  the  back  buffer  imaging  procedure  is  to  be  called  whenever 
QuickTime  is  about  to  update  the  window  containing  the  specified  QuickTime 
VR  movie  instance.  That  is,  the  procedure  is  called  just  before  QuickTime 


IV-2392 
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QTVRCubicFaceData 


unwarps  the  back  buffer  image  into  the  prescreen  buffer  and  redraws  the 
screen  image. 

kQTVRBackBuf fer Every Idl e 

If  this  bit  is  set,  the  back  buffer  imaging  procedure  is  to  be  called  when  either 
MCIsPl  ayerEvent  (11-819)  is  called  with  the  i  dl  e  parameter,  or  when  MCIdl  e 
(11-816)  is  called.  Its  purpose  is  to  cause  the  software  to  draw  as  often  as 
possible. 

kQTVRBackBuf ferAl ways  Refresh 

If  this  bit  is  set,  the  back  buffer  is  always  refreshed  to  the  proper  movie  data  just 
before  your  back  buffer  imaging  procedure  is  called.  If  your  back  buffer 
imaging  procedure  completely  overwrites  the  rectangle  passed  to  it,  you 
should  not  set  this  bit. 

Discussion 

The  a  reasOf  Interest  parameter  to  QTVRSetBackBuf ferlmagi  ngProc  (11-1411)  specifies 
an  array  ofQTVRAreaOflnterest  structures,  each  one  of  which  indicates  a  rectangular 
area  in  the  QTVR  back  buffer. 

Associated  Functions 

QTVRSetBackBuf  ferlmagi  ngProc  (11-1411) 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

See  Also 

See  QTVRSetBackBuf  ferlmagi  ngProc  (11-1411). 


STR 


QTVRCubicFaceData 


Non-standard  cubic  panorama  data  for  a  '  cuf  a  '  (IV-2525)  atom, 
struct  QTVRCubicFaceData  { 


f  1  oat 

ori entati on[4] 

f  1  oat 

center[2] ; 

ft  oat 

aspect ; 

ft  oat 

skew; 

}; 

ori entati on 

Undocumented. 

center 

Undocumented. 
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QTVRCubicViewAtom 


aspect 

Undocumented. 

skew 

Undocumented. 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

See  Also 

See  'cufa'  (IV-2525). 


QTVRCubicViewAtom 


Cubic  view  data  for  a  '  cuvw'  (IV-2526)  atom, 
struct  QTVRCubicViewAtom  { 


FI  oat32 

mi nPan ; 

FI  oat32 

maxPan ; 

FI  oat32 

mi nTi 1 1 ; 

FI  oat32 

maxT i 1 t ; 

FI  oat32 

minFieldOfView; 

FI  oat32 

maxFi el dOfVi ew ; 

FI  oat32 

defaul tPan ; 

FI  oat32 

defaul tTi 1 t ; 

FI  oat32 

}; 

defaul t  F i el dOfVi ew 

mi nPan 

Undocumented 


maxPan 

Undocumented 
mi nTi 1 t 

Undocumented 
maxT  i  1 1 

Undocumented 
mi nFi el dOfVi ew 
Undocumented 
maxFi el dOfVi ew 
Undocumented 
defaul tPan 

Undocumented 
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defaul tTi  1 1 

Undocumented 
defaul t  Fi el dOf View 
Undocumented 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

See  Also 

See  '  cuvw '  (IV-2526). 


STR 


QTVRCursorRecord 

Contains  information  passed  to  QTVRRepl  aceCursor  (11-1407). 

struct  QTVRCursorRecord  { 

UIntl6  theType; 

SIntl6  rsrcID; 

Handle  handle; 

}; 

theType 

A  constant  (see  below)  that  defines  the  type  of  cursor  to  replace. 
rsrcID 

The  resource  ID  of  the  cursor  to  replace;  see  "QTVR  Cursors"  (IV-2688). 
handl e 

A  handle  to  the  cursor  data  that  is  to  replace  the  specified  cursor.  If  theType  is 
kQTVRUseDef aul  tCursor,  then  this  field  should  contain  NIL. 

theType  Constants 

kQTVRUseDef aul  tCursor 

Restore  the  default  cursor.  In  this  case,  the  handle  field  of  the  cursor  record 
should  contain  NIL. 

kQTVRStdCursorType 

The  cursor  is  a  standard  black-and-white  cursor. 
kQTVRCol orCursorType 

The  cursor  is  a  color  cursor. 

Discussion 

The  cursRecord  parameter  to  QTVRRepl  aceCursor  (11-1407)  specifies  a 
QTVRCursorRecord  structure,  which  indicates  the  cursor  to  replace  and  its 
replacement  cursor. 
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QTVRFloatPoint 


Version  Notes 

In  earlier  versions  of  QuickTime,  theType  was  called  the  type  field. 

Associated  Functions 

QTVRRepl  aceCursor  (11-1407) 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

See  Also 

See  QTVRRepl  aceCursor  (11-1407). 


QTVRFloatPoint 

Specifies  a  point  in  a  QTVR  panorama  or  object. 

struct  QTVRFloatPoint  { 
float  x; 

float  y; 

1: 

x 

The  horizontal  coordinate  of  the  point. 

y 

The  vertical  coordinate  of  the  point. 

Associated  Functions 

QTVRAngl  esToCoord  (11-1334) 

Programming  Info 

C  interface  file:  QuickTimeVR.h 


QTVRInterceptRecord 


Contains  information  about  a  QTVRInterceptProc  (III— 2130)  being  intercepted  by 
QTVR. 

struct  QTVRInterceptRecord  { 


SInt32 

reservedl ; 

SInt32 

sel ector ; 

SInt32 

reserved2 ; 

SInt32 

reserved3 ; 

SInt32 

paramCount ; 

void  * 

parameter[6] 

}; 
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reservedl 

Reserved;  do  not  use. 
sel ector 

A  constant  that  indicates  which  routine  has  triggered  your  intercept  procedure 
(see  below). 
reserved2 

Reserved;  do  not  use. 
reserved3 

Reserved;  do  not  use. 
paramCount 

The  number  of  items  in  the  parameter  field, 
parameter 

An  array  that  holds,  in  order,  the  parameters  that  were  passed  to  the 
intercepted  function,  minus  the  QTVR  instance  parameter.  For  example,  if  you 
intercept  the  QTVRSetPanAngl  e  function,  the  parameter  field  contains  a  single 
item,  a  pointer  to  a  floating-point  value  that  is  the  new  pan  angle.  You  can 
determine  how  many  items  the  parameter  field  contains  by  inspecting  the 
paramCount  field. 

selector  Constants 

kQTVRSetPanAngl  eSel  ector 
Value  is  0x2000. 
kQTVRSetT i 1 tAngl  eSel  ector 
Value  is  0x2000. 
kQTVRSetFi el dOfVi ewSel  ector 
Value  is  0x2002. 
kQTVRSetVi ewCenterSel  ector 
Value  is  0x2003. 
kQTVRMouseEnterSel  ector 
Value  is  0x2004. 
kQTVRMouseWi thi  nSel  ector 
Value  is  0x2005. 
kQTVRMouseLeaveSel  ector 
Value  is  0x2006. 
kQTVRMouseDownSel ector 
Value  is  0x2007. 


STR 
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QTVRPanoImagingAtom 


kQTVRMouseSti 1 1 DownSel  ector 
Value  is  0x2008. 
kQTVRMousellpSel  ector 
Value  is  0x2009. 
kQTVRTri ggerHotSpotSel  ector 
Value  is  0x200A. 
kQTVRGetHotSpotTypeSel  ector 
Value  is  0x200B. 

Associated  Functions 

QTVRCal  1  InterceptedProc  (11-1336) 

Programming  Info 

C  interface  file:  QuickTimeVR.h 

See  Also 

See  QTVRInterceptProc  (III — 2130). 


QTVRPanoImagingAtom 


Provides  panorama  imaging  data  for  an  '  i  mpn '  atom, 
struct  QTVRPanoImagingAtom  { 


UIntl6 

majorVersi on ; 

UIntl6 

mi norVersi  on ; 

UInt32 

i magi ngMode ; 

UInt32 

i magi ngVal i d FI ags  ; 

UInt32 

correcti on ; 

UInt32 

qual i ty ; 

UInt32 

di rectDraw ; 

UInt32 

imagingProperties[6] 

UInt32 

reservedl ; 

UInt32 

reserved2 ; 

majorVersi on 

Undocumented. 
majorVersi on 

Undocumented. 
i magi ngMode 

Undocumented. 
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i magi ngVal i dFl ags 
Undocumented. 
correct! on 

Undocumented. 

quality 

Undocumented. 
di rectDraw 

Undocumented. 
i magi ngProperti  es 

Reserved  for  future  properties, 
reserved!. 

Reserved;  do  not  use. 
reserved2 

Reserved;  do  not  use. 

Programming  Info 

C  interface  file:  Qui  ckTi  meVRFormat .  h 

See  Also 

See  the  '  i  mpn '  (IV-2551)  atom. 


STR 


Rect 


Defines  the  size  and  location  of  a  QuickDraw  rectangle. 

struct  Rect  { 

short  top; 

short  left; 

short  bottom; 

short  right; 

}; 

top 

The  vertical  coordinate  of  the  upper-left  point  of  the  rectangle. 

1  eft 

The  horizontal  coordinate  of  the  upper-left  point  of  the  rectangle, 
bottom 

The  vertical  coordinate  of  the  lower-right  point  of  the  rectangle. 
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ReferenceMovieDataRefRecord 


ri  ght 

The  horizontal  coordinate  of  the  lower-right  point  of  the  rectangle. 

Programming  Info 

C  interface  file:  Quickdraw.h 


See  Also 

See  Inside  Macintosh:  Imaging  With  QidckDrazv  (listed  in  the  bibliography). 


ReferenceMovieDataRefRecord 


Provides  a  reference  to  an  alternate  movie  selected  by  a  '  rmda '  (IV-2577)  atom. 

struct  ReferenceMovieDataRefRecord  { 
long  flags; 

OSType  dataRefType; 

long  dataRefSize; 

char  dataRef[l]; 

}; 

fl  ags 

If  set  to  0,  the  data  for  the  '  rmda '  atom  is  imported  by  reference  and  the 
dataRefType,  dataRefSi  ze,  and  dataRef  fields  are  significant.  If  set  to 
kDataRef  IsSel  fContai ned  (see  below),  the  alternate  movie  is  self-contained. 
dataRefType 

The  type  of  dataRef;  see  "Data  References"  (IV-2661). 
dataRefSi ze 

The  size  mbytes  of  dataRef. 
dataRef 

The  data  reference.  It  is  typically  an  A1  i  asHandl  e  or  a  URL  (formatted  as  a  C 
string). 

flags  Constants 

kDataReflsSel fContai  ned 

The  reference  movie  for  the  '  rmda '  atom  is  self-contained. 


Discussion 

This  structure  contains  the  data  for  a  '  rmda  '  (IV-2577)  atom. 

Programming  Info 

C  interface  file:  MoviesFormat.h 

See  Also 

See  'rmda'  (IV-2577). 
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RegisteredComponentlnstanceRecord 

Undocumented 

struct  Regi steredComponentlnstanceRecord  { 
long  data [  1  ] ; 

}; 


STR 


data 

An  array  of  data. 

Programming  Info 

C  interface  file:  Components .  h 


RegisteredComponentRecord 


Undocumented 

struct  RegisteredComponentRecord  { 
long  data [ 1 ] ; 

}; 

data 

An  array  of  data. 

Programming  Info 

C  interface  file:  Components  .  h 


ResolvedQTEventSpec 

Passes  data  to  an  MCActi onFi  1  terProc  (III— 2096)  callback,  when  the  action 
mcActi  onExecuteAl  1  Acti  onsForQTEvent  is  executed. 

struct  ResolvedQTEventSpec  { 

QTAtomSpec  actionAtom; 

Track  targetTrack; 

long  targetRefCon ; 

}; 

acti onAtom 

The  atom  being  executed. 
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targetTrack 

The  affected  track. 
targetRefCon 

A  target  ID.  For  VR  actions,  it's  the  ID  of  the  hot  spot  (if  any)  that  triggered  the 
event.  For  sprite  tracks,  it's  the  sprite  ID  of  the  sprite  (if  any)  that  triggered  the 
event. 


Programming  Info 

C  interface  file:  Movi  es .  h 


ResourceSpec 

Describes  the  resource  type  and  resource  ID  of  a  component's  code,  name, 
information  string,  or  icon. 

struct  ResourceSpec  { 

OSType  resType; 

short  resID; 

I: 

resType 

A  4-byte  code  (see  below)  that  defines  the  resource  type. 
resID 

The  ID  of  the  specific  resource. 

resType  Constants 

'CODE' 

A  code  resource. 

'ICON' 

An  icon  resource. 

'STR  ' 

A  name  or  information  string  resource. 

Programming  Info 

C  interface  file:  Components .  h 

See  Also 

See  the  "Component  Manager"  chapter  of  Inside  Macintosh:  More  Macintosh  Toolbox 

(listed  in  the  bibliography). 
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RGBColor 

Defines  a  color  in  the  red-green-blue  system. 

struct  RGBColor  { 

unsigned  short  red; 

unsigned  short  green; 

unsigned  short  blue; 

}; 

red 

The  magnitude  of  the  red  component 
green 

The  magnitude  of  the  green  component 

bl  ue 

The  magnitude  of  the  blue  component 

Associated  Functions 

Graphi cs ImportGetGraphi csMode  (1-635) 

Programming  Info 

C  interface  file:  Quickdraw.h 


STR 


RGBRangeRecord 


Defines  a  range  of  RGB  colors. 

struct  RGBRangeRecord  { 
RGBColor  minColor; 

RGBColor  maxColor; 

}; 

mi nCol or 

One  end  of  the  range. 
maxCol or 

The  other  end  of  the  range. 

Programming  Info 

C  interface  file:  ImageCodec.h 


Inside  QuickTime:  Data  Structures 


IV-2403 


Data  Structures 


RoutineDescriptor 


RoutineDescriptor 


Used  by  the  Mac  OS  Mixed  Mode  manager  to  execute  a  routine. 


struct  RoutineDescriptor  { 

UIntl6  goMi xedModeTrap ; 

SInt8  version; 


RDF1 agsType 

UInt32 

UInt8 

UInt8 

UIntl6 


routineDescriptorFlags; 
reservedl ; 
reserved2 ; 
sel ectorlnfo ; 
routi neCount ; 


Routi neRecord 

}; 


routi neRecords[l]  ; 


goMi xedModeT  rap 

Contains  OxAAFE,  a  trap  instruction  that  tells  the  68LC040  emulator  to  transfer 
control  to  the  Mixed  Mode  Manager, 
versi on 

The  version  number  of  this  structure,  currently  kRouti  neDescri  ptorVersi  on 
(value  =  7). 

routi neDescri pt or  FI  a gs 

Constants  (see  below)  that  specify  whether  or  not  the  routine  selectors  are 
indexable. 

reservedl 

Reserved;  set  to  0. 
reserved2 

Reserved;  set  to  0. 
sel ectorlnfo 

Reserved;  set  to  0. 
routi neCount 

The  index  of  the  final  routine  record  inroutineRecords.lt  the  routine  descriptor 
describes  a  single  procedure,  set  this  field  to  0.  If  it  contains  pointers  to  both 
680x0  and  PowerPC  code,  set  it  to  1. 
routi neRecords 

A  zero-based  array  of  Routi  neRecord  (IV-2405)  structures. 

routineDescriptorFlags  Constants 

kSel ectorsAreNotlndexabl e 

For  dispatched  routines,  the  recognized  routine  selectors  are  not  contiguous. 
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kSel  ect orsAre Index able 

For  dispatched  routines,  the  recognized  routine  selectors  are  contiguous  and 
therefore  indexable. 


Programming  Info 

C  interface  file:  Mi  xedMode .  h 


STR 


See  Routi  neRecord  (IV-2405).  For  information  about  the  Mixed  Mode  Manager,  see 
Inside  Macintosh:  PowerPC  System  Softzvare  (listed  in  the  bibliography). 


RoutineRecord 


Contains  information  about  a  particular  routine  in  the  Mac  OS  Mixed  Mode 
Manager. 

struct  RoutineRecord 
ProcInfoType 
SInt8 
ISAType 

Routi neFl agsType 
ProcPtr 
UInt32 
UInt32 

}; 

proclnfo 

A  constant  that  defines  the  routine's  calling  conventions  and  parameters.  This 
constant  is  controlled  by  the  Mixed  Mode  Manager;  for  information  about  its 
structure,  see  Inside  Macintosh:  PozverPC  System  Softzvare  (listed  in  the 
bibliography), 
reservedl 

Reserved;  set  to  0. 

ISA 

A  constant  (see  below)  that  defines  the  instruction  set. 
routi neFl ags 

A  constant  (see  below)  that  specifies  information  about  the  routine,  or  0x00  if  all 
characteristics  are  normal. 
procDescri ptor 

A  pointer  to  the  routine's  code. 


proclnfo; 
reservedl ; 

ISA; 

routi neFl ags ; 
procDescri ptor ; 
reserved2 ; 
sel ector ; 
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RoutineRecord 


reserved2 

Reserved;  set  to  0. 
sel ector 

Reserved;  set  to  0.  For  routines  that  are  dispatched,  this  field  contains  the 
routine  selector. 

ISA  Constants 

kM68kISA 

The  routine  consists  of  680x0  code. 
kPowerPCISA 

The  routine  consists  of  PowerPC  code. 

routineFlags  Constants 

kProcDescriptorls Relative 

The  address  of  the  routine's  entry  point  specified  in  the  procDescriptor  field  is 
relative  to  the  beginning  of  the  Routi  neDescri  ptor  (IV-2404)  structure. 
Otherwise  it  is  an  absolute  address.  Value  is  0x01. 

kFragment Needs Prepari ng 

The  fragment  containing  the  code  to  be  executed  needs  to  be  loaded  into 
memory  and  prepared  by  the  Code  Fragment  Manager;  otherwise  it  is  already 
loaded  and  prepared.  If  this  flag  is  set,  the  kPowerPCISA  and 
kProcDescri  ptor  Is  Relative  flags  should  be  set.  Value  is  0x02. 
kUseNati velSA 

Use  the  native  instruction  set  architecture  instead  of  the  current  one.  Value  is 
0x04. 

kDontPassSel ector 

Do  not  pass  the  routine  selector  to  the  target  routine  as  a  parameter.  You  should 
not  set  this  flag  with  680x0  routines.  Value  is  0x08. 

kRoutinelsDispatched Default Routine 

This  routine  is  the  default  routine  for  a  set  of  routines  that  is  dispatched  using 
a  routine  selector.  Value  is  0x10. 
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C  interface  file:  Mi  xedMode .  h 

See  Also 

See  Routi  neDescri  ptor  (IV-2404).  For  information  about  the  Mixed  Mode  Manager, 
see  Inside  Macintosh:  PowerPC  System  Software  (listed  in  the  bibliography). 
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RTPMPPayloadT  ypeParams 

Describes  a  streaming  payload. 

struct  RTPMPPayloadTypeParams  { 

UInt32  flags; 

UInt32  payl oadNumber ; 

short  nameLength; 

char  *  payloadName; 

}; 

fl  ags 

Flags  (see  below)  that  tell  whether  the  payload  is  static  or  dynamic.  If  this  field 
is  kRTPMPPayl  oadTypeStati  cFl  ag,  then  the  payl  oadNumber  field  contains  the  RTP 
payload  number;  if  this  field  is  kRTPMPPayl  oadTypeDynami  cFl  ag,  then  the 
payl  oadName  field  contains  the  name  of  the  dynamic  payload  encoding  being 
used. 

payl oadNumber 

The  RTP  payload  number. 
nameLength 

Enter  the  size  of  the  payl  oadName  buffer,  counting  a  null  terminator.  If  the  size 
is  too  small,  QuickTime  will  return  the  needed  length  in  this  field  and  will 
return  paramErrin  the  calling  function, 
payl oadName 

Pointer  to  the  name  of  the  dynamic  payload  encoding  being  used. 

flags  Constants 

kRTPMPPayl oadTypeStati  cFl  ag 

Static  payload.  Value  is  0x00000001. 
kRTPMPPayl oadTypeDynami  cFl  ag 

Dynamic  payload.  Value  is  0x00000002. 

Programming  Info 
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RTPMPSampleDataParams 

Holds  media  packetizer  sample  data,  including  any  number  of  samples  or  a  partial 
sample. 

struct  RTPMPSampleDataParams  { 

UInt32  version; 
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RTPMPSampleDataParams 


UInt32 

UInt32 

UInt32 

Fi  xed 

SInt32 

UInt32 

Handl e 

RTPMPSampl eRef 
UInt32 

const  UInt8  * 
RTPMPDataReleaseUPP 
voi  d  * 

}; 


timeStamp ; 
durati on ; 
pi ayOffset ; 
pi ayRate ; 
fl ags  ; 

sampl eDescSeed ; 
sampl eDescri pti on  ; 
sampl eRef ; 
dataLength ; 
data  ; 

rel easeProc ; 
refCon ; 


versi on 

Version  of  the  data  structure.  Currently  always  0. 
timeStamp 

RTP  time  stamp  for  the  presentation  of  the  sample  data.  This  time  stamp  has 
already  been  adjusted  by  edits,  edit  rates,  etc. 
durati on 

Duration  (in  RTP  time  scale)  of  the  sample.  For  unknown  duration,  enter  0. 
pi ayOffset 

Offset  within  the  media  sample  itself.  This  is  only  used  for  media  formats 
where  a  single  media  sample  can  span  across  multiple  time  units.  QuickTime 
Music  is  an  example  of  this,  where  a  single  sample  spans  the  entire  track.  For 
most  video  and  audio  formats,  this  will  be  0. 

pi ayRate 

1.0  (0x00010000)  is  normal.  Higher  numbers  indicate  faster  play  rates.  Note  that 
ti  meStamp  is  already  adjusted  by  the  rate.  This  field  is  generally  of  interest  only 
to  audio  packetizers. 
fl  ags 

Flag  (see  below)  to  indicate  if  the  sample  is  a  sync  sample  (key  frame), 
sampl eDescSeed 

If  the  sample  description  changes,  this  number  will  change, 
sampl eDescri pti on 

The  sample  description  for  the  given  media  sample, 
sampl eRef 

Reserved;  do  not  use. 
dataLength 

Size  of  the  media  data. 
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data 

Pointer  to  the  media  data, 
rel easeProc 

If  not  NIL,  you  need  to  call  your  RTPMPDataRel  easeProc  (III— 2132)  when  you  are 
finished  with  the  sample  data. 


STR 


Information  to  pass  to  the  RTPMPDataRel  easeProc. 

flags  Constants 

kRTPMPSyncSampl eFl  ag 

The  sample  is  a  sync  sample. 

Associated  Functions 

RTPPBAddPacketSampl  eData  (III — 1485) 

Programming  Info 

C  interface  file:  QTStreami  ngComponents .  h 

See  Also 

See  RTPMPDataRel  easeProc  (III — 2132). 


RTPPayloadCharacteristic 


Stores  payload  characteristics  information. 

struct  RTPPayloadCharacteristic  { 

OSType  tag; 

long  value; 

}; 

tag 

Undocumented 
val  ue 

Undocumented 


Programming  Info 
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RTPPayloadlnfo 

Holds  a  payload's  name, 
struct  RTPPayloadlnfo  { 
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1  ong 

payl oadFl ags ; 

UInt8 

payloadlD; 

char 

unused[3] : 

char 

payl oadNamefl] 

}; 

pay! oadFl ags 

Undocumented 
payl oadID 

Undocumented 

unused[3] 

Unused, 
payl  oadName 

A  name  string. 

Programming  Info 
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Specifies  the  sort  order  for  a  list  of  packetizers. 

struct  RTPPayloadSortRequest  { 

long  characteristicCount ; 

RTPPayloadCharacteristic  character!' stic[l]; 

1: 

characteristicCount 

The  number  of  structures  in  the  characteristic  field, 
characteri sti c 

An  array  of  RTPPayl  oadCharacteri  sti  c  (IV-2409)  structures. 

Associated  Functions 

QTSFi  ndMedi  aPacketi  zer  (11-1231) 

Programming  Info 
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RTPReassemblerlnfo 


Undocumented 
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struct  RTPReassembl erlnfo  { 

long  character! sticCount; 

RTPPayl oadCharacteri sti c  character!  sti  c [ 1 ] ; 

character!'  sti  cCount 

The  number  of  structures  in  the  character!  sti  c  field, 
character! sti c 

An  array  of  RTPPayl  oadCharacteri  sti  c  (IV-2409)  structures. 

Programming  Info 
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RTPRssmlnitParams 


Initializes  a  packet  reassembler  component. 


struct  RTPRssmlnitParams  { 


RTPSSRC 

UInt8 

UInt8 

TimeBase 

TimeScale 


ssrc; 

payl oadType ; 
pa d [ 3 ]  ; 
ti  meBase ; 
ti meScal e ; 


}; 


ssrc 

Undocumented 

payl oadType 

Undocumented 


pad 

Unused, 
ti meBase 

A  reference  to  the  reassembler's  time  base.  You  obtain  a  time  base  by  calling 
GetMovi  eTimeBase  (1-496)  or  NewTimeBase  (11-1119). 

ti meScal e 

The  reassembler's  time  scale. 

Associated  Functions 

RTPRssmlni  ti  al  i  ze  (III — 1514) 

Programming  Info 
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RTPRssmPacket 


A  streaming  reassembler  packet  list. 


struct  RTPRssmPacket  { 

struct  RTPRssmPacket  * 
struct  RTPRssmPacket  * 
QTSStreamBuffer  * 

Bool ean 

UInt8 

UIntl6 

UInt32 

UInt32 

UInt32 

SHServerEditParameters 

TimeVal ue64 

SInt32 

SInt32 

}; 


next ; 
prev ; 

streamBuffer ; 
paramsFi  1 1  edln  ; 
padCl] ; 
sequenceNum ; 
transportHeader Length; 
payloadHeader Length; 
dataLength ; 
serverEdi tParams ; 
timeStamp ; 
chunkFl ags ; 
fl ags  ; 


next 

A  pointer  to  the  next  RTPRssmPacket  structure. 

prev 

A  pointer  to  the  previous  RTPRssmPacket  structure. 
streamBuffer 

A  pointer  to  a  QTSStreamBuffer  (IV-2385)  structure  defining  the  stream  buffer. 
paramsFi  1 1  edln 
Undocumented 


pad 

Undocumented 

sequenceNum 

Undocumented 
transportHeader Length 
Undocumented 
payloadHeader Length 
Undocumented 
dataLength 

Undocumented 
serverEdi tParams 
Undocumented 
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ti meStamp 

Undocumented 
chunkFl ags 

Undocumented 
fl  ags 

Undocumented 

Associated  Functions 

RTPRssmAd j  us  t  Packet  Pa  rams  (III — 1500) 

Programming  Info 
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RTPSendStreamBufferRangeParams 


Undocumented 


struct  RTPSendStreamBufferRangeParams 
QTSStreamBuf fer  * 

TimeVal ue64 

UInt32 

UInt32 

SInt32 

SInt32 

const  SHServerEdi tParameters  * 


{ 

streamBuf fer ; 
presentati onT i me ; 
chunkStartPosi ti on ; 
numDataBytes ; 
chunkFl ags ; 
fl ags  ; 

serverEdi tParams ; 


}; 


streamBuf fer 

Undocumented 
presentati onT i me 
Undocumented 
chunkStartPosi ti on 
Undocumented 
numDataBytes 

Undocumented 
chunkFl ags 

Undocumented 
fl  ags 

Undocumented 
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serverEdi tParams 
Undocumented 

Associated  Functions 

RTPRssmSendStreamBufferRange  (III — 1519) 

Programming  Info 
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SampleDescription 


Stores  information  required  to  decode  samples  in  a  media, 
struct  SampleDescription  { 


1  ong 

descSi ze ; 

1  ong 

dataFormat ; 

1  ong 

resvdl ; 

short 

resvd2 ; 

short 

dataRef Index 

1: 

descSi ze 

Size  in  bytes  of  this  data  structure. 
dataFormat 

The  sample  description  format, 
resvdl 

Reserved.  Set  to  0. 
resvd2 

Reserved.  Set  to  0. 
dataRef Index 

Contains  an  index  value  indicating  which  of  the  media's  data  references 
contains  the  sample  data  for  this  sample  description. 

Associated  Functions 

AddMedi  aSampl  e  (1-27) 

Programming  Info 

C  interface  file:  Movi  es .  h 


See  Also 

For  an  atom  that  contains  sample  description  structures,  see  ’  stsd  ’  (IV-2591). 
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SampleReference64Record 


Provides  a  64-bit  version  of  Sampl  eReferenceRecord  (IV-2416). 


struct  Sampl eReference64Record  { 


wi  de 

unsigned  long 
T i meVal ue 
unsigned  long 
short 


dataOf f set ; 
dataSi ze ; 

durati onPerSampl e ; 
numberOf Sampl  es ; 
sampl  e FI  ags  ; 


dataOf f set 

Specifies  the  offset  into  the  movie  data  file.  This  field  specifies  the  offset  into  the 
file  of  the  sample  data. 
dataSi ze 

Specifies  the  total  number  of  bytes  of  sample  data  identified  by  the  reference. 
All  samples  referenced  by  a  single  Sampl  eReference64Record  must  be  the  same 
size. 

durati onPerSampl e 

Specifies  the  duration  of  each  sample  in  the  reference.  You  must  specify  this 
parameter  in  the  media's  time  scale.  All  samples  referenced  by  a  single 
Sampl  eRef  erence64Record  must  be  the  same  duration. 

numberOf Sampl es 

Specifies  the  number  of  samples  contained  in  the  reference, 
sampl  eFl  ag 

Contains  flags  (see  below)  that  control  the  operation.  Set  unused  flags  to  0. 

sampleFlag  Constants 

medi aSampl eNotSync 

Indicates  whether  the  sample  to  be  added  is  not  a  synchronous  sample.  Set  this 
flag  to  1  if  the  sample  is  not  a  synchronous  sample.  Set  this  flag  to  0  if  the  sample 
is  a  synchronous  sample. 

Programming  Info 
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See  Also 

See  Sampl  eReferenceRecord  (IV-2416). 
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SampleReferenceRecord 


Describes  a  sample  or  group  of  similar  samples. 


struct  SampleReferenceRecord  { 


I  ong 
1  ong 

TimeVal ue 
1  ong 
short 


dataOffset ; 
dataSi ze ; 

durati onPerSampl e ; 
numberOfSampl es ; 
sampl eFl ags ; 


dataOffset 

Specifies  the  offset  into  the  movie  data  file.  This  field  specifies  the  offset  into  the 
file  of  the  sample  data. 
dataSi ze 

Specifies  the  total  number  of  bytes  of  sample  data  identified  by  the  reference. 
All  samples  referenced  by  a  single  Sampl  eReferenceRecord  must  be  the  same 
size. 

durati onPerSampl e 

Specifies  the  duration  of  each  sample  in  the  reference.  You  must  specify  this 
parameter  in  the  media's  time  scale.  All  samples  referenced  by  a  single 
Sampl  eReferenceRecord  must  be  the  same  duration. 

numberOfSampl es 

Specifies  the  number  of  samples  contained  in  the  reference, 
sampl  eFl  ag 

Contains  flags  (see  below)  that  control  the  operation.  Set  unused  flags  to  0. 

sampleFlag  Constants 

medi a Sampl e Not Sync 

Indicates  whether  the  sample  to  be  added  is  not  a  synchronous  sample.  Set  this 
flag  to  1  if  the  sample  is  not  a  synchronous  sample.  Set  this  flag  to  0  if  the  sample 
is  a  synchronous  sample. 

Programming  Info 
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See  Also 

This  data  structure  is  used  by  GetMedi  aSampl  eReferences  (1—449)  and 
AddMedi  aSampl  eReferences  (1-33). 
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SampleT  oChunk 


Maps  a  physical  sample  number  to  a  chunk  number. 

struct  Sampl eToChunk  { 
long  firstChunk; 

long  sampl esPerChunk; 

long  sampl eDescriptionID; 

}; 

f i rstChunk 

The  first  chunk  number  that  uses  this  data  structure, 
sampl esPerChunk 

The  number  of  samples  in  each  chunk, 
sampl eDescriptionID 

An  index  into  the  '  stsd  '  (IV-2591)  atom  for  this  sample. 

Discussion 

A  chunk  is  a  collection  of  data  samples  in  a  media  that  allows  optimized  data  access. 
A  chunk  may  contain  one  or  more  samples.  Chunks  in  a  media  may  have  different 
sizes,  and  the  samples  within  a  chunk  may  have  different  sizes. 

Programming  Info 
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See  Also 

See  'stsd'  (IV-2591). 


SCDataRateSettings 


Contains  the  current  temporal  compression  parameters  that  govern  the  data  rate. 

struct  SCDataRateSettings  { 
long  dataRate; 

long  f rameDurati on ; 

CodecQ  mi nSpati al Qual i ty ; 

CodecQ  mi nTemporal Qual i ty ; 

}; 

dataRate 

Specifies  the  maximum  number  of  bytes  of  compressed  data  your  application 
wants  to  receive  per  second.  Use  this  parameter  to  modulate  the  rate  at  which 
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SCExtendedProcs 


the  component  passes  compressed  data  to  your  application.  This  can  be  useful 
to  account  for  hardware  limitations  during  sequence  playback. 

f rameDurati on 

Indicates  the  duration  of  each  frame,  in  milliseconds.  Set  this  parameter  to  0  to 
allow  the  standard  dialog  component  to  calculate  the  duration  based  upon  the 
frame  rate  you  specify  in  an  scTemporal  Setti  ngsType  request.  However,  if  you 
allow  the  user  to  specify  a  0  frame  rate  (that  is,  you  set  the 
scAl  1  owZeroFrameRate  flag  to  1  in  your  scPreferenceFl  agsType  request),  you 
must  set  the  frame  duration  each  time  you  compress  a  frame,  because  the 
component  does  not  have  sufficient  information  to  determine  an  appropriate 
rate. 

mi nSpati al Qual i ty 

Specifies  the  minimum  acceptable  spatial  quality.  In  order  to  meet  your 
specified  data  rate,  the  standard  dialog  component  may  have  to  adjust  the 
spatial  quality  setting.  Use  this  parameter  to  set  a  minimum  level,  which  the 
component  may  not  exceed.  See  the  chapter  "Image  Compression  Manager"  in 
Inside  Macintosh:  QuickTime  (listed  in  the  bibliography)  for  values  for  both  this 
parameter  and  the  mi  nTemporal  Qual  i  ty  parameter. 

mi nTemporal Quality 

Specifies  the  minimum  acceptable  temporal  quality.  As  with  spatial  quality,  in 
order  to  meet  your  specified  data  rate,  the  standard  dialog  component  may 
have  to  adjust  the  temporal  quality  setting.  Use  this  parameter  to  set  a 
minimum  level,  which  the  component  may  not  exceed. 

Programming  Info 
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Extends  the  interface  provided  in  the  standard  image  or  sequence  dialog  boxes. 

struct  SCExtendedProcs  { 

SCModal  Fi  1  terllPP  filterProc; 

SCModal HookUPP  hookProc; 

long  refcon; 

Str31  customName; 

}; 

f i 1 terProc 

Contains  a  pointer  to  an  SCModal  Fi  1  terProc  (III— 2133)  callback  in  your 
application.  Because  the  compression  dialog  box  is  a  movable  modal  dialog 
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box,  you  must  provide  a  filter  to  process  update  events  for  your  application 
windows.  The  standard  component  calls  your  filter  function  before  it  processes 
the  event.  You  can  use  this  function  to  control  events  in  the  dialog  box.  For 
example,  you  might  use  the  filter  function  to  release  processing  time  to  other 
windows  displayed  by  your  application  while  the  standard 
image-compression  dialog  box  is  being  displayed.  If  you  do  not  want  to  specify 
a  filter  function,  set  this  parameter  to  NIL. 

hookProc 

Contains  a  pointer  to  an  SCModal  HookProc  (III— 2134)  callback  in  your 
application.  The  standard  component  calls  your  hook  function  whenever  the 
user  selects  an  item  in  the  dialog  box.  You  can  use  this  function  to  customize 
the  operation  of  the  standard  image-compression  dialog  box.  For  example,  you 
might  want  to  support  a  custom  button  that  activates  a  secondary  dialog  box. 
Another  possibility  would  be  to  provide  additional  validation  support  when 
the  user  clicks  OK.  If  you  do  not  want  to  specify  a  hook  function,  set  this 
parameter  to  NIL. 

ref con 

Specifies  a  reference  constant  that  is  to  be  passed  to  the  SCModal  HookProc  and 
SCModal  Fi  1  terProc  callbacks. 
customName 

Specifies  the  string  to  be  displayed  in  the  custom  button  in  the  dialog  box.  If 
you  are  not  using  a  custom  button,  set  this  parameter  to  N I L. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

See  Also 

See  SCModal  Fi  1  terProc  (III— 2133)  and  SCModal  HookProc  (III— 2134).  The  operation  of 
modal-dialog  filter  functions  is  described  in  the  chapter  "Dialog  Manager"  in  Inside 
Macintosh:  Macintosh  Toolbox  Essentials  (listed  in  the  bibliography). 
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Provides  data  to  the  schedul  edSoundCmd  command  for  SndDoImmedi  ate  (III— 1832)  and 
SndDoCommand  (III — 1831). 

struct  ScheduledSoundHeader  { 

SoundHeaderUni on  u; 
long  flags; 

short  reserved; 

short  cal  1 BackParaml ; 

long  call BackParam2 ; 
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TimeRecord  startTime; 

}; 

u 

A  union  of  one  of  the  three  existing  SoundHeader  types, 
fl  ags 

Flag  (see  below)  to  determine  if  this  structure  is  an 
ExtendedSchedul edSoundHeader. 
reserved 

Reserved, 
cal  1 BackParaml 
Undocumented 
cal  1 BackParam2 
Undocumented 
startTime 

Undocumented 

flags  Constant 

kSchedul edSoundExtendedHdr 

If  0,  this  is  a  classic  Schedul  edSoundHeader.  If  1,  this  is  an 

ExtendedSchedul  edSoundHeader  (IV-2251)  and  at  least  contains  the  recordSi  ze 

and  extendedFl  ags  fields. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

See  SndDoImmedi  ate  (III — 1832)  and  SndDoCommand  (III — 1831). 


SCParams 


Provides  data  for  the  SCGetCompressi  onExtended  (III— 1544)  function. 


struct  SCParams  { 

1  ong 

CodecType 

CodecComponent 

CodecQ 

CodecQ 

short 

Fi  xed 

1  ong 

1  ong 


fl ags ; 

theCodecType ; 
theCodec ; 
spati al Qual i ty ; 
temporal Qual i ty ; 
depth ; 
f rameRate ; 
keyFrameRate ; 
reservedl ; 
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long  reserved2; 

}; 

fl  ags 

Flags  (see  below). 
theCodecType 

A  compressor  type;  see  "Codec  Identifiers"  (IV-2655). 
theCodec 

An  instance  of  a  compressor  component,  obtained  by  calling  OpenComponent 
(11-1130)  or  OpenDefaul  tComponent  (11-1131). 

spati al Qua! i ty 

Constants  (see  below)  that  determine  image  spatial  quality, 
temporal Qual i ty 

Constants  (see  below)  that  determine  image  temporal  quality, 
depth 

Image  data  depth, 
f rameRate 

The  frame  rate. 
keyFrameRate 

The  key  frame  rate, 
reserved!. 

Reserved. 

reserved2 

Reserved. 

flags  Constants 

scGetCompressi on 
Undocumented 
scShowMoti onSetti  ngs 
Undocumented 
scSetti ngsChangedltem 
Undocumented 

spatialQuality  and  temporalQuality  Constants 

codecMi nQual i ty 

The  minimum  valid  value  for  a  CodecQ  field. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 


STR 
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codecNormal Qual i ty 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 

codecMaxQual i ty 

The  maximum  standard  value  for  a  CodecQ  field, 
codec LosslessQuality 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

Associated  Functions 

SCGetCompressi onExtended  (III — 1544) 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


ScrpSTElement 


Defines  the  style  of  text  in  the  Mac  OS  scrap. 


struct  ScrpSTElement  { 


I  ong 
short 
short 
short 

Styl  eFi  el  d 
short 
RGBCol or 


scrpStartChar ; 
scrpHei ght ; 
scrpAscent ; 
scrpFont ; 
scrpFace ; 
scrpSi ze ; 
scrpCol or ; 


scrpStartChar 

The  offset  to  the  beginning  of  a  TEStyl  eRec  (IV-2473)  structure  in  the  Mac  OS 
scrap, 
scrptlei  ght 

The  line  height. 
scrpAscent 

The  font  ascent. 
scrpFont 

The  font  family  ID. 
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scrpFace 

Unpacked  byte  representing  the  style. 
scrpSi ze 

The  size  in  points. 
scrpCol or 

An  RGBCol  or  (IV-2403)  structure  representing  the  text  color. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


STR 


SCSpatialSettings 


Passes  information  when  scSpati  al  Setti  ngsType  is  used  with  SCGetlnfo  (III— 1545) 
or  SCSetlnfo  (III— 1558). 

struct  SCSpatialSettings  { 

CodecType  codecType; 

CodecComponent  codec; 
short  depth; 

CodecQ  spati al Qual i ty ; 

}; 

codecType 

Specifies  the  default  compressor  type  that  is  displayed  in  the  pop-up  menu  of 
compressors  in  the  dialog  box.  The  standard  image-compression  dialog 
component  uses  this  field  to  return  the  compressor  type  that  was  selected  by 
the  user.  You  must  set  this  parameter  to  one  of  the  compressor  types  supported 
by  the  Image  Compression  Manager,  or  to  N I L.  If  you  set  the  field  to  NIL,  the 
standard  image-compression  dialog  component  uses  as  the  default  value  the 
first  compressor  or  compressor  type  that  it  retrieves  from  the  Image 
Compression  Manager. 

codec 

Provides  additional  information  about  the  default  compressor  that  is  displayed 
in  the  pop-up  menu  of  compressors  in  the  dialog  box.  If  the  user  selects  a 
specific  compressor  component,  the  standard  image-compression  dialog 
component  returns  the  appropriate  compressor  identifier  in  this  field. 

The  scLi  stEveryCodec  bit  in  the  scPref  erenceFl  agsType  request  passed  to 
SCGetlnfo  or  SCSetlnfo  influences  the  operation  of  the  compressor  list  in  the 
dialog  box  and,  therefore,  the  way  the  component  uses  this  field.  Set 
scLi  stEveryCodec  to  1  to  have  the  list  contain  an  entry  for  each  compressor 
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component  in  the  system.  If  the  flag  is  set  to  1,  the  standard  image-compression 
dialog  component  uses  this  field  along  with  the  codecType  field  to  select  the 
default  compressor  that  appears  in  the  dialog  box.  To  specify  a  default  image 
compressor  component,  set  the  codecType  field  to  the  appropriate  compressor 
identifier.  When  the  user  clicks  OK  in  the  dialog  box,  the  standard 
image-compression  dialog  component  returns  the  compressor  identifier  that 
corresponds  to  the  selected  image  compressor  component.  If  you  set  the 
codecType  field  to  N I L,  the  standard  image-compression  dialog  component  uses 
as  the  default  value  the  first  compressor  of  the  specified  type  that  it  retrieves 
from  the  Image  Compression  Manager. 

If  you  have  set  scLi  stEve ry Codec  to  0,  the  list  contains  only  one  entry  for  each 
type  of  compressor  in  the  system.  The  standard  image-compression  dialog 
component  ignores  this  field  when  creating  the  list  of  compressor  types.  In  this 
case,  the  standard  image-compression  dialog  component  does  not  change  the 
value  of  this  field  when  the  user  clicks  OK. 

However,  you  may  use  the  codec  field  to  specify  additional  selection  criteria  by 
setting  it  to  one  of  the  special  compressor  identifiers  supported  by  the  Image 
Compression  Manager;  see  "Codec  Identifiers"  (IV-2655).  The  standard 
image-compression  dialog  component  may  use  this  value  when  it  validates  the 
compression  parameters  selected  by  the  user. 

depth 

Specifies  the  default  value  of  the  pixel  depth  pop-up  menu  in  the  dialog  box. 
This  menu  allows  the  user  to  select  the  color  or  gray  scale  resolution  value  to  be 
used  when  compressing  the  image  or  image  sequence.  If  you  set  this  field  to  0, 
the  component  chooses  an  appropriate  depth  for  the  default  compressor  you 
specified  with  the  codec  field.  Values  of  1,  2, 4,  8, 16, 24,  and  32  indicate  the 
depth  of  color  images.  Values  of  34,  36,  and  40  indicate  2-bit,  4-bit,  and  8-bit 
grayscale,  respectively,  for  grayscale  images. 

When  the  user  clicks  OK,  the  standard  image-compression  dialog  component 
sets  this  field  to  the  pixel  depth  value  selected  by  the  user.  Note  that  the 
standard  image-compression  dialog  component  may  adjust  the  depth  value  so 
that  it  corresponds  to  a  value  that  is  supported  by  the  compressor  that  has  been 
selected  by  the  user.  The  depth  returned  could  be  0  if  the  scShowBestDepth  flag 
is  set  in  scPreferenceFl  agsType. 

spati at Qual i ty 

A  constant  (see  below)  that  specifies  the  default  setting  of  the  quality  slider  in 
the  dialog  box.  This  slider  controls  the  spatial  quality  of  the  compressed  image 
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sequence,  which  influences  the  amount  of  spatial  compression  that  can  be 
achieved.  Spatial  compression  eliminates  redundant  information  within  each 
frame  in  a  sequence.  When  the  user  clicks  OK,  the  standard  image-compression 
dialog  component  sets  this  field  to  the  spatial  quality  value  selected  by  the  user. 
Note  that  the  standard  image-compression  dialog  component  may  adjust  the 
quality  value  so  that  it  corresponds  to  a  value  that  is  supported  by  the 
compressor  that  has  been  selected  by  the  user. 

spatialQuality  Constants 

codecMi nQual i ty 

The  minimum  valid  value. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 
codecNormal Quality 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 
codecMaxQual i ty 

The  maximum  standard  value, 
codec Los  si essQual i ty 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

Discussion 

This  structure  controls  how  an  image  is  compressed;  you  supply  a  pointer  to  it.  If 
you  are  retrieving  its  settings,  using  SCGetlnfo  (III— 1545),  the  Standard  Dialog 
component  places  the  current  settings  into  the  structure.  If  you  are  changing  the 
settings,  using  SCSetlnfo  (III— 1558),  place  the  new  values  into  the  structure;  the 
Standard  Dialog  component  will  use  those  values  to  update  its  settings. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

See  Also 

See  SCGetlnfo  (III— 1545)  and  SCSetlnfo  (III— 1558). 


SCStatus 


Passes  sound  channel  status  information  to  SndChannel  Status  (III— 1829). 
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struct  SCStatus  { 

Unsi gnedFi xed 
Unsi gnedFi xed 
Unsi gnedFi xed 
Bool ean 
Bool ean 
Bool ean 
Bool ean 
unsigned  long 
1  ong 

}; 

scStartTime 

Starting  time  in  seconds  for  play  from  disk;  0  if  the  Sound  Manager  is  not 
currently  playing  from  a  disk  through  the  channel  specified  to 
SndChannel  Status.  The  Sound  Manager  sets  the  values  of  the  scStartT i me  and 
scEndT i  me  fields  based  on  the  values  you  set  in  an  Audi  oSel  ecti  on  (IV-2161) 
structure. 
scEndT i me 

Ending  time  in  seconds  for  play  from  disk;  0  if  the  Sound  Manager  is  not 
currently  playing  from  a  disk  through  the  channel  specified  to 
SndChannel Status. 
scCurrentT i me 

Current  time  for  play  from  disk;  0  if  the  Sound  Manager  is  not  currently  playing 
from  a  disk  through  the  channel  specified  to  SndChannel  Status.  This  field 
indicates  the  number  of  seconds  between  the  beginning  of  the  sound  on  the 
disk  and  the  part  of  the  sound  currently  being  played. 

scChannel Busy 

TRUE  if  the  channel  is  processing  commands;  FALSE  otherwise. 
scChannel Di sposed 

Reserved;  do  not  use. 
scChannel Paused 

TRUE  if  the  channel  is  paused;  FALSE  otherwise.  After  issuing  a  series  of  sound 
commands,  you  can  use  the  scChannel  Busy  and  scChannel  Paused  fields  to 
determine  if  the  channel  has  finished  processing  all  of  the  commands.  If  both 
scChannel  Busy  and  scChannel  Paused  are  FALSE,  the  Sound  Manager  has 
processed  all  of  the  channel's  commands. 

scUnused 

Unused. 


scStartTime; 
scEndT i me ; 
scCurrentT i me ; 
scChannel Busy ; 
scChannel Di sposed ; 
scChannel Paused ; 
scUnused ; 

scChannel At tributes; 
scCPULoad ; 
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scChannel Attri butes 

You  can  use  constants  (see  below)  to  mask  out  certain  values  in  the 
scChannel  Attri  butes  field  to  determine  how  a  channel  has  been  initialized. 
scCPULoad 

Obsolete;  do  not  use. 

scChannelAttributes  Mask  Constants 

i ni tPanMask 

Mask  for  right /left  pan  values;  value  is  0x0003. 
i ni tSRateMask 

Mask  for  sample  rate  values;  value  is  0x0030. 
i ni tStereoMask 

Mask  for  mono/stereo  values;  value  is  OxOOCO. 

Discussion 

Note  that  because  the  Sound  Manager  might  be  playing  only  a  selection  of  a  sound, 
the  scCurrentTime  field  does  not  reflect  the  number  of  seconds  of  sound  play  that 
have  elapsed.  To  compute  the  number  of  seconds  of  sound  play  elapsed,  you  can 
subtract  the  value  in  the  scStartT i me  field  from  that  in  the  scCurrentTime  field. 
However,  because  the  Sound  Manager  updates  the  value  of  the  scCurrentTime  field 
only  periodically,  you  should  not  rely  on  the  accuracy  of  its  value. 

Version  Notes 

The  scCPULoad  field  previously  reflected  the  percentage  of  CPU  processing  power 
used  by  the  sound  channel.  However,  this  field  is  obsolete,  and  you  should  not  rely 
on  its  value. 

Associated  Functions 

SndChannel  Status  (III — 1829) 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

See  SndChannel  Status  (III — 1829). 
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SCT  emporalSettings 


Passes  information  when  scTemporal  Setti  ngsType  is  used  with  SCGetlnfo  (III— 1545) 
or  SCSetlnfo  (III— 1558). 

struct  SCTemporalSettings  { 

CodecQ  temporal Qual i ty ; 

Fixed  frameRate; 
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long  keyFrameRate ; 

}; 

temporal Qual i ty 

A  constant  (see  below)  that  specifies  the  default  setting  of  the  motion  quality 
slider  in  the  dialog  box.  This  slider  controls  the  temporal  quality  of  the 
compressed  image,  which  influences  the  amount  of  temporal  compression  that 
can  be  achieved.  Note  that  Apple's  component  uses  the  same  slider  for  both 
spatial  and  temporal  quality.  Temporal  compression  eliminates  redundant 
information  between  frames  in  an  image  sequence.  When  the  user  clicks  OK, 
the  standard  image-compression  dialog  component  sets  this  field  to  the 
temporal  quality  value  selected  by  the  user.  Note  that  the  standard 
image-compression  dialog  component  may  adjust  the  quality  value  so  that  it 
corresponds  to  a  value  that  is  supported  by  the  compressor  that  has  been 
selected  by  the  user, 
f rameRate 

Specifies  the  default  value  of  the  text-edit  box  that  controls  the  number  of 
frames  per  second  in  the  image  sequence  to  be  compressed.  This  dialog  item 
allows  the  user  to  select  the  frame  rate  to  be  used  when  compressing  the  image 
sequence.  Note  that  this  field  is  stored  as  a  fixed-point  number,  allowing  the 
user  to  specify  fractional  frame  rates.  When  the  user  clicks  OK,  the  standard 
image-compression  dialog  component  sets  this  field  to  the  frame  rate  value 
specified  by  the  user.  If  you  have  set  the  scAl  1  owZeroFrameRate  flag  to  1  in  the 
scPreferenceFl  agsType  request  passed  to  SCGetlnfo  or  SCSetlnfo,  and  the  user 
specifies  nothing  or  0,  the  component  sets  this  field  to  0. 
keyFrameRate 

Specifies  the  default  value  of  the  text-edit  box  that  controls  the  frequency  with 
which  key  frames  are  inserted  into  the  compressed  image  sequence.  Key 
frames  provide  points  from  which  a  temporally  compressed  sequence  may  be 
decompressed.  When  the  user  clicks  OK,  the  standard  image-compression 
dialog  component  sets  this  field  to  the  key  frame  rate  value  specified  by  the 
user.  If  you  have  set  the  scAl  1  owZeroKey  FrameRate  flag  to  1  in  the 
scPreferenceFl  agsType  request  passed  to  SCGetlnfo  or  SCSetlnfo,  and  the  user 
specifies  nothing  or  0,  the  component  sets  this  field  to  0. 

temporalQuality  Constants 

codecMi nQual i ty 

The  minimum  valid  value. 
codecLowQual i ty 

Low-quality  image  reproduction.  This  value  should  correspond  to  the  lowest 
image  quality  that  still  results  in  acceptable  display  characteristics. 
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codecNormal Quality 

Image  reproduction  of  normal  quality. 
codecHi ghQual i ty 

High-quality  image  reproduction.  This  value  should  correspond  to  the  highest 
image  quality  that  can  be  achieved  with  reasonable  performance. 

codecMaxQual i ty 

The  maximum  standard  value, 
codec Los  si essQual i ty 

Lossless  compression  or  decompression.  This  special  value  is  valid  only  for 
components  that  can  support  lossless  compression  or  decompression. 

Discussion 

The  frame  rate  dialog  item  can  be  useful  in  cases  where  your  application  cannot 
determine  the  frame  rate  of  the  source  movie.  For  example,  movies  stored  in  PICT 
files  do  not  include  frame  rate  information.  Therefore,  the  user  must  specify  a  frame 
rate  for  you.  Alternatively,  some  users  may  want  to  create  movies  with  different 
frame  rates.  This  item  allows  the  user  to  specify  a  rate  for  the  compressed  sequence. 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

See  Also 

See  SCGetlnfo  (III— 1545)  and  SCSetlnfo  (III— 1558). 
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SeqGrabExtendedFramelnfo 


Defines  a  frame  for  a  sequence  grabber  component  and  its  sequence  grabber 
channel  components. 


struct  SeqGrabExtendedFramelnfo 


1; 


wi  de 
1  ong 
1  ong 

SGChannel 
1  ong 

SGOutput 


f rameOf f set ; 
f rameT i me ; 
f rameSi ze ; 
frameChannel ; 
f rameRefCon ; 
f rameOutput ; 


{ 


f rameOf f set 

Specifies  the  offset  to  the  sample.  Note  that  this  is  a  64-bit  value. 
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frameTime 

Specifies  the  time  at  which  the  frame  was  captured  by  a  sequence  grabber 
channel  component.  The  time  value  is  relative  to  the  data  sequence.  The 
channel  component  must  choose  a  time  scale  and  use  it  consistently  for  all 
sample  references, 
f rameSi ze 

Specifies  the  number  of  bytes  in  the  current  sample, 
f rameChannel 

Identifies  the  current  connection  to  the  channel  component, 
f rameRefCon 

Contains  a  reference  constant  for  use  by  the  channel  component.  The  channel 
component  uses  this  constant  in  any  appropriate  way;  for  example,  to  store  a 
reference  to  frame  differencing  information  for  a  time-compressed  sequence, 
f rameOutput 

Identifies  the  sequence  grabber  output  used  to  store  captured  data  referenced 
by  the  current  record. 

Discussion 

This  structure  differs  from  SeqGrabFramelnfo  (IV-2430)  in  two  respects:  the 
f  rameOffset  field  takes  a  64-bit  value,  and  the  f  rameOutput  field  does  not  exist  in 
SeqGrabFramelnfo. 

Version  Notes 

Introduced  in  QuickTime  4. 

Associated  Functions 

SGAdd  Ext  ended  Frame  Reference  (III — 1677) 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

See  Also 

See  SeqGrabFramelnfo  (IV-2430). 


SeqGrabFramelnfo 


Provides  information  about  a  frame  for  a  sequence  grabber  component  and  its 
sequence  grabber  channel  components. 

struct  SeqGrabFramelnfo  { 


ong 

f rameOffset ; 

ong 

f rameT i me ; 

ong 

f rameSi ze ; 
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SGChannel  frameChannel ; 

long  frameRefCon; 

}; 

f rameOf f set 

Specifies  the  offset  to  the  sample.  Your  channel  component  obtains  this  value 
from  SGWri teMovi eData  (III— 1824). 
f rameT i me 

Specifies  the  time  at  which  your  channel  component  captured  the  frame.  This 
time  value  is  relative  to  the  data  sequence.  That  is,  this  time  is  not  represented 
in  the  context  of  any  fixed  time  scale.  Rather,  your  channel  component  must 
choose  and  use  a  time  scale  consistently  for  all  sample  references. 

f rameSi ze 

Specifies  the  number  of  bytes  in  the  sample  described  by  the  sample  reference. 
frameChannel 

Identifies  the  current  connection  to  your  channel. 
frameRefCon 

Contains  a  reference  constant  for  use  by  your  channel  component.  You  can  use 
this  value  in  any  way  that  is  appropriate  for  your  channel  component.  For 
example,  video  channel  components  may  use  this  value  to  store  a  reference  to 
frame  differencing  information  for  a  temporally  compressed  image  sequence. 

Discussion 

This  structure  differs  from  SeqGrabExtendedFramelnfo  (IV-2429)  in  two  respects:  the 
f  rameOffset  field  takes  a  32-bit  value,  and  SeqGrabExtendedFramelnfo  has  a 
f  rameOutput  field. 

Associated  Functions 

SGAddFrameReference  (III — 1681) 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

See  Also 

See  SeqGrabExtendedFramelnfo  (IV-2429). 
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SFReply 


Passes  Standard  File  Dialog  information  to  SFGetFi  1  ePrevi  ew  (III— 1674)  or 
SFPGetFi  1  ePrevi  ew  (III — 1676). 

struct  SFReply  { 
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Bool ean 

good ; 

Bool ean 

copy ; 

OSType 

fType ; 

short 

vRef Num 

short 

versi on 

StrFi 1 eName 

f Name ; 

}; 

good 

Reports  whether  the  reply  record  is  valid.  The  value  is  TRU  E  after  the  user  clicks 
Save  or  Open;  FALSE  after  the  user  clicks  Cancel.  When  the  user  has  completed 
the  dialog  box,  the  other  fields  in  the  reply  record  are  valid  only  if  the  value  of 
good  is  TRUE. 

copy 

Reserved;  do  not  use. 
fType 

Contains  the  file  type  of  the  selected  file;  see  "File  Types  and  Creators" 
(IV-2668). 

vRef Num 

Contains  the  working  directory  reference  number,  which  encodes  both  the 
volume  reference  number  and  the  parent  directory  ID  of  the  selected  file. 

versi on 

Reserved;  do  not  use. 
f  Name 

Contains  the  name  of  the  selected  file;  its  type  is  Str63  on  the  Mac  OS. 

Associated  Functions 

SFGetFi  1  ePrevi  ew  (III — 1674) 

Programming  Info 

C  interface  file:  StandardFile.h 


See  Also 

See  SFGetFi  1  ePrevi  ew  (III — 1674)  and  SFPGetFi  1  ePrevi  ew  (III — 1676). 


SGCompressInfo 

Defines  the  characteristics  of  a  buffer  that  contains  a  captured  image  that  has  been 
compressed. 

struct  SGCompressInfo  { 

Ptr  buffer: 
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unsigned  long 

UInt8 

UInt8 


buf f erSi ze ; 
si  mi  1 ari ty ; 
reserved ; 


}; 


buffer 

Points  to  the  buffer  that  contains  the  compressed  image.  This  pointer  must 
contain  a  32-bit  clean  address. 

buf ferSi ze 

Specifies  the  number  of  bytes  of  image  data  in  the  buffer, 
si  mi  1 ari ty 

Indicates  the  relative  similarity  of  this  image  to  the  previous  image  in  a 
sequence.  A  value  of  0  indicates  that  the  current  frame  is  a  key  frame  in  the 
sequence.  A  value  of  255  indicates  that  the  current  frame  is  identical  to  the 
previous  frame.  Values  from  1  through  254  indicate  relative  similarity,  ranging 
from  very  different  (1)  to  very  similar  (254). 
reserved 

Reserved;  set  to  0. 

Callback  functions  use  this  structure  to  exchange  information  about  compressed 
images.  For  example,  SGCompressCompl  eteBottl  eProc  (III— 2138)  must  format  a 
compression  information  record  whenever  a  video  frame  is  compressed. 

Associated  Functions 

SGCompressCompl  eteBottl  eProc  (III — 2138) 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents  .  h 


Discussion 


See  Also 


See  SGCompressCompl  eteBottl  eProc  (III — 2138). 
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SGDeviceListRecord 


Passes  information  about  one  or  more  channel  devices. 

struct  SGDeviceListRecord  { 
short  count; 

short  sel ectedlndex; 

long  reserved; 

SGDeviceName  entry[l]; 
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count 

Indicates  the  number  of  devices  described  by  this  structure.  The  value  of  this 
field  corresponds  to  the  number  of  entries  in  the  device  name  array  defined  by 
the  entry  field, 
sel ectedlndex 

Identifies  the  currently  active  device.  The  value  of  this  field  corresponds  to  the 
appropriate  entry  in  the  device  name  array  defined  by  the  entry  field.  Note  that 
this  value  is  zero-relative;  that  is,  the  first  entry  has  an  index  number  of  0,  the 
second's  value  is  1,  and  so  on. 

reserved 

Reserved;  set  to  0. 
entry 

Contains  an  array  of  device  name  structures.  Each  structure  corresponds  to  one 
valid  device.  The  count  field  indicates  the  number  of  entries  in  this  array.  The 
SGDevi  ceName  (IV-2434)  structure  defines  the  format  of  a  device  name  structure. 

Discussion 

Sequence  grabbers  provide  a  number  of  functions  that  allow  you  to  determine  the 
device  that  is  attached  to  a  given  sequence  grabber  channel.  These  devices  allow  the 
channel  component  to  control  the  digitizing  equipment.  For  example,  video 
channels  use  video  digitizer  components,  and  sound  channels  use  sound  input 
drivers.  Your  application  can  use  these  routines  to  present  a  list  of  available  devices 
to  the  user,  allowing  the  user  to  select  a  specific  device  for  each  channel. 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

See  Also 

SGGetChannel  Devi  ceLi  st  (III— 1701)  retrieves  a  list  of  devices  that  may  be  used  with 
a  specified  channel.  You  can  place  one  or  more  device  names  into  a  menu  by  calling 
SGAppendDevi  ceLi  stToMenu  (III— 1685).  You  can  use  SGSetChannel  Device  (III— 1776)  to 
assign  a  device  to  a  channel. 


SGDeviceName 


Identifies  a  single  device  that  may  be  used  by  a  sequence  grabber  channel. 

struct  SGDeviceName  { 

Str63  name; 

Handle  icon; 

long  flags; 

long  refCon; 


IV-2434 


Inside  QuickTime:  Data  Structures 


SGOutputRecord 


long  reserved; 

}; 

name 

Contains  the  name  of  the  device.  For  video  digitizer  components,  this  field 
contains  the  component's  name  as  specified  in  the  component  resource.  For 
sound  input  drivers,  this  field  contains  the  driver  name. 

i  con 

Contains  a  handle  to  the  device's  icon.  Some  devices  may  support  an  icon, 
which  you  may  choose  to  present  to  the  user.  If  the  device  does  not  support  an 
icon,  or  if  you  choose  not  to  retrieve  this  information,  by  setting  the 
sgDeviceListWithlcons  flag  to  0  when  you  call  SGGetChannel  DeviceList 
(III— 1701),  this  field  is  set  to  NIL. 
fl  ags 

Flags  (see  below)  that  reflect  the  current  status  of  the  device.  The  sequence 
grabber  sets  these  flags  when  you  retrieve  a  device  list. 

refCon 

Reserved;  set  to  0. 
reserved 

Reserved;  set  to  0. 

flags  Constants 

sgDevi ceNameFl agDevi ceUnavai 1 abl e 

When  set  to  1,  this  flag  indicates  that  this  device  is  not  currently  available. 

Programming  Info 
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See  Also 

See  SGDevi  ceLi  stRecord  (IV-2433). 
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SGOutputRecord 


Contains  a  sequence  grabber  output. 

struct  SGOutputRecord  { 
long  data [ 1 ] ; 

}; 

data 

An  array  of  data. 
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Programming  Info 

C  interface  file:  QuickTimeComponents.h 


ShadowSync 


Identifies  a  self-contained  sync  sample  that  is  used  as  an  alternate  for  an  existing 
frame  difference  sample. 

struct  ShadowSync  { 

long  fdSampl eNum ; 

long  syncSampl eNum ; 

}; 

fdSampl eNum 

A  frame-difference  sample  number. 
syncSampl eNum 

The  corresponding  sync  sample  number. 

Programming  Info 

C  interface  file:  MoviesFormat.h 


See  Also 

For  the  atom  structure  that  holds  ShadowSync  data  structures,  see  '  stsh  '  (IV-2592). 


SHChunkRecord 


Defines  a  chunk  for  a  reassembler. 


struct  SHChunkRecord  { 
UInt32 
1  ong 
SInt32 
UInt32 

const  UInt8  * 

1  ong 
1  ong 

TimeVal ue64 


versn  on ; 
reservedl ; 
fl ags ; 
dataSi ze ; 
dataPtr ; 
reserved2 ; 
reserved3 ; 
presentationTime; 
reserved4 ; 
reserved5 ; 

serverEditParameters; 
reserved6 ; 
reserved7 ; 


1  ong 
1  ong 

const  SHServerEdi tParameters  * 
1  ong 
1  ong 


IV-2436 
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versi on 

Undocumented 

reservedl 

Reserved;  do  not  use. 
flags 

Undocumented 
dataSi ze 

The  size  of  the  chunk  data. 
dataPtr 

A  pointer  to  the  chunk  data. 
reserved2 

Reserved;  do  not  use. 
reserved3 

Reserved;  do  not  use. 
presentationTime 
Undocumented 
reserved4 

Reserved;  do  not  use. 
reserved5 

Reserved;  do  not  use. 
server Ed i t Parameters 

A  pointer  to  an  SHServerEdi  tParameters  (IV-2437)  structure  containing  the 
server  edit  parameters 

reserved6 

Reserved;  do  not  use. 
reserved7 

Reserved;  do  not  use. 

Associated  Functions 

RTPRssmCopyDataToChunk  (III — 1503) 

Programming  Info 
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SHServerEditParameters 


Undocumented 
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struct  SHServerEdi tParameters  { 


UInt32 
Fi  xed 

TimeVal  ue64 
TimeVal ue64 


versn  on ; 
edi tRate ; 

dataStartTi me_medi aAxi  s ; 
dataEndT i me_medi aAxi s ; 


versi on 

Undocumented 
edi tRate 

Undocumented 
dataStartTi me_medi aAxi s 
Undocumented 
dataEndTime_medi aAxis 
Undocumented 


Programming  Info 
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SMStatus 


Passes  information  to  SndManagerStatus  (III— 1839)  to  determine  information  about 
the  sound  channels  currently  allocated  by  all  applications. 

struct  SMStatus  { 

short  smMaxCPULoad ; 

short  smNumChannel s ; 

short  smCurCPULoad ; 

}; 

smMaxCPULoad 

A  default  value  of  100  at  startup  time. 
smNumChannel s 

The  number  of  sound  channels  currently  allocated.  This  does  not  mean  that  the 
channels  are  actually  being  used,  only  that  they  have  been  created  with  the 
SndNewChannel  function  and  not  yet  disposed. 
smCurCPULoad 

The  approximate  percentage  of  CPU  processing  power  currently  taken  by 
allocated  sound  channels. 
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Discussion 

The  Sound  Manager  uses  information  that  it  returns  in  the  smMaxCPULoad  and 
smCurCPULoad  fields  to  help  it  determine  whether  it  can  allocate  a  new  channel  when 
your  application  calls  SndNewChannel  (III— 1839).  Your  application  should  not  reply 
on  the  values  returned  in  the  smMaxCPULoad  and  smCurCPULoad  fields.  To  determine  if 
it  is  safe  to  allocate  a  channel,  simply  try  to  allocate  it  with  SndNewChannel .  That 
function  returns  the  appropriate  result  code  if  allocating  the  channel  would  put  too 
much  of  a  strain  on  CPU  processing. 

Associated  Functions 

SndManagerStatus  (III — 1839) 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

See  SndManagerStatus  (III — 1839). 
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Snd2ListResource 


HyperCard  sound  resource  format. 


struct  Snd2Li stResource  { 


short 

short 

short 

SndCommand 

UInt8 


}; 


format ; 
refCount ; 
numCommands ; 
commandPart[l] ; 
dataPart[l] ; 


format 

Undocumented 

refCount 

Undocumented 

numCommands 

Undocumented 

commandPart 

Undocumented 

dataPart 

Undocumented 
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SndChannel 


Stores  information  about  each  sound  channel. 


struct  SndChannel  { 
SndChannel Ptr 
Ptr 

SndCal 1 BackUPP 
1  ong 
1  ong 

SndCommand 

short 

short 

short 

short 

SndCommand 


nextChan ; 
f i rstMod ; 
cal  1  Back ; 
userlnfo ; 
wait; 

cmdlnProgress ; 
fl ags  ; 
qLength  ; 
qHead ; 
qT ail  ; 
queue[128] ; 


nextChan 

A  pointer  to  the  next  sound  channel  in  a  single  queue  of  channels  that  the 
Sound  Manager  maintains  for  all  applications, 
f i rstMod 

Reserved;  do  not  use. 
cal  1  Back 

A  pointer  to  an  SndCal  1  BackProc  (III— 2147)  callback  associated  with  the  sound 
channel. 

userlnfo 

A  four-byte  value  that  your  application  can  use  to  store  information. 

wai  t 

Reserved;  do  not  use. 
cmdlnProgress 

Reserved;  do  not  use. 
fl  ags 

Reserved;  do  not  use. 
qLength 

Reserved;  do  not  use. 
qHead 

Reserved;  do  not  use. 
qTai  1 

Reserved;  do  not  use. 
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queue 

The  sound  commands  pending  for  the  sound  channel. 

Discussion 

The  Sound  Manager  maintains  a  structure  of  this  type  to  store  information  about 
each  sound  channel  that  you  allocate  directly  by  calling  the  SndNewChannel  (III— 1839) 
function  or  indirectly  by  passing  a  N I L  channel  to  a  high-level  Sound  Manager 
routine  like  SndPl  ay  (III— 1842).  The  only  field  of  this  structure  that  you  are  likely  to 
need  to  access  directly  is  the  u  s  e  r  I  n  f  o  field .  This  field  is  useful  if  you  need  to  pass  a 
value  to  a  Sound  Manager  callback  procedure  or  completion  routine.  For  example, 
you  might  store  a  handle  to  sound  data  here  so  that  a  routine  that  disposes  of  an 
allocated  channel  can  also  release  the  sound  data  that  the  channel  played. 

Associated  Functions 

SndCal  1  BackProc  (III — 2147) 

Programming  Info 
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SndCommand 


Stores  a  sound  command. 

struct  SndCommand  { 
unsigned  short 
short 
1  ong 

}; 

cmd 

The  command  number;  see  "Sound  Commands"  (IV-2691). 
paraml 

First  parameter. 
param2 

Second  parameter. 

Discussion 

Commands  are  always  8  bytes  in  length.  The  first  2  bytes  are  the  command  number, 
and  the  next  6  make  up  the  command's  options.  The  format  of  the  last  6  bytes 
depends  on  the  command  in  use,  although  typically  those  6  bytes  are  interpreted  as 
an  integer  followed  by  a  long  integer.  For  example,  an  application  can  install  a  wave 
table  into  a  sound  channel  by  using  SndDoCommand  (III— 1831)  with  a  sound  command 
whose  cmd  field  is  the  waveTabl  eCmd  constant.  In  that  case,  the  paraml  field  specifies 


cmd ; 
paraml ; 
param2 ; 
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SndDoubleBuffer 


the  length  of  the  wave  table,  and  the  pa  ram2  field  is  a  pointer  to  the  wave-table  data 
itself.  Other  sound  commands  may  interpret  the  6  parameter  bytes  differently  or 
may  not  use  them  at  all. 

Associated  Functions 

SndCall  BackProc  (III — 2147) 

Programming  Info 
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SndDoubleBuffer 


Buffers  between  which  the  Sound  Manager  switches  until  all  sound  data  has  been 
sent  into  the  sound  channel. 

struct  SndDoubleBuffer  { 
long  dbNumFrames ; 

long  dbFlags; 

long  dbtlserInfo[2] ; 

SInt8  dbSoundData[l] ; 

1: 

dbNumFrames 

The  number  of  sound  frames  in  the  buffer, 
db FI  ags 

Status  flags  (see  below), 
dbtlserlnfo 

A  value  that  your  application  can  use  to  store  information. 
dbSoundData 

The  sound  data. 


dbFlags  Constants 

dbBufferReady 

The  buffer  is  ready. 
dbLastBuffer 

This  is  the  last  buffer  of  data. 

Associated  Functions 

SndDoubl  eBackProc  (III — 2148) 

Programming  Info 

C  interface  file:  Sound .  h 


IV-2442 


Inside  QuickTime:  Data  Structures 


SndDoubleBufferHeader 


SndDoubleBufferHeader 


Passes  information  to  SndPl  ayDoubl  eBuf  f  er  (III— 1843). 


struct  SndDoubleBufferHeader  { 


short 

short 

short 

short 

UnsignedFixed 
SndDoubleBufferPtr 
SndDoubl eBackUPP 


dbhNumChannel  s ; 
dbhSampl eSi ze ; 
dbhCompressi  onID; 
dbhPacketSi  ze ; 
dbhSampl eRate ; 
dbhBuf f erPtr[2] ; 
dbhDoubl eBack; 


}; 


dbhNumChannel s 

The  number  of  sound  channels. 
dbhSampl eSi ze 

The  sample  size,  if  sound  is  noncompressed. 
dbhCompressi onID 

The  compression  algorithm  used  on  the  samples  in  the  compressed  sound 
header  (see  below) .  The  constant  fixedCompressionis  available  only  with  Sound 
Manager  versions  3.0  and  later.  If  the  compress!  onID  field  contains  the  value 
f i  xedCompressi  on,  the  Sound  Manager  reads  the  format  field  to  determine  the 
compression  algorithm  used  to  generate  the  compressed  data.  Otherwise,  the 
Sound  Manager  reads  the  compressi  onID  field.  Apple  reserves  the  right  to  use 
compression  IDs  in  the  range  0  through  511.  Currently  the  constant 
vari  abl  eCompressi  on  is  not  used  by  the  Sound  Manager. 
dbhPacketSi ze 

The  size,  in  bits,  of  the  smallest  element  that  a  given  expansion  algorithm  can 
work  with  (see  below).  Beginning  with  Sound  Manager  version  3.0,  you  can 
specify  the  value  0  in  this  field  to  instruct  the  Sound  Manager  to  determine  the 
packet  size  itself. 

dbhSampl eRate 

The  sample  rate. 
dbhBuf ferPtr 

Pointers  to  SndDoubl  eBuf  fer  (IV-2442)  structures. 
dbhDoubl eBack 

Pointer  to  an  SndDoubl  eBackProc  (III— 2148)  callback. 
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compressionID  Constants 

vari abl eCompressi on 

Variable-ratio  compression;  value  is  -2. 
f i xedCompressi on 

Fixed-ratio  compression;  value  is  -1. 
notCompressed 

Uncompressed  samples;  value  is  0. 
threeToOne 

3:1  compressed  samples;  value  is  3. 
sixToOne 

6:1  compressed  samples;  value  is  4. 

Discussion 

The  dbhBuf ferPtr  array  contains  pointers  to  two  structures  of  type  SndDoubl  eBuf  fer 
(IV-2442).  These  are  the  two  buffers  between  which  the  Sound  Manager  switches 
until  all  the  sound  data  has  been  sent  into  the  sound  channel.  When  the  call  to 
SndPlayDoubleBuffer  (III— 1 843)  is  made,  the  two  buffers  should  both  already  contain 
a  nonzero  number  of  frames  of  data. 

Version  Notes 

The  Sound  Manager  defines  SndDoubl  eBufferHeader2  (IV-2444),  identical  to 
SndDoubl  eBufferHeader  except  that  it  contains  the  dbhFormat  field  (of  type  OSType) 
that  defines  a  custom  codec  to  be  used  to  decompress  the  sound  data.  The  dbhFormat 
field  is  used  only  if  the  dbhCompressi  onID  field  of  SndDoubl  eBuf ferHeader2  contains 
the  value  fixedCompression. 

Associated  Functions 

SndPlayDoubleBuffer  (III — 1843) 

Programming  Info 
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See  Also 

See  SndDoubl  eBufferHeader2  (IV-2444). 


SndDoubleBufferHeader2 


Passes  information  to  SndPl  ayDoubl  eBuffer  (III— 1843),  specifying  a  codec. 

struct  SndDoubl eBufferHeader2  { 

short  dbhNumChannel s ; 

short  dbhSampl eSi ze ; 

short  dbhCompressionlD; 


IV-2444 
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short 

Unsi gnedFi xed 
SndDoubleBufferPtr 
SndDoubl eBackUPP 
OSType 


dbhPacketSi ze ; 
dbhSampl eRate ; 
dbhBuf f erPtr[2] ; 
dbhDoubl eBack; 
dbhFormat ; 


dbhNumChannel s 

The  number  of  sound  channels. 
dbhSampl eSi ze 

The  sample  size,  if  sound  is  noncompressed. 
dbhCompressi onID 

The  compression  algorithm  used  on  the  samples  in  the  compressed  sound 
header  (see  below).  The  constant  f  i  xedCompressi  on  is  available  only  with  Sound 
Manager  versions  3.0  and  later.  If  the  compressi  onID  field  contains  the  value 
f  i  xedCompressi  on,  the  Sound  Manager  reads  the  format  field  to  determine  the 
compression  algorithm  used  to  generate  the  compressed  data.  Otherwise,  the 
Sound  Manager  reads  the  compressi  onID  field.  Apple  reserves  the  right  to  use 
compression  IDs  in  the  range  0  through  511.  Currently  the  constant 
vari  abl  eCompressi  on  is  not  used  by  the  Sound  Manager. 
dbhPacketSi ze 

The  size,  in  bits,  of  the  smallest  element  that  a  given  expansion  algorithm  can 
work  with  (see  below).  Beginning  with  Sound  Manager  version  3.0,  you  can 
specify  the  value  0  in  this  field  to  instruct  the  Sound  Manager  to  determine  the 
packet  size  itself. 
dbhSampl eRate 

The  sample  rate. 
dbhBuf ferPtr 

Pointers  to  SndDoubl  eBuffer  (IV-2442)  structures. 
dbhDoubl eBack 

Pointer  to  an  SndDoubl  eBackProc  (III— 2148)  callback. 
dbhFormat 

A  sound  compression  format;  see  "Codec  Identifiers"  (IV-2655).  This  field  is 
used  only  if  the  dbhCompressi  onID  field  contains  the  value  fi xedCompressi  on. 

compressionID  Constants 

vari abl eCompressi on 

Variable-ratio  compression;  value  is  -2. 
fi xedCompressi on 

Fixed-ratio  compression;  value  is  -1. 
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notCompressed 

Uncompressed  samples;  value  is  0. 
threeToOne 

3:1  compressed  samples;  value  is  3. 
sixToOne 

6:1  compressed  samples;  value  is  4. 

Discussion 

The  dbhBuf  ferPtr  array  contains  pointers  to  two  structures  of  type  SndDoubl  eBuf fer 
(IV-2442).  These  are  the  two  buffers  between  which  the  Sound  Manager  switches 
until  all  the  sound  data  has  been  sent  into  the  sound  channel.  When  the  call  to 
SndPl  ayDoubl  eBuffer  (III— 1 843)  is  made,  the  two  buffers  should  both  already  contain 
a  nonzero  number  of  frames  of  data. 

Version  Notes 

SndDoubl  eBufferHeader  (IV-2443)  is  identical  to  SndDoubl  eBufferHeader2  except  that 
it  lacks  the  dbhFormat  field. 

Programming  Info 
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See  Also 

See  SndDoubl  eBufferHeader  (IV-2443). 


SndlnputCmpParam 

Provides  data  for  the  SndlnputReadSync  (III— 1837)  and  SndlnputReadAsync  (III— 1836) 
functions. 

struct  SndlnputCmpParam  { 

SICCompI etionProcPtr 
SI  InterruptProcPtr 
OSErr 
short 

unsigned  long 
unsigned  long 
Ptr 
Ptr 

1: 

i oCompl eti on 

Pointer  to  a  SICCompI  eti  onProc  (III— 2146)  callback. 


i oCompl eti on  ; 
i olnterrupt ; 
i  oResul  t ; 
pad ; 

i oReqCount ; 
i oActCount ; 
i oBuffer ; 
i oMi sc ; 
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i olnterrupt 

Pointer  to  a  SI  InterruptProc  (III— 2147)  callback, 
i  oResul  t 

I/O  result  error  code, 
pad 

Not  used, 
i oReqCount 

Undocumented 
i oActCount 

Undocumented 
i oBuf fer 

Undocumented 
i oMi sc 

Undocumented 

Associated  Functions 

SICCompI  eti  onProc  (III — 2146) 

Programming  Info 
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SndListResource 


Holds  a  sound  resource  containing  sampled  sound. 


struct  SndListRes 
short 
short 
ModRef 
short 

SndCommand 

UInt8 

}; 


ource  { 
format ; 
numModi f i ers  ; 
modi f i erPart[l] ; 
numCommands ; 
commandPart[l] ; 
dataPart[l] ; 


format 

Undocumented 
numModi f i ers 

Undocumented 
modi f i erPart 

Undocumented 
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numCommands 

Undocumented 

commandPart 

Undocumented 

dataPart 

Undocumented 

Programming  Info 
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SoundComponentData 


Contains  information  about  the  sound  format  in  a  compressed  sound  file. 


struct  SoundComponentData  { 


I  ong 
OSType 
short 
short 

Unsi gnedFi xed 
1  ong 
Byte  * 

1  ong 


fl ags ; 
format ; 
numChannel s ; 
sampl eSi ze ; 
sampl eRate ; 
sampl eCount ; 
buffer ; 
reserved ; 


}; 


fl  ags 

Normally  set  to  0. 
format 

The  sound  format;  see  "Sound  Formats"  (IV-2692). 
numChannel s 

The  number  of  channels;  1  =  mono,  2  =  stereo, 
sampl eSi ze 

The  sample  size  (i.e.,  8  =  8-bit,  16  =  16-bit), 
sampl eRate 

The  sampling  rate  in  samples  per  second, 
sampl eCount 

The  number  of  audio  samples  in  the  file, 
buffer 

Set  to  0. 
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reserved 
Set  to  0. 

Associated  Functions 

OpenMi  xerSoundComponent  (11-1132) 

Programming  Info 
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SoundComponentLink 


Describes  a  sound  component. 

struct  SoundComponentLink  { 

ComponentDescri pti on  descri pti on  ; 
SoundSource  mixerlD; 

SoundSource  *  linkID; 

}; 

descri pti on 

Describes  the  sound  component, 
mixer  ID 

Reserved;  do  not  use. 

1 inkID 

Reserved;  do  not  use. 
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SoundDescription 


Describes  the  format  of  a  collection  of  audio  samples, 
struct  SoundDescription  { 


1  ong 

descSi ze ; 

1  ong 

dataFormat; 

1  ong 

resvdl ; 

short 

resvd2 ; 

short 

dataRef Index 

short 

versi on ; 

short 

revl evel  ; 

1  ong 

vendor ; 

short 

numChannel s ; 
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short  sampleSize; 

short  comp  res si  on  ID ; 

short  packetSize; 

Unsi gnedFi xed  sampleRate; 

}; 

descSi ze 

Defines  the  total  size,  in  bytes,  of  this  structure. 
dataFormat 

Describes  the  format  of  the  sound  data;  see  "Sound  Formats"  (IV-2692).  Some 
older  movie  files  sometimes  have  a  0  value  in  this  field.  You  should  assume  that 
this  is  the  same  as  the  'raw  '  value, 
resvdl 

Reserved;  set  to  0. 
resvd2 

Reserved;  set  to  0. 
dataRef Index 

Reserved;  set  to  0. 
versi on 

Reserved;  set  to  0. 
revLevel 

Reserved;  set  to  0. 
vendor 

Reserved;  set  to  0. 
numChannel s 

Indicates  the  number  of  sound  channels  used  by  the  sound  sample.  Set  this  field 
to  1  for  monaural  sounds;  set  it  to  2  for  stereo  sounds. 

sampl eSi ze 

Specifies  the  number  of  bits  in  each  sound  sample.  Set  this  field  to  8  for  8-bit 
sound;  set  it  to  16  for  16-bit  sound, 
compressi onID 

Reserved;  set  to  0. 
packetSi ze 

Reserved;  set  to  0. 
sampl eRate 

Indicates  the  rate  at  which  the  sound  samples  were  obtained.  Sound  media 
handlers  use  this  value  to  influence  the  natural  playback  speed  of  the  sound 
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described  by  this  sound  description  structure.  This  field  contains  an  unsigned 
fixed-point  number  that  specifies  the  number  of  samples  collected  per  second. 

Associated  Functions 

AddSoundDescri  pti  onExtensi  on  (1-40) 

Programming  Info 

C  interface  file:  Movl  es  .  h 

See  Also 

For  an  extension  to  this  structure,  see  the  'flap'  (IV-2537)  atom. 
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SoundDescriptionVl 


Version  1  extension  of  the  SoundDescri  pti  on  (IV-2449)  structure. 


struct  SoundDescriptionVl  { 


SoundDescri pti on 
unsigned  long 
unsigned  long 
unsigned  long 
unsigned  long 


}; 


desc ; 

sampl esPerPacket; 
bytesPerPacket; 
bytesPerFrame; 
bytesPerSampl  e; 


desc 

A  SoundDescri  pti  on  (IV-2449)  structure, 
sampl esPerPacket 

The  number  of  samples  in  each  packet. 
bytesPerPacket 

The  number  of  bytes  in  each  packet. 
bytesPerFrame 

The  number  of  bytes  in  each  frame. 
bytesPerSampl e 

The  number  of  bytes  in  each  sample. 

Discussion 

This  structure  is  a  superset  of  the  SoundDescri  pti  on  (IV-2449)  structure.  The  added 
fields  are  taken  directly  from  the  Compressi  onlnfo  (IV-2222)  structure  currently 
used  by  the  Sound  Manager  to  describe  the  compression  ratio  of  fixed  ratio  audio 
compression  algorithms.  The  fields  have  been  added  to  support  compression 
algorithms  which  can  be  run  at  different  compression  ratios  and  to  support  more 
generic  parsing  of  QuickTime  sound  tracks.  They  are  described  in  detail  in  Inside 
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Macintosh:  Sound  (listed  in  the  bibliography).  If  these  fields  are  not  used,  they  are 
set  to  0.  File  readers  only  need  to  check  to  see  if  sampl  es  Per  Packet  is  0. 

Programming  Info 

C  interface  file:  Movi  es .  h 


See  Also 


See  SoundDescri  pti  on  (IV-2449). 


SoundHeader 


Describes  a  set  of  sound  samples. 

struct  SoundHeader  { 

Ptr 

unsigned  long 
Unsi gnedFi xed 
unsigned  long 
unsigned  long 
UInt8 
UInt8 
UInt8 

1: 

sampl ePtr 

Pointer  to  sound  samples;  if  NIL,  then  samples  are  in  sampl  eArea. 
1 ength 

Length  of  sound  samples  in  bytes, 
sampl eRate 

Sample  rate  for  this  sound. 

1 oopStart 

Start  of  looping  portion. 

1 oopEnd 

End  of  looping  portion, 
encode 

Header  encoding. 
baseFrequency 

The  pitch  of  the  original  sampled  sound, 
sampl eArea 

Space  for  when  samples  follow  directly. 


sampl ePtr ; 

1 ength ; 
sampl eRate ; 

1 oopStart ; 

1 oopEnd ; 
encode ; 

baseFrequency ; 
sampl eArea[l] ; 
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Programming  Info 

C  interface  file:  Sound .  h 


SoundlnfoList 


Passes  information  to  SoundComponentGetlnfo  (III— 1849)  or  SoundComponentSetlnfo 
(III— 1856). 

struct  SoundlnfoList  { 
short  count; 

Handle  infoHandle; 

}; 

count 

The  number  of  elements  in  the  array  referenced  by  i  nf  oHandl  e.  It  is  your 
component's  responsibility  to  allocate  the  block  of  data  referenced  by  that 
handle,  but  it  is  the  caller's  responsibility  to  dispose  of  that  handle  once  it  is 
finished  with  it. 

i nf oHandl e 

A  handle  to  an  array  of  data  elements.  The  type  of  these  data  elements  depends 
on  the  kind  of  information  requested,  which  is  determined  by  the  sel  ector 
parameter  passed  to  SoundComponentGetlnfo  or  SoundComponentSetlnfo. 

Discussion 

This  structure  consists  of  a  count  and  a  handle  to  a  variable-sized  array.  The  data 
type  of  the  array  elements  depends  on  the  kind  of  information  being  returned. 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

See  SoundComponentGetlnfo  (III — 1849)  and  SoundComponentSetlnfo  (III — 1856). 


STR 


SoundMedialnfoHeader 


Contains  sound  stereo  balance  information. 

struct  SoundMedialnfoHeader  { 
long  flags; 

short  balance; 

short  rsrvd; 
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fl  ags 

One  byte  of  version  information  followed  by  three  bytes  of  flags.  The  flags 
bytes  are  not  currently  used, 
bal ance 

Specifies  the  mix  of  sound  between  two  stereo  speakers,  with  a  range  of  -1.0  to 
+1.0.  The  high  8  bits  contain  the  integer  part;  the  low  8  bits  contain  the  fractional 
part.  Negative  values  emphasize  the  left  channel  and  positive  values  the  right 
channel.  This  field  is  normally  set  to  0  for  even  balance. 

rsrvd 

Reserved;  set  to  0. 

Programming  Info 

C  interface  file:  MoviesFormat.h 

See  Also 

For  the  atom  structure  that  contains  the  SoundMedialnfoHeader  data  structure,  see 
' smhd '  (IV-2584). 

SoundParamBlock 

Describes  the  source  data  to  be  modified  or  sent  to  a  sound  output  device. 

struct  SoundParamBlock  { 

1  ong 

SoundComponentData 
Unsi gnedFi xed 
short 
short 
1  ong 

Componentlnstance 
SoundParamUPP 
SoundParamUPP 
1  ong 
short 


recordSi ze 

The  length,  in  bytes,  of  the  sound  parameter  block. 

desc 

A  SoundComponentData  (IV-2448)  structure  that  describes  the  format,  size,  and 
location  of  the  sound  data. 


recordSi ze ; 
desc ; 

rateMul ti pi i er ; 
1 eftVol ume ; 
ri ghtVol ume ; 
qual i ty ; 
filter: 
moreRtn ; 
compl eti onRtn ; 
refCon ; 
resul t ; 
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rateMul ti pi i er 

A  multiplier  to  be  applied  to  the  playback  rate  of  the  sound.  This  field  contains 
an  unsigned  fixed-point  number.  If,  for  example,  this  field  has  the  value  2.0,  the 
sound  is  played  back  at  twice  the  rate  specified  in  the  sampl  eRate  field  of  the 
SoundComponentData  structure  contained  in  the  desc  field. 

1 eftVol ume 

The  playback  volume  for  the  left  channel.  You  specify  a  volume  with  a  16-bit 
value,  where  0x0000  represents  no  volume  and  0x0100  represents  full  volume. 
You  can  overdrive  a  channel's  volume  by  passing  volume  levels  greater  than 
0x0100. 

ri ghtVol ume 

The  playback  volume  for  the  right  channel.  You  specify  a  volume  with  a  16-bit 
value,  where  0x0000  represents  no  volume  and  0x0100  represents  full  volume. 
You  can  overdrive  a  channel's  volume  by  passing  volume  levels  greater  than 
0x0100. 
quality 

The  level  of  quality  for  the  sound.  This  value  usually  determines  how  much 
processing  should  be  applied  during  audio  data  processing  (such  as  rate 
conversion  and  decompression)  to  increase  the  output  quality  of  the  sound, 
filter 

Reserved  for  future  use.  You  should  set  this  field  to  NIL. 
moreRtn 

A  pointer  to  a  SoundParamProc  (III— 2149)  callback  that  is  called  to  retrieve 
another  buffer  of  audio  data.  This  field  is  used  internally  by  the  Sound 
Manager, 
compl eti onRtn 

A  pointer  to  a  SoundParamProc  (III— 2149)  callback  that  is  called  when  the  sound 
has  finished  playing.  This  field  is  used  internally  by  the  Sound  Manager. 
refCon 

A  value  that  is  to  be  passed  to  the  callback  routines  specified  in  the  moreRtn  and 
compl  eti  onRtn  fields.  You  can  use  this  field  to  pass  information  (for  example, 
the  address  of  a  structure)  to  a  callback  routine. 

resul t 

The  status  of  the  sound  that  is  playing.  The  value  1  indicates  that  the  sound  is 
currently  playing.  The  value  0  indicates  that  the  sound  has  finished  playing. 
Any  negative  value  indicates  that  some  error  has  occurred. 

Associated  Functions 

SoundComponentPl  aySourceBuf  f  er  (ill-1854) 
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SoundSlopeAndlnterceptRecord 


Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

See  SoundComponentData  (IV-2448). 


SoundSlopeAndlnterceptRecord 


Provides  floating-point  conversion  variables  for  a  'flap'  (IV-2537)  atom. 

struct  SoundSlopeAndlnterceptRecord  { 

Float64  slope; 

Float64  intercept; 

Float64  minClip; 

Float64  maxClip; 

}; 

si  ope 

Undocumented 

i ntercept 

Undocumented 

mi nCl  i  p 

Undocumented 

maxCl i p 

Undocumented 


Programming  Info 

C  interface  file:  Sound .  h 


See  Also 

See  'flap'  (IV-2537). 


SPB 


Passes  information  to  low-level  sound  input  functions. 


struct  SPB  { 

1  ong 

unsigned  long 
unsigned  long 
unsigned  long 
Ptr 

SICompI eti onUPP 


i nRef Num ; 
count ; 

mi  1 1 i seconds ; 
bufferLength ; 
bufferPtr ; 
compl eti onRouti ne ; 
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SI  I  interrupt  UPP  interrupt  Routine; 

long  userLong; 

OSErr  error; 

long  unusedl; 

}; 

i nRef Num 

The  reference  number  of  the  sound  input  device  from  which  recording  is  to 
occur, 
count 

The  number  of  bytes  to  record.  After  recording  finishes,  the  count  field 
indicates  the  number  of  bytes  actually  recorded, 
mi  1 1 i seconds 

The  number  of  milliseconds  to  record.  If  the  count  and  milliseconds  fields  do 
not  agree,  then  the  field  that  specifies  the  longer  recording  time  is  used.  After 
recording  finishes,  the  milliseconds  field  indicates  the  number  of  milliseconds 
actually  recorded. 

but f erLength 

The  length  in  bytes  of  the  buffer  into  which  the  recorded  sound  data  is  to  be 
placed.  If  the  buffer  is  shorter  than  the  recording  time,  then  the  recording  time 
is  truncated  so  that  the  recorded  data  can  fit  into  the  buffer, 
buf f erPtr 

A  pointer  to  the  buffer  to  store  sound  data  in. 
comp! eti onRouti ne 

Pointer  to  an  SICompI  eti  onProc  (III— 2146)  callback, 
i nterruptRouti ne 

Pointer  to  an  SI  InterruptProc  (III— 2147)  callback. 
userLong 

A  long  integer  for  your  application's  use.  You  can  use  this  field,  for  instance,  to 
pass  a  handle  to  an  application-defined  structure  to  the  sound  input 
completion  or  interrupt  routine, 
error 

Contains  a  value  greater  than  0  while  recording  unless  an  error  occurs,  in  which 
case  it  contains  a  value  less  than  0.  Your  application  can  poll  this  field  to  check 
on  the  status  of  an  asynchronous  recording.  If  recording  terminates  without  an 
error,  this  field  contains  0.  See  "Error  Codes"  (IV-2663). 

unusedl 

Reserved;  set  to  0. 
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Associated  Functions 

SICompI  eti  onProc  (III — 2146) 

Programming  Info 

C  interface  file:  Sound .  h 

See  Also 

For  a  function  that  uses  this  structure,  see  SPBRecord  (III— 1878). 


SpriteDescription 


Provides  information  to  compress  a  sprite  using  a  data  compression  codec, 
struct  SpriteDescription  { 


1  ong 

descSi ze ; 

1  ong 

dataFormat ; 

1  ong 

resvdl ; 

short 

resvd2 ; 

short 

dataRef Index ; 

1  ong 

versi on ; 

OSType 

decompressorType 

1  ong 

sampl eFl ags ; 

}; 

descSi ze 

The  total  size  of  the  Spri  teDescri  pti  on  structure,  including  extra  data. 
dataFormat 

Undocumented 

resvdl 

Reserved;  do  not  use. 
resvd2 

Reserved;  do  not  use. 
dataRef Index 

Undocumented 
versi on 

Undocumented 

decompressorType 

A  data  decompressor  component  type,  or  0  for  no  decompression;  see  "Codec 
Identifiers"  (IV-2655).  If  this  field  is  nonzero,  a  component  of  the  specified  type 
is  used  to  decompress  the  sprite  sample  when  it  is  loaded. 
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sampl  e FI  ags 

Undocumented 

Programming  Info 

C  interface  file:  Movi  es  .  h 


SpriteRecord 


Contains  a  sprite. 

struct  SpriteRecord  { 
long  data [ 1 ] ; 

}; 

data 

An  array  of  sprite  data. 

Programming  Info 

C  interface  file:  Movi  es  .  h 
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SpriteWorldRecord 


Contains  a  sprite  world. 

struct  SpriteWorldRecord  { 
long  data [ 1 ] ; 

}; 

data 

An  array  of  sprite  world  data. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


SProcRec 


A  link  in  a  list  that  begins  with  the  gdSearchProc  field  of  the  GDevi  ce  (IV-2264) 
structure. 

struct  SProcRec  { 

Handle  nxtSrch; 

Col orSearchUPP  srchProc; 
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SSpLocalizationData 


}; 

nxtSrch 

A  handle  to  next  SProcRec  structure. 
srchProc 

Pointer  to  a  custom  search  procedure;  see  Advanced  Color  Imaging  on  the  Mac  OS 
(listed  in  the  bibliography).  Chapter  7. 

Programming  Info 

C  interface  file:  Quickdraw.h 


SSpLocalizationData 


Provides  a  format  for  sound  localization  data, 
struct  SSpLocalizationData  { 


UInt32 

cpuLoad ; 

UInt32 

medi urn ; 

f  1  oat 

humi di ty ; 

f  1  oat 

roomSi ze ; 

f  1  oat 

roomRef 1 ecti vi ty ; 

f  1  oat 

reverbAttenuati on ; 

UInt32 

sourceMode ; 

f  1  oat 

referenceDi stance; 

f  1  oat 

coneAngl eCos ; 

f  1  oat 

coneAttenuati on ; 

SSpLocati onData 

currentLocati on ; 

UInt32 

reservedO ; 

UInt32 

reservedl ; 

UInt32 

reserved2 ; 

UInt32 

reserved3 ; 

UInt32 

virtual SourceCount; 

SSpVirtual Source Data 

vi rtual Source[4] ; 

}; 

cpuLoad 

CPU  load  versus  quality;  0  is  best, 
medi urn 

Medium  for  sound  propagation, 
humi di ty 

Humidity  when  medi  urn  is  air. 
roomSi ze 

Reverberation  model:  distance  between  walls. 
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roomRef 1 ecti vi ty 

Reverberation  model:  bounce  attenuation. 
reverbAttenuati on 

Reverberati  on  model:  mix  level. 
sourceMode 

Type  of  filtering  to  apply. 
referenceDi stance 

Nominal  distance  for  recording. 
coneAngl eCos 

Cos  (angle/2)  of  attenuation  cone. 
coneAttenuati on 

Attenuation  outside  the  cone. 
currentLocati on 

Location  of  the  sound. 
reservedO 

Reserved;  set  to  0. 
reservedl 

Reserved;  set  to  0. 
reserved2 

Reserved;  set  to  0. 
reserved3 

Reserved;  set  to  0. 
vi rtual SourceCount 

Number  of  reflections, 
vi rtual Source 

The  reflections. 

Programming  Info 

C  interface  file:  SoundSprocket.  h 
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StandardFileReply 


Returns  the  results  of  user  actions  in  the  Standard  File  dialog  box. 

struct  StandardFileReply  { 

Boolean  sfGood; 

Boolean  sfReplacing; 
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OSType 
FSSpec 
Seri ptCode 
short 
Bool ean 
Bool ean 
1  ong 
short 

}; 

sfGood 

Whether  or  not  the  reply  record  is  valid;  that  is,  whether  your  application  can 
use  the  information  in  the  other  fields.  The  field  is  set  to  TRUE  after  the  user 
clicks  Save  or  Open,  and  to  FALSE  after  the  user  clicks  Cancel, 
sf Repl aci ng 

Whether  or  not  a  file  to  be  saved  replaces  an  existing  file  of  the  same  name. 
Your  application  can  use  the  value  of  this  field  instead  of  checking  for  and 
handling  name  conflicts  itself. 

sfType 

The  file  type;  see  "File  Types  and  Creators"  (IV-2668). 
s  f  F  i  1  e 

The  file  or  folder  selected  by  the  user.  If  the  selected  file  is  a  stationery  pad,  the 
FSSpec  describes  the  file  itself,  not  a  copy  of  the  file. 
sfScri pt 

The  file's  script  code;  see  "Localization  Codes"  (IV-2673). 
sf  FI  ags 

Mac  OS  Finder  flags  for  the  selected  file  or  folder, 
sf IsFol der 

TRUE  if  the  selected  item  is  a  folder, 
sf IsVol ume 

TRUE  if  the  selected  item  is  a  volume, 
sf Reservedl 

Reserved;  do  not  use. 
sf Reserved2 

Reserved;  do  not  use. 


sfType ; 
s  f  F  i  1  e ; 
sfScri pt ; 
sf  FI  ags  ; 
sf IsFol der ; 
sf IsVol ume ; 
sf Reservedl ; 
sf Reserved2 ; 


Discussion 

The  Standard  File  Package  fills  in  the  reply  record  and  returns  when  the  user 
completes  one  of  its  dialog  boxes,  either  by  selecting  a  file  and  clicking  Save  or 
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Open,  or  by  clicking  Cancel.  Your  application  checks  the  values  in  the  reply  record 
to  see  what  action  to  take,  if  any. 

Associated  Functions 

CustomGetFi  1  ePrevi ew  (1-163) 

Programming  Info 

C  interface  file:  StandardFile.h 

See  Also 

See  Inside  Macintosh:  Files  (listed  in  the  bibliography). 


STR 


StateBlock 


Provides  information  for  the  stateVars  field  of  a  CmpSoundHeader  (IV-2176) 
structure. 

struct  StateBlock  { 

short  stateVar[64] ; 

}; 

stateVar 

An  array  of  integers.  This  field  contains  state  variables  that  need  to  be 
preserved  across  invocations  of  the  compression  algorithm.  The  size  of  this 
field  is  defined  by  a  constant  (see  below). 

stateVar  Size  Constant 

stateBl ockSi ze 
Value  is  64. 

Associated  Functions 

Comp3tol  (1-104) 

Programming  Info 

C  interface  file:  Sound .  h 


StringRangeRecord 


Undocumented 

struct  StringRangeRecord  { 
long  maxChars; 

long  maxLines; 

1; 
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maxChars 

The  maximum  length  of  the  string. 
maxLi nes 

The  number  of  editing  lines  to  use  (1  typical,  0  to  default). 

Programming  Info 

C  interface  file:  ImageCodec.  h 


SynthesizerConnections 


Describes  how  a  MIDI  device  is  connected  to  the  user's  computer, 
struct  SynthesizerConnections  { 


OSType 

cl i entID ; 

OSType 

i nputPortID ; 

OSType 

outputPortID 

1  ong 

mi di Channel  ; 

1  ong 

fl ags ; 

1  ong 

unique ; 

1  ong 

reservedl ; 

1  ong 

reserved2 ; 

I: 

cl i entID 

The  client  ID  provided  by  the  MIDI  Manager,  or  '  OMS  '  for  an  OMS  port, 
i nputPortID 

The  ID  provided  by  the  MIDI  Manager  or  OMS  for  the  port  used  to  SEND  to 
the  MIDI  synthesizer. 
outputPortID 

The  ID  provided  by  the  MIDI  Manager  or  OMS  for  the  port  that  RECEIVES 
from  a  keyboard  or  other  control  device, 
mi di Channel 

The  system  MIDI  channel  or,  for  a  hardware  device,  the  slot  number, 
fl  ags 

Constants  (see  below)  that  provide  information  about  the  type  of  connection, 
unique 

A  unique  ID  you  can  use  instead  of  an  index  to  identify  the  synthesizer  to  the 
note  allocator, 
reservedl 

Reserved.  Set  to  0. 
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reserved2 

Reserved.  Set  to  0. 

flags  Constants 

kSynthesi zerConnecti onMono 

If  set,  and  the  synthesizer  can  be  both  monophonic  and  polyphonic,  the 
synthesizer  is  instructed  to  take  up  its  channels  sequentially  from  the  system 
channel  in  monophonic  mode. 

kSynthesi zerConnecti onMMgr 

This  connection  is  imported  from  the  MIDI  Manager. 
kSynthesi zerConnecti onOMS 

This  connection  is  imported  from  the  Open  Music  System  (OMS). 
kSynthesi zerConnecti onQT 

This  connection  is  a  QuickTime-only  port. 
kSynthesi zerConnecti onFMS 

This  connection  is  imported  from  the  FreeMIDI  system. 

Associated  Functions 

NAGetDefaui  tMIDI  Input  (11-1023) 

Programming  Info 

C  interface  file:  QuickTimeMusic.h 
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SynthesizerDescription 


Contains  information  about  a  synthesizer, 
struct  SynthesizerDescription  { 


OSType 

synthesi zerType ; 

Str31 

name ; 

unsi gned 

1  ong 

fl ags ; 

unsi gned 

1  ong 

voi ceCount ; 

unsi gned 

1  ong 

partCount; 

unsi gned 

1  ong 

i nstrumentCount ; 

unsi gned 

1  ong 

modi f i a  b  1  el nstrumentCount ; 

unsi gned 

1  ong 

channel  Mask; 

unsi gned 

1  ong 

drumPartCount; 

unsi gned 

1  ong 

drumCount ; 

unsi gned 

1  ong 

modi f i abl eDrumCount ; 

unsi gned 

1  ong 

drumChannel Mask; 

unsi gned 

1  ong 

outputCount ; 

unsi gned 

1  ong 

1 atency ; 

unsi gned 

1  ong 

control  1 ers [4] ; 

unsi gned 

1  ong 

gmlnstruments[4] ; 
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unsigned  long  gmDrurris[4]  ; 

}; 

synthesi zerType 

The  synthesizer  type.  This  is  the  same  as  the  music  component  subtype. 

name 

Text  name  of  the  synthesizer  type, 
fl  ags 

Constants  (see  below)  that  provide  information  about  how  the  synthesizer 
works. 

voi ceCount 

Maximum  polyphony. 
partCount 

Maximum  multi-timbrality  (and  MIDI  channels), 
i nstrumentCount 

The  number  of  built-in  ROM  instruments.  This  does  not  include  General  MIDI 
instruments. 

modi f i abl el nstrumentCount 

The  number  of  slots  available  for  saving  user-modified  instruments, 
channel  Mask 

Which  channels  a  MIDI  device  always  uses  for  instruments.  Set  to  OxFFFF  for  all 
channels. 
drumPartCount 

The  maximum  multi-timbrality  of  drum  parts.  For  synthesizers  where  drum 
kits  are  separated  from  instruments. 

drumCount 

The  number  of  built-in  ROM  drum  kits.  This  does  not  include  General  MIDI 
drum  kits.  For  synthesizers  where  drum  kits  are  separated  from  instruments, 
modi fi abl eDrumCount 

The  number  of  slots  available  for  saving  user-modified  drum  kits.  For  MIDI 
synthesizers  where  drum  kits  are  separated  from  instruments. 
drumChannel Mask 

Which  channels  a  MIDI  device  always  uses  for  drum  kits.  Set  to  FFFF  for  all 
channels. 

outputCount 

The  number  of  audio  outputs.  This  is  usually  2. 
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1 atency 

The  response  time  in  microseconds, 
control  1 ers 

An  array  of  128  bits  identifying  the  available  controllers;  see  "Music 
Controllers"  (IV-2682).  Bits  are  numbered  from  1  to  128,  starting  with  the  most 
significant  bit  of  the  long  word  and  continuing  to  the  least  significant  of  the  last 
bit. 

gmlnstruments 

An  array  of  128  bits  giving  the  available  General  MIDI  instruments. 
gmDrums 

An  array  of  128  bits  giving  the  available  General  MIDI  drum  kits. 

flags  Constants 

kSynthesi zerDynami cVoi  ce 

Voices  can  be  assigned  to  parts  on  the  fly  with  this  synthesizer  (otherwise, 
polyphony  is  very  important). 

kSynthesi  zerllsesMIDIPort 

This  synthesizer  must  be  patched  through  a  MIDI  system,  such  as  the  MIDI 
Manager  or  OMS. 
kSynthesi zerMi crotone 

This  synthesizer  can  play  microtonal  scales. 
kSynthesi zerHasSampl  es 

This  synthesizer  has  some  use  for  sampled  audio  data. 
kSynthesi zerMi xedDrums 

Any  part  of  this  synthesizer  can  play  drum  parts. 
kSynthesi zerSoftware 

This  synthesizer  is  implemented  in  main  CPU  software  and  uses  CPU  cycles. 
kSynthesi zerHardware 

This  synthesizer  is  a  hardware  device,  not  a  software  synthesizer  or  MIDI 
device. 

kSynthesi zerDynami cChannel 

This  synthesizer  can  move  any  part  to  any  channel  or  disable  each  part.  For 
devices  only. 

kSynthesi zerHogsSystemChannel 

Even  if  the  kSynthesi  zerDynami  cChannel  bit  is  set,  this  synthesizer  always 
responds  on  its  system  channel.  For  MIDI  devices  only. 
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kSynthesi zerSl owSetPart 

This  synthesizer  does  not  respond  rapidly  to  the  various  set  part  and  set  part 
instrument  calls. 
kSynthesi zerOff 1 i ne 

This  synthesizer  can  enter  an  offline  synthesis  mode. 
kSynthesi zerGM 

This  synthesizer  is  a  General  MIDI  device. 

Associated  Functions 

Musi  cGetDescri  pti  on  (11-986) 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 


TCT  extOptions 


Holds  text  font  and  style  information, 
struct  TCTextOptions  { 


short 

txFont ; 

short 

txFace ; 

short 

txSi ze ; 

short 

pad ; 

RGBCol or 

foreCol or ; 

RGBCol or 

backCol or ; 

1: 

txFont 

Specifies  the  number  of  the  font. 
txFace 

Specifies  the  font's  style  (bold,  italic,  and  so  on). 
txSi ze 

Specifies  the  font's  size. 

pad 

Unused  field  to  make  structure  long- word  aligned. 
foreCol or 

Specifies  the  foreground  color. 
backCol or 

Specifies  the  background  color. 
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TCGetDi  spl  ayOpti  ons  (III — 1918) 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 


TERec 


Contains  display,  storage,  styling,  and  other  information  for  text  editing. 


struct  TERec  { 

Rect 

destRect ; 

Rect 

vi ewRect ; 

Rect 

sel Rect ; 

short 

1 i neHei ght ; 

short 

f ontAscent ; 

Poi  nt 

sel  Poi  nt ; 

short 

sel Start; 

short 

sel End ; 

short 

acti ve ; 

WordBreakUPP 

wordBreak; 

TEC1 i ckLoopUPP 

cl i ckLoop ; 

1  ong 

cl  i  ckT i  me ; 

short 

cl i ckLoc ; 

1  ong 

caretTime; 

short 

caretState; 

short 

just; 

short 

teLength ; 

Handl e 

hText ; 

1  ong 

h  D i spatchRec ; 

short 

cl i kStuf f ; 

short 

crOnly ; 

short 

txFont ; 

Styl eFi el d 

txFace ; 

short 

txMode ; 

short 

txSi ze ; 

GrafPtr 

i nPort ; 

Hi ghHookUPP 

hi ghHook; 

CaretHookUPP 

caretHook; 

short 

nLi  nes ; 

short 

1 i neStarts [16001] 

}; 


destRect 

The  destination  rectangle,  in  local  coordinates. 
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vi ewRect 

The  view  rectangle,  in  local  coordinates, 
sel Rect 

The  selection  rectangle,  whose  boundaries  are  defined  in  local  coordinates.  This 
value  is  the  current  selection  range  or  insertion  point. 

1 i neHei ght 

The  vertical  spacing  of  lines  of  text.  Vertical  spacing  may  be  fixed  or  it  may  vary 
from  line  to  line,  depending  upon  specific  text  attributes.  If  the  value  of 
1  i  neHei  ght  is  greater  than  0,  this  field  specifies  the  fixed  vertical  distance  from 
the  ascent  line  of  one  line  of  text  down  to  the  ascent  line  of  the  next.  If  the  value 
of  1  i  neHei  ght  is  less  than  1,  then  this  field  specifies  the  vertical  distance  from 
the  ascent  line  of  one  line  of  text  down  to  the  ascent  line  of  the  next  calculated 
independently  for  each  line,  based  on  the  maximum  value  for  any  individual 
character  attribute  on  that  line. 
fontAscent 

The  font  ascent  line.  If  the  value  of  fontAscent  is  greater  than  0,  this  field 
specifies  how  far  above  the  base  line  the  pen  is  positioned  to  begin  drawing  the 
caret  or  highlighting.  For  single-spaced  text,  this  is  the  height  of  the  text  in 
pixels  (the  height  of  the  tallest  characters  in  the  font  from  the  base  line).  If  the 
value  of  fontAscent  is  less  than  1,  this  field  specifies  the  font  ascent  calculated 
independently  for  each  line,  based  on  maximum  value  for  any  individual 
character  attribute  on  that  line, 
sel Poi nt 

The  point  selected  with  the  mouse,  in  the  local  coordinates  of  the  current 
graphics  port.  The  assembly-language  offset  for  this  field  is  named  teSel  Point. 

sel Start 

The  byte  offset  of  the  beginning  of  a  selection  range.  Note  that  byte  offset  0 
refers  to  the  first  byte  in  the  text  buffer, 
sel End 

The  byte  offset  of  the  end  of  a  selection  range.  To  include  that  byte,  this  value 
must  be  1  greater  than  the  position  of  the  last  byte  offset  of  the  text, 
acti ve 

Used  internally. 
wordBreak 

The  record's  word  selection  break  routine.  This  routine  determines  the  word 
that  is  highlighted  when  the  user  double-clicks  in  the  text  and  the  position  at 
which  text  is  wrapped  at  the  end  of  a  line. 
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cl i ckLoop 

The  pointer  to  the  click  loop  routine.  The  specified  click  loop  routine  is  called 
repeatedly  as  long  as  the  mouse  button  is  held  down  within  the  text, 
cl  i  ckT i  me 

Used  internally, 
cl i ckLoc 

Used  internally. 
caretTime 

Used  internally. 
caretState 

Used  internally. 

just 

The  type  of  text  alignment:  default  (according  to  the  primary  line  direction), 
left,  center,  or  right. 
teLength 

The  number  of  bytes  in  the  text  to  be  edited.  For  two-byte  systems,  potentially 
twice  the  number  of  characters.  Initially  set  to  zero.  The  maximum  length  is 
32767  bytes. 
hText 

A  handle  to  the  text.  Initially,  it  points  to  a  zero-length  block  of  text  in  the  heap, 
h  D i spatchRec 

Used  internally, 
cl i kStuf f 

Used  internally. 
crOnly 

A  value  specifying  whether  or  not  text  wraps  at  the  right  edge  of  the  destination 
rectangle.  If  crOnly  is  positive,  text  does  wrap.  If  crOnly  is  negative,  new  lines 
are  specified  explicitly  by  Return  characters  only;  text  does  not  wrap  at  the  edge 
of  the  destination  rectangle.  (This  is  useful  in  an  application  similar  to  a 
programming-language  editor,  where  you  may  not  want  a  single  line  of  code 
to  be  split  onto  two  lines.) 

txFont 

The  font  of  all  the  text  in  the  TERec  structure  if  the  txSi  ze  field  of  this  TERec 
structure  is  greater  than  or  equal  to  0.  If  you  change  this  value,  the  entire  text  of 
this  TERec  structure  has  the  new  characteri  sti  c  when  it  is  redrawn;  also, 
remember  to  change  the  1  i  neHei  ght  and  fontAscent  fields  as  well.  If  the  txSi  ze 


STR 


Inside  QuickTime:  Data  Structures 


IV-2471 


Data  Structures 


TERec 


field  is  -1,  this  field  combines  with  tx Face  to  hold  a  handle  to  the  associated 
TEStyleRec  (IV-2473)  structure. 

txFace 

The  character  attributes  of  all  the  text  in  an  TERec  structure  if  the  txSi  ze  field  of 
this  TERec  structure  is  greater  than  or  equal  to  0.  If  you  change  this  value,  the 
entire  text  of  this  TERec  structure  has  the  new  characteristic  when  it  is 
redrawn;  also,  remember  to  change  the  1  i  neFHei  ght  and  fontAscent  fields  as 
well.  If  the  txSi  ze  field  is  -1,  this  field  combines  with  txFont  to  hold  a  handle  to 
the  associated  TEStyl  eRec  (IV-2473)  structure. 

txMode 

The  pen  mode  of  all  the  text  in  the  TERec  structure.  If  you  change  this  value,  the 
entire  text  of  this  TERec  structure  has  the  new  characteristic  when  it  is 
redrawn;  also,  remember  to  change  the  1  i  neFHei  ght  and  fontAscent  fields  as 
well. 
txSi ze 

Depending  on  its  value,  txSi  ze  either  contains  the  point  size  of  all  of  the  text  or 
it  acts  as  a  flag  indicating  whether  or  not  there  is  associated  character  attribute 
information.  If  txSi  ze  is  greater  than  or  equal  to  0,  this  is  a  monostyled  TERec 
structure,  that  is,  all  text  is  set  in  a  single  font,  size,  and  face,  and  the  value  of 
txSi  ze  is  the  size  of  the  text.  If  txSi  ze  is  -1,  the  TERec  structure  contains 
associated  character  attribute  information  and  the  txFont  and  txFace  fields 
combine  to  form  a  handle  to  the  TEStyl  eRec  (IV-2473)  structure. 

i nPort 

A  pointer  to  the  CGraf  Port  (IV-2168)  structure  associated  with  this  TERec 
structure. 

hi ghHook 

A  pointer  to  the  routine  that  deals  with  text  highlighting, 
carethlook 

A  pointer  to  the  routine  that  controls  the  appearance  of  the  caret, 
n  L i nes 

The  number  of  lines  in  the  text. 

1 i neStarts 

An  array  containing  the  character  position  of  the  first  character  in  each  line. 
This  is  a  dynamic  data  structure  having  only  as  many  elements  as  needed. 
TextEdit  calculates  these  values  internally,  so  do  not  change  the  elements  of  the 
li  neStarts  array.  Because  this  data  structure  grows  and  shrinks,  the  size  of  the 
TERec  structure  changes. 
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Programming  Info 

C  interface  file:  Text  Ed  i  t .  h 


TEStyleRec 


Stores  the  character  attribute  information  for  the  text  of  a  multistyled  TERec 
(IV-2469)  structure. 


struct  TEStyleRec 
short 
short 
STHandl e 
LHHandl e 
1  ong 

Nul 1 StHandl e 
Styl eRun 


nRuns  ; 
nStyl es ; 
styl eTab; 
lhTab; 
teRefCon ; 
nul 1 Styl e ; 
runs[8001] ; 


nRuns 

The  number  of  style  runs  in  the  text. 
nStyl es 

The  number  of  distinct  sets  of  character  attributes  used  in  the  text;  this  forms 
the  size  of  the  style  table. 

styl eTab 

A  handle  to  the  style  table. 
lhTab 

A  handle  to  the  line  height  table. 
teRefCon 

A  reference  constant  for  use  by  applications.  The  application  can  use  this  32-bit 
field  to  suit  its  needs. 

nul 1 Styl e 

A  handle  to  the  style  scrap  record  used  to  store  the  character  attribute 
information  for  a  null  selection. 
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runs 

A  table  of  style  runs  that  is  of  indefinite  length.  To  determine  the  length  of  a 
run,  you  subtract  its  start  position  from  that  of  the  next  entry  in  the  style  run 
table.  A  dummy  entry  at  the  end  of  the  style  run  table  delimits  the  length  of  the 
last  run;  its  start  position  is  equal  to  the  overall  number  of  characters  in  the  text, 
plus  1. 
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Discussion 

If  an  edit  record  has  associated  character  attribute  information,  its  tx Font  and 
txFace  fields  combine  to  hold  a  style  handle  to  its  style  record.  The  text  is  divided 
into  style  runs,  summarized  in  the  style  run  table  which  is  part  of  the  style  record. 
Each  entry  in  the  style  run  table  gives  the  starting  character  position  of  a  run  and  an 
index  into  the  style  table.  The  style  table  element  pointed  to  by  the  style  run  index 
describes  the  character  attributes  for  that  run. 

Programming  Info 

C  interface  file:  TextEdit. h 


T  extDescription 


Describes  a  sample  of  text. 


struct  TextDescription  { 


I  ong 
1  ong 
1  ong 
short 
short 
1  ong 
1  ong 

RGBCol or 
Rect 

ScrpSTEl ement 
char 


descSi ze ; 
dataFormat ; 
resvdl ; 
resvd2 ; 
dataRef Index ; 
di spl ay  FI ags  ; 
textJusti f i cati on  ; 
bgCol or ; 
defaultTextBox; 
defaul tStyl e ; 
defaultFontName[l] ; 


si  ze 

Defines  the  total  size  of  this  text  description  structure. 

type 

Indicates  the  type  (data  type  '  text ' ). 
resvdl 

Reserved;  set  to  0. 
resvd2 

Reserved;  set  to  0. 
di  spl ay  FI ags 

Contains  flags  (see  below)  that  specify  how  the  text  is  to  be  displayed. 
textJusti f i cati on 

Contains  a  constant  (see  below)  that  specifies  how  the  text  is  to  be  aligned. 
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bgCol or 

Specifies  the  background  color  for  the  text  display, 
def aul tTextBox 

Indicates  the  location  of  the  text  within  track  boundaries, 
def aul tStyl e 

Provides  aScrpSTEl  ement  (IV-2422)  structure  that  specifies  the  default  style  for 
the  text  display, 
defaul tFontName 

The  name  of  the  default  font. 

displayFlags  Constants 

df DontDi spl ay 

Does  not  display  the  specified  sample, 
df DontAutoScal e 

Does  not  scale  the  text  if  the  track  bounds  increase. 
dfCl i pToTextBox 

Clips  to  just  the  text  box.  This  is  useful  if  the  text  overlays  the  video. 
dfShri nkTextBoxToFi t 

Recalculates  size  of  the  textBox  parameter  to  just  fit  the  given  text  and  stores 
this  rectangle  with  the  text  data. 

dfScrol 1  In 

Scrolls  the  text  in  until  the  last  of  the  text  is  in  view.  This  flag  is  associated  with 
the  scrol  1  Del  ay  parameter, 
df Scrol 1  Out 

Scrolls  text  out  until  the  last  of  the  text  is  out  of  view.  This  flag  is  associated  with 
the  scrol  1  Del  ay  parameter.  If  both  dfScrol  1  In  and  dfScrol  1  Out  are  set,  the  text 
is  scrolled  in,  then  out. 

df Hori zScrol 1 

Scrolls  a  single  line  of  text  horizontally.  If  the  dfHorizScroll  flag  is  not  set,  then 
the  scrolling  is  vertical. 

df ReverseScrol 1 

If  set,  scrolls  vertically  down,  rather  than  up.  If  not  set,  horizontal  scrolling 
proceeds  toward  the  left  rather  than  toward  the  right. 

textJustification  Constants 

teFl ushDefaul t 

Default  alignment  according  to  the  primary  line  direction. 
teCenter 

Center  for  all  scripts. 
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teFl  ushRi  ght 

Right  alignment  for  all  scripts. 
teFl ushLeft 

Left  alignment  for  all  scripts. 

Associated  Functions 

TextMediaDrawRaw  (III — 1940) 

Programming  Info 

C  interface  file:  Movi es .  h 


T  extDisplay  Data 


Contains  formatting  information  for  a  text  sample, 
struct  TextDisplayData  { 


1  ong 

di  spl ay  FI ags  ; 

1  ong 

textJusti f i cati on  ; 

RGBCol or 

bgCol or ; 

Rect 

textBox ; 

short 

begi nHi 1 i te ; 

short 

endHi 1 i te ; 

RGBCol or 

hi  1 i teCol or ; 

Bool ean 

doHi 1 i teCol or ; 

SInt8 

filler; 

T i meVal ue 

scrol 1  Del ayDur ; 

Poi  nt 

dropShadowOffset ; 

short 

dropShadowT  ransparency; 

di  spl ay  FI ags 

Contains  flags  (see  below)  that  represent  the  values  of  text  descriptors. 
textJusti f i cati on 

Contains  constants  (see  below)  that  specify  the  alignment  of  the  text  in  the  text 
box.  Possible  values  are  teFl  ushDef  aul  t,  teCenter,  teFl  ushRi  ght,  and 
teFl  ushLeft.  For  more  information  on  text  alignment  and  the  text  justification 
constants,  see  the  "TextEdit"  chapter  of  Inside  Macintosh:  Text  (listed  in  the 

bibliography). 

bgCol or 

Specifies  the  background  color  of  the  rectangle  specified  by  the  text  Box  field.  The 
background  color  is  specified  as  an  RGB  color  value. 
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textBox 

Specifies  the  rectangle  of  the  text  box. 
begi nHi 1 i te 

Specifies  the  one-based  index  of  the  first  character  in  the  sample  to  highlight. 
endHi 1 i te 

Specifies  the  one-based  index  of  the  last  character  in  the  sample  to  highlight. 
doHi 1 i teCol or 

Specifies  whether  to  use  the  color  specified  by  the  hi  1  i  teCol  or  field  for 
highlighting.  If  the  value  of  this  field  is  TRUE,  the  highlight  color  is  used  for 
highlighting.  If  the  value  of  this  field  is  FALSE,  reverse  video  is  used  for 
highlighting, 
filler 

Reserved, 
scrol 1  Del ayDur 

Specifies  a  scroll  delay.  The  scroll  delay  is  specified  as  the  number  of  units  of 
delay  in  the  text  track's  time  scale.  For  example,  if  the  time  scale  is  600,  a  scroll 
delay  of  600  causes  the  sample  text  to  be  delayed  one  second.  In  order  for  this 
field  to  take  effect,  scrolling  must  be  enabled. 
dropShadowOf f set 

Specifies  an  offset  for  the  drop  shadow.  For  example,  if  the  point  specified  is 
(3,4),  the  drop  shadow  is  offset  3  pixels  to  the  right  and  4  pixels  down.  In  order 
for  this  field  to  take  effect,  drop  shadowing  must  be  enabled. 
dropShadowT  ransparency 

Specifies  the  intensity  of  the  drop  shadow  as  a  value  between  0  and  255.  In 
order  for  this  field  to  take  effect,  drop  shadowing  must  be  enabled. 

displayFlags  Constants 

df DontDi s pi  ay 

Does  not  display  the  specified  sample, 
df DontAutoScal e 

Does  not  scale  the  text  if  the  track  bounds  increase. 
dfCl i pToTextBox 

Clips  to  just  the  text  box.  This  is  useful  if  the  text  overlays  the  video. 
dfShri nkTextBoxToFi t 

Recalculates  size  of  the  textBox  parameter  to  just  fit  the  given  text  and  stores 
this  rectangle  with  the  text  data. 
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dfScrol 1  In 

Scrolls  the  text  in  until  the  last  of  the  text  is  in  view.  This  flag  is  associated  with 
the  scrol  1  Del  ay  parameter. 
dfScrol 1  Out 

Scrolls  text  out  until  the  last  of  the  text  is  out  of  view.  This  flag  is  associated  with 
the  scrol  1  Del  ay  parameter.  If  both  dfScrol  1  In  and  dfScrol  1  Out  are  set,  the  text 
is  scrolled  in,  then  out. 

dfHori zScrol 1 

Scrolls  a  single  line  of  text  horizontally.  If  the  d  f  H  o  r  i  z  S  c  r  o  1 1  flag  is  not  set,  then 
the  scrolling  is  vertical, 
df ReverseScrol 1 

If  set,  scrolls  vertically  down,  rather  than  up.  If  not  set,  horizontal  scrolling 
proceeds  toward  the  left  rather  than  toward  the  right. 

textJustification  Constants 

teFl  ushDefaul  t 

Default  alignment  according  to  the  primary  line  direction. 
teCenter 

Center  for  all  scripts. 
teFl  ushRi  ght 

Right  alignment  for  all  scripts. 
teFl ushLeft 

Left  alignment  for  all  scripts. 

Discussion 

When  the  text  export  component  exports  a  text  sample,  it  uses  the  information  in 
this  structure  to  generate  the  appropriate  text  descriptors  for  the  sample.  Likewise, 
when  the  text  import  component  imports  a  text  sample,  it  sets  the  appropriate  fields 
in  this  structure  based  on  the  sample's  text  descriptors. 

Associated  Functions 

TextExportGetDi  spl  ayData  (III — 1928) 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 


ThreeDeeDescription 

Undocumented 

struct  ThreeDeeDescription  { 
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ThreeDeeNonLinearSample 


1  ong 

descSi ze ; 

1  ong 

data  Format ; 

1  ong 

resvdl ; 

short 

resvd2 ; 

short 

dataRef Index; 

1  ong 

versi on ; 

1  ong 

rendererType ; 

1  ong 

decompressorType ; 

}; 

descSi ze 

The  total  size  of  this  structure,  including  extra  data, 
data  Format 

Undocumented 

resvdl 

Reserved;  do  not  use. 
resvd2 

Reserved;  do  not  use. 
dataRef Index 

Undocumented 
versi on 

Which  version  is  this  data. 
rendererType 

Which  Tenderer  to  use;  0  for  default. 
decompressorType 

Which  decompressor  to  use;  0  for  default. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


ThreeDeeNonLinearSample 


Undocumented 

struct  ThreeDeeNonLinearSample  { 

float  DurFromLastSampl e ; 

TQ3Matrix4x4  matrix; 

}; 

DurFromLastSampl e 

Duration  from  0  to  1. 
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ThreeDeeNonLinearTweenHeaderAtom 


matri x 

Undocumented 


Programming  Info 
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ThreeDeeNonLinearTweenHeaderAtom 


Undocumented 

struct  ThreeDeeNonLinearTweenHeaderAtom  { 


1  ong 

number ; 

1  ong 

dataSi ze ; 

f  1  oat 

tensi onFactor 

1  ong 

reservedl ; 

1  ong 

reserved2 ; 

}; 

number 

Undocumented 
dataSi ze 

Undocumented 
tensi onFactor 

Undocumented;  default  is  0. 
reservedl 

Undocumented 

reserved2 

Undocumented 


Programming  Info 
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ThreeDee  VRObjectSample 


Undocumented 

struct  ThreeDeeVRObjectSampl e  { 
long  rows; 

long  columns; 

TQ3Matrix4x4  cal  1 b 1 ; 

TQ3Matrix4x4  c  a 1 1 b  2 ; 
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long  reservedl; 

long  reserved2; 

}; 

rows 

Undocumented 


STR 


Undocumented 
cal i bl 

Undocumented 
cal i b2 

Undocumented 

reservedl 

Undocumented 

reserved2 

Undocumented 

Programming  Info 

C  interface  file:  Movi  es  .  h 


TimeBaseRecord 


Contains  a  time  base. 

struct  TimeBaseRecord  { 
long  data [ 1 ] ; 

}; 

data 

Array  of  data  that  constitutes  a  time  base. 

Programming  Info 

C  interface  file:  Movi  es  .  h 


T  imeCodeCounter 


Provides  frame  count  information  for  a  TimeCodeRecord  (IV-2484)  structure. 

struct  TimeCodeCounter  { 
long  counter; 
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TimeCodeDef 


}; 


counter 

A  frame  count. 


Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

See  Also 

See  TimeCodeRecord  (IV-2484). 


TimeCodeDef 


Contains  timecode  format  information. 


struct  TimeCodeDef  { 


1  ong 

TimeScale 
TimeVal ue 
UInt8 
UInt8 


}; 


fl ags ; 
fT i meScal e ; 
f rameDurati on ; 
numFrames ; 
paddi ng ; 


fl  ags 

Contains  flags  (see  below)  that  provide  timecode  format  information. 
fT i meScal e 

Contains  the  time  scale  for  interpreting  the  frameDuration  field.  This  field 
indicates  the  number  of  time  units  per  second, 
f rameDurati on 

Specifies  how  long  each  frame  lasts,  in  the  units  defined  by  the  f  Ti  meSca  1  e  field. 
numFrames 

Indicates  the  number  of  frames  stored  per  second.  In  the  case  of  timecodes  that 
are  interpreted  as  counters,  this  field  indicates  the  number  of  frames  stored  per 
timer  "tick." 
paddi ng 

Unused. 


flags  Constants 

tcDropFrame 

Indicates  that  the  timecode  drops  frames  occasionally  to  stay  in 
synchronization.  Some  timecodes  run  at  other  than  a  whole  number  of  frames 
per  second.  For  example,  NTSC  video  runs  at  29.97  frames  per  second.  In  order 
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to  resynchronize  between  the  timecode  rate  and  a  30  frames-per-second 
playback  rate,  the  timecode  drops  a  frame  at  a  predictable  time  (in  much  the 
same  way  that  leap  years  keep  the  calendar  synchronized). 

tc24HourMax 

Indicates  that  the  timecode  values  return  to  0  at  24  hours. 
tcNegT i mesOK 

Indicates  that  the  timecode  supports  negative  time  values. 
tcCounter 

Indicates  that  the  timecode  should  be  interpreted  as  a  simple  counter,  rather 
than  as  a  time  value.  This  allows  the  timecode  to  contain  either  time 
information  or  counter  (such  as  a  tape  counter)  information. 

Associated  Functions 

TCFrameNumberToT i  meCode  (III — 1916) 

Programming  Info 
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TimeCodeDescription 


Defines  the  format  and  content  of  a  timecode  media  sample  description. 


struct  TimeCodeDescription  { 


}; 


1  ong 
1  ong 
1  ong 
short 
short 
1  ong 

T i meCodeDef 
1  ong 


descSi ze ; 
dataFormat; 
resvdl ; 
resvd2 ; 
dataRef Index; 
fl ags ; 

ti meCodeDef ; 
srcRef [1] ; 


descSi ze 

Specifies  the  size  of  the  sample  description,  in  bytes. 
dataFormat 

Indicates  the  sample  description  type;  see  "Component  Identifiers"  (IV-2657). 
TimeCodeMedi aType  =  ' tmcd'. 
resvdl 

Reserved;  set  to  0. 
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resvd2 

Reserved;  set  to  0. 
dataRef Index 

Contains  an  index  value  indicating  which  of  the  media's  data  references 
contains  the  sample  data  for  this  sample  description. 

fl  ags 

Reserved;  set  to  0. 
ti meCodeDef 

Contains  a  timecode  definition  structure  that  defines  timecode  format 
information. 
srcRef 

Contains  the  timecode's  source  information.  This  is  formatted  as  a  user  data 
item  that  is  stored  in  the  sample  description.  The  media  handler  provides 
functions  that  allow  you  to  get  and  set  this  data. 

Associated  Functions 

TCGetSourceRef  (III — 1919) 

Programming  Info 

C  interface  file:  Qui  ckT i meComponents .  h 

TimeCodeRecord 

Interprets  time  information  as  both  a  time  value  (HH:MM:SS:FF)  and  a  frame  count. 

union  TimeCodeRecord  { 

TimeCodeTime  t; 

TimeCodeCounter  c; 

1: 

t 

The  timecode  value  interpreted  as  time  in  a  Ti  meCodeTi  me  (IV-2485)  structure, 
c 

The  timecode  value  interpreted  as  a  frame  count  in  a  Ti  meCodeCounter  (IV-2481) 
structure. 

Discussion 

When  you  use  the  timecode  media  handler  to  work  with  time  values,  the  media 
handler  uses  T i  meCodeRecord  structures  to  store  the  time  values.  These  structures 
allows  you  to  interpret  the  time  information  as  either  a  time  value  (HH:MM:SS:FF) 
or  a  counter  value.  Given  a  timecode  definition,  you  can  freely  convert  from  frame 
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numbers  to  time  values  and  from  time  values  to  frame  numbers.  For  a  time  value  of 
00:00:12:15  (HH:MM:SS:FF),  you  would  obtain  a  frame  number  of  375  ( (12*30)  +15). 

Associated  Functions 

TCFrameNumberToT i  meCode  (III — 1916) 

Programming  Info 

C  interface  file:  Qui  ckTi meComponents  .  h 

See  Also 

See  TimeCodeTime  (IV-2485)  and  TimeCodeCounter  (IV-2481). 


STR 


T  imeCodeT  ime 


Provides  time  information  for  a  T i  meCodeRecord  (IV-2484)  structure. 

struct  TimeCodeTime  { 

UInt8  hours; 

UInt8  minutes; 

UInt8  seconds; 

UInt8  frames; 

}; 

hours 

Hours  in  the  HH:MM:SS:FF  time  format, 
mi nutes 

Minutes  in  the  HH:MM:SS:FF  time  format.  With  timecodes  that  allow  negative 
time  values,  this  field  (addressed  T  i  meCodeRecord .  t  .mi  nutes)  indicates  whether 
the  time  value  is  positive  or  negative.  If  the  tctNegFl  ag  bit  (see  below)  of  the 
minutes  field  is  set  to  1,  the  time  value  is  negative, 
seconds 

Seconds  in  the  HH:MM:SS:FF  time  format, 
frames 

Frames  in  the  HH:MM:SS:FF  time  format. 

minutes  Flag  Constant 

tctNegFl ag 

If  this  bit  of  the  mi  nutes  field  is  set  to  1,  the  time  value  in  T i  meCodeT i  me  is 
negative. 

Programming  Info 
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TimeRecord 


See  Also 

See  TimeCodeRecord  (IV-2484). 


TimeRecord 


Contains  a  time  value  with  its  scale  and  time  base. 

struct  TimeRecord  { 

CompT i meVal ue 
T i meScal e 
T i meBase 

}; 

val  ue 

Contains  the  time  value.  The  time  value  defines  either  a  duration  or  an  absolute 
time  by  specifying  the  corresponding  number  of  units  of  time.  For  durations, 
this  is  the  number  of  time  units  in  the  period.  For  an  absolute  time,  this  is  the 
number  of  time  units  since  the  beginning  of  the  time  coordinate  system.  The 
unit  for  this  value  is  defined  by  the  scale  field.  The  time  value  is  expressed  as 
a  64-bit  integer  quantity.  This  64-bit  quantity  consists  of  two  32-bit  integers  and 
is  defined  by  the  Int64  data  type. 

seal  e 

Contains  the  time  scale.  This  field  specifies  the  number  of  units  of  time  that  pass 
each  second.  If  you  specify  a  value  of  0,  the  time  base  uses  its  natural  time  scale. 

base 

Contains  a  reference  to  the  time  base.  You  obtain  a  time  base  by  calling 
GetMovi  eTimeBase  (1-496)  or  NewTimeBase  (11-1119).  If  the  time  structure  defines 
a  duration,  set  this  field  to  NIL.  Otherwise,  this  field  must  refer  to  a  valid  time 
base. 

Associated  Functions 

AddT i  me  (1-41) 

Programming  Info 

C  interface  file:  Movi  es .  h 


value; 
seal e ; 
base ; 


TimeT  oSampleNum 

Maps  a  sample  number  to  its  sample  duration, 
struct  TimeToSampleNum  { 
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long  sampl eCount ; 

TimeValue  sampl eDurati on ; 

}; 

sampl eCount 

A  physical  sample  number, 
sampl eDurati on 

The  physical  duration  of  the  sample. 

Programming  Info 

C  interface  file:  Movi  es Format .  h 

See  Also 

For  an  atom  that  contains  TimeToSampl  eNum  structures,  see  'stts'  (IV-2595). 


STR 


T  oneDescription 


Provides  the  information  needed  to  produce  a  specific  musical  sound. 


struct  ToneDescription 
Bi gEndi anOSType 
Str31 
Str31 

Bi gEndi anLong 
Bi gEndi anLong 

}; 


{ 

synthesi zerType ; 
synthesi zerName ; 
i nstrumentName ; 
i nstrumentNumber ; 
gmNumber ; 


synthesi zerType 

A  synthesizer  type  constant  (see  below).  A  value  of  0  specifies  that  any  type  of 
synthesizer  is  acceptable, 
synthesi zerName 

The  name  of  the  instrument  to  use. 
i nstrumentName 

The  name  of  the  instrument  to  use. 
i nstrumentNumber 

The  instrument  number  of  the  instrument  to  use.  This  value,  which  must  be  in 
the  range  1-262143,  can  specify  General  MIDI  and  GS  instruments  as  well  as 
other  instruments.  The  instrument  specified  by  this  field  is  used  if  it  is  available; 
if  not,  the  instrument  specified  by  the  gmNumber  field  is  used.  If  neither  of  the 
instruments  specified  by  the  i  nstrumentNumber  or  gmNumber  fields  is  available, 
the  instrument  specified  by  the  i  nstrumentName  field  is  used.  Finally,  if  none  of 
these  fields  specifies  an  instrument  that  is  available,  no  tone  is  played. 
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gmNumber 

The  instrument  number  of  a  General  MIDI  or  GS  instrument  to  use  if  the 
instrument  specified  by  the  i  nstrumentNumber  field  is  not  available.  This  value, 
which  must  be  in  the  range  1-16383,  can  specify  only  General  MIDI  and  GS 
instruments.  The  instrument  specified  by  the  i  nstrumentNumber  field  is  used  if 
it  is  available;  if  not,  the  instrument  specified  by  the  gmNumber  field  is  used.  If 
neither  of  the  instruments  specified  by  the  i  nstrumentNumber  or  gmNumber  fields 
is  available,  the  instrument  specified  by  the  i  nstrumentName  field  is  used. 
Finally,  if  none  of  these  fields  specifies  an  instrument  that  is  available,  no  tone 
is  played. 

synthesizerType  Constants 

kSoftSynthComponentSubType 

Software  synthesizer;  value  is  '  s  s 
kGMSynthComponentSubType 

General  MIDI  synthesizer;  value  is  '  gm  ' . 

Discussion 

The  tune  header  in  the  QuickTime  Music  Architecture  has  aToneDescription 
structure  for  each  instrument  used.  These  structures  are  also  used  in  the  tone 
description  atoms  of  atomic  instruments. 

Associated  Functions 

Musi  cFi  ndTone  (11-981) 

Programming  Info 

C  interface  file:  Qui  ckT i meMusi  c .  h 


TQ3Matrix4x4 


Defines  a  4-by-4  matrix  transformation. 

struct  TQ3Matrix4x4  { 

f 1  oat  val ue[4] [4] ; 

1: 

val  ue 

The  matrix. 


Programming  Info 
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T  rackDirectory  Entry 


Includes  a  track  in  a  movie. 

struct  TrackDirectoryEntry  { 

TrackDi rectory  trackDi rectory ; 

}; 


STR 


trackDi rectory 

A  'trak'  (IV-2600)  atom. 

Programming  Info 

C  interface  file:  Movi  es Format .  h 

See  Also 

Seethe  'trak'  (IV-2600)  and  'moov'  (IV-2566)  atoms. 


T  rackEditStateRecord 


Contains  a  track  edit  state. 

struct  TrackEdi tStateRecord  { 
long  data [ 1 ] ; 

1; 

data 

An  array  of  data  that  constitutes  a  track  edit  state. 

Programming  Info 
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TrackHeader 


Specifies  the  characteristics  of  a  track  in  a  movie. 


struct  TrackHeader 
1  ong 
1  ong 
1  ong 
1  ong 
1  ong 

T i meVal ue 
1  ong 
1  ong 


{ 

fl ags  ; 

creati onT i me ; 
modi  f i cati onT i me ; 
trackID; 
reservedl ; 
durati on ; 
reserved2 ; 
reserved3 ; 
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short  layer; 

short  al ternateGroup ; 

short  volume; 

short  reserved4; 

MatrixRecord  matrix; 

Fixed  trackWidth; 

Fixed  trackHeight; 

}; 

fl  ags 

The  high  byte  is  version  information;  the  low  byte  is  a  combination  of  one  or 
more  flags  (see  below), 
creati onT i me 

Number  of  seconds  since  midnight,  January  1, 1904  to  the  time  when  the  '  t  r  a  k ' 
(IV-2600)  atom  was  created. 
modificationTime 

Number  of  seconds  since  midnight,  January  1, 1904  to  the  time  when  the  '  t  r  a  k ' 
atom  was  last  changed. 

trackID 

The  ID  number  of  this  track, 
reservedl 

Reserved;  set  to  0. 
durati on 

The  duration  of  this  track  in  movie  time  units. 
reserved2 

Reserved;  set  to  0. 
reserved3 

Reserved;  set  to  0. 

1  ayer 

The  viewing  priority  of  this  track  in  its  movie.  QuickTime  displays  the  movie's 
tracks  according  to  this  value;  tracks  with  lower  layer  numbers  are  displayed  in 
front  and  tracks  with  higher  layer  numbers  are  displayed  in  back. 

al ternateGroup 

A  number  common  to  a  collection  of  movie  tracks  that  contain  alternate  data 
for  one  another.  QuickTime  chooses  one  track  from  the  group,  based  on 
considerations  such  as  localization  or  hardware  capabilities, 
vol ume 

The  sound  volume  at  which  to  play  this  track,  ranging  from  -1.0  to  +1.0.  The 
high-order  8  bits  contain  the  integer  part;  the  low-order  8  bits  contain  the 
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fractional  part.  A  value  of  +1.0  constitutes  the  maximum  volume  of  the  user's 
computer.  Negative  values  are  silent  but  retain  the  magnitude  of  the  volume 
setting. 

reserved4 

Reserved;  set  to  0. 
matri x 

A  Matrix  Re  cord  (IV-2304)  structure  that  contains  the  graphic  transformation 
matrix  for  this  track. 
trackWi dth 

The  width  of  this  track  in  pixels. 
trackHei ght 

The  height  of  this  track  in  pixels. 

flags  Constants 

T  rackEnabl e 

This  track  is  enabled. 

TracklnMovie 

This  track  is  part  of  the  movie  playback. 

TracklnPreview 

This  track  is  part  of  the  movie's  preview. 

TracklnPoster 

This  track  is  part  of  the  movie's  poster. 

Programming  Info 

C  interface  file:  Movi  es Format .  h 

See  Also 

For  the  atom  structure  that  normally  contains  the  TrackHeader  data  structure,  see 
’tkhd'  (IV-2598). 


T  rackLoadSettings 


Contains  preloading  information  for  a  track,  used  in  a  'load'  (IV-2556)  atom. 


struct  TrackLoadSettings  { 


T i meVal ue 
T i meVal ue 
1  ong 
1  ong 


prel oadStartTime; 
prel oadDurati on ; 
prel  oadFl  ags ; 
def aul tHi nts ; 
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preloadStartTime 
Undocumented 
prel oadDurati on 
Undocumented 
prel oadFl ags 

Undocumented 
defaul tHi nts 

Undocumented 

Programming  Info 

C  interface  file:  MoviesFormat.h 

See  Also 

For  the  atom  structure  that  contains  this  data  structure,  see  the  'load'  (IV-2556) 
atom. 

TrackRecord 

Contains  a  track. 

struct  TrackRecord  { 
long  data [13; 

}; 

data 

An  array  of  track  data. 

Programming  Info 

C  interface  file:  Movi  es .  h 


TuneStatus 


Provides  information  on  the  currently  playing  tune. 


struct  TuneStatus  { 
unsigned  long  * 
unsigned  long  * 
TimeVal ue 
short 
short 
TimeVal ue 
1  ong 


tune ; 
tunePtr ; 
time ; 

queueCount ; 
queueSpots ; 
queueT i me ; 
reserved[3]  ; 
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}; 

tune 

The  currently  playing  tune. 
tunePtr 

Current  position  within  the  playing  tune. 

ti  me 

Current  tune  time. 
queueCount 

Number  of  tunes  queued  up. 
queueSpots 

Number  of  tunes  that  can  be  added  to  the  queue. 
queueT i me 

Total  amount  of  playing  time  represented  by  tunes  in  the  queue.  This  value  can 
be  very  inaccurate, 
reserved 

Reserved;  set  to  0. 

Associated  Functions 

TuneGetStatus  (III — 1961) 

Programming  Info 
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TweenRecord 


Passes  information  to  your  tween  component's  TweenDoTween  method. 


struct  TweenRecord  { 
1  ong 

QTAtomContai ner 
QTAtom 
QTAtom 
Fi  xed 

TweenerDataUPP 
void  * 
void  * 

}; 


versi on ; 
container; 
tweenAtom; 
dataAtom; 
percent ; 
dataProc; 
pri vatel ; 
pri vate2 ; 


versi on 

The  version  number  of  this  structure.  This  field  is  initialized  to  0. 
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contai ner 

The  atom  container  that  contains  the  tween  data. 
tweenAtom 

The  atom  for  this  tween  entry's  data  in  the  container, 
percent 

The  percentage  by  which  to  change  the  data. 
dataProc 

The  procedure  the  tween  component  calls  to  send  the  tweened  value  to  the 
receiving  track, 
pri vatel 

Reserved, 
pri vate2 

Reserved. 

Associated  Functions 

TweenerDataProc  (III — 2153) 

Programming  Info 
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TweenSequenceEntryRecord 


Specifies  when  a  tween  in  a  tween  sequence  ends. 

struct  TweenSequenceEntryRecord  { 

Fixed  endPercent; 

QTAtomID  tweenAtomlD ; 

QTAtomID  dataAtomID; 

1: 

endPercent 

Specifies  the  point  in  the  duration  of  the  tween  media  sample  at  which  the 
sequence  entry  ends.  This  is  expressed  as  a  percentage;  for  example,  if  the  value 
is  75.0,  the  sequence  entry  ends  after  three-quarters  of  the  total  duration  of  the 
tween  media  sample  have  elapsed.  The  sequence  entry  begins  after  the  end  of 
the  previous  sequence  entry  or,  for  the  first  entry  in  the  sequence,  at  the 
beginning  of  the  tween  media  sample. 

tweenAtomlD 

Specifies  the  '  twen '  (IV-2605)  atom  containing  the  tween  for  the  sequence 
element. 
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dataAtomID 

Specifies  the  kTweenData  atom  containing  the  data  for  the  tween. 

Discussion 

Each  tween  in  a  tween  sequence  begins  after  the  previous  tween  ends  or,  for  the  first 
tween  in  the  sequence,  at  the  beginning  of  the  tween  duration.  Because  there  can  be 
more  than  one  data  set  for  a  tween,  the  data  structure  includes  a  field  for  the  data 
atom  ID  as  well  as  the  tween  atom  ID. 

Programming  Info 
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See  the  '  twen '  (IV-2605)  atom. 


STR 


TweenVIRecord 


Provides  an  extended  version  of  the  TweenRecord  (IV-2493)  structure. 

struct  TweenVIRecord  { 

1  ong 

QTAtomContai ner 
QTAtom 
QTAtom 
Fi  xed 

TweenerDataUPP 
void  * 
void  * 

Fract 

}; 

versi on 

The  version  number  of  this  structure.  This  field  is  initialized  to  0. 
contai ner 

The  atom  container  that  contains  the  tween  data. 
tweenAtom 

The  atom  for  this  tween  entry's  data  in  the  container. 
dataAtom 

Undocumented 

percent 

The  percentage  by  which  to  change  the  data. 


versi on ; 
contai ner; 
tweenAtom; 
dataAtom; 
percent ; 
dataProc; 
pri vatel ; 
pri vate2 ; 
f ractPercent ; 
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dataProc 

The  procedure  the  tween  component  calls  to  send  the  tweened  value  to  the 
receiving  track, 
pri vatel 

Reserved, 
pri vate2 

Reserved, 
f ractPercent 

Undocumented 

Programming  Info 
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See  Also 

See  the  TweenRecord  (IV-2493)  structure. 


UnsignedWide 


Stores  an  unsigned  64-bit  value  as  two  unsigned  32-bit  integers. 

struct  UnsignedWide  {  //  big-endian  version 

UInt32  hi; 

UInt32  1 o ; 

}; 

struct  UnsignedWide  {  //  little-endian  version 

UInt32  1 o ; 

UInt32  hi; 

1: 

hi 

The  high-order  unsigned  32-bit  integer. 

1  o 

The  low-order  unsigned  32-bit  integer. 
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UserDataRecord 


Contains  user  data. 


IV-2496 
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VDCompressionList 


struct  UserDataRecord  { 
long  data [ 1 ] ; 

}; 

data 

An  array  of  user  data. 

Programming  Info 
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VDCompressionList 


Contains  a  set  of  image-compression  capabilities  for  a  video  digitizer. 

struct  VDCompressionList  { 

CodecComponent  codec; 

CodecType  cType; 

Str63  typeName; 

Str63  name; 

long  formatFlags; 

long  compress  FI ags ; 

long  reserved; 

}; 

codec 

Contains  the  component  identifier  for  the  video  digitizer's  compressor 
component.  Some  video  digitizers  may  also  implement  their 
image-compression  capabilities  in  an  Image  Compression  Manager 
compressor  component.  In  this  case,  the  digitizer  may  allow  the  application  to 
connect  to  and  use  the  compressor.  If  so,  the  digitizer  provides  the  compressor 
component's  identifier  here.  If  not,  the  digitizer  sets  this  field  to  N I L. 
cType 

Identifies  the  compression  algorithm  supported  by  the  video  digitizer;  see 
"Codec  Identifiers"  (IV-2655). 
typeName 

Contains  a  text  string  that  identifies  the  compression  algorithm.  An  application 
may  display  this  string  to  the  user  to  identify  the  type  of  image  compression 
being  performed. 

name 

Specifies  the  name  of  the  compressor.  The  developer  of  the  video  digitizer 
assigns  this  name.  An  application  may  display  this  string  to  the  user. 
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VDGammaRecord 


formatFl ags 

Contains  flags  that  describe  the  data  formats  supported  by  the  video  digitizer. 
Typically,  these  flags  are  of  interest  only  to  developers  of  video  digitizers  and 
image  compressors. 
compressFl ags 

Contains  flags  that  describe  the  compression  capabilities  of  the  video  digitizer. 
Typically,  these  flags  are  of  interest  only  to  developers  of  video  digitizers  and 
image  compressors, 
reserved 

Reserved;  do  not  use. 

Associated  Functions 

VDGetCompressi onTypes  (III — 1994) 

Programming  Info 
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VDGammaRecord 


Holds  a  gamma  table. 

struct  VDGammaRecord  { 

Ptr  csGTable; 

1: 

csGTabl e 

A  pointer  to  a  gamma  table. 

Programming  Info 
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VdigBufferRec 


Defines  a  video  digitizer  buffer. 

struct  VdigBufferRec  { 

Pi xMapHandl e  dest; 

Point  location: 

long  reserved: 


IV-2498 
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dest 

Contains  a  handle  to  the  pixel  map  that  defines  the  destination  buffer. 

1 ocati on 

Specifies  the  location  of  the  video  destination  in  the  pixel  map  specified  by  the 
dest  field.  This  point  identifies  the  upper-left  comer  of  the  destination 
rectangle.  The  size  and  scaling  of  the  destination  rectangle  are  governed  by  the 
matrix  and  mask  fields  of  the  buffer  list  structure  that  contains  this  structure. 

reserved 

Reserved;  set  to  0. 

Programming  Info 
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See  Also 

See  VdigBufferRecList  (IV-2499). 

VdigBufferRecList 

Contains  a  list  of  Vdi  gBufferRec  (IV-2498)  structures. 

struct  VdigBufferRecList  { 
short  count; 

MatrixRecordPtr  matrix; 

RgnHandie  mask; 

Vdi  gBufferRec  1  i s t [ 1 ] ; 

}; 

count 

Specifies  the  number  of  buffers  defined  by  this  structure.  The  value  of  this  field 
must  correspond  to  the  number  of  entries  in  the  list  array, 
matri x 

Specifies  the  transformation  matrix  that  is  applied  to  all  of  the  destination 
rectangles  before  the  video  image  is  displayed.  You  must  specify  a  matrix.  If 
you  do  not  want  to  perform  any  transformations,  use  the  identity  matrix. 

mask 

Specifies  a  clipping  region  that  is  applied  to  the  destination  rectangle  before  the 
video  image  is  displayed.  Note  that  this  region  applies  to  only  the  first 
destination  buffer.  If  you  want  the  region  to  apply  to  all  of  your  destination 
buffers,  you  must  do  this  yourself.  If  you  do  not  want  to  specify  a  clipping 
region,  set  this  field  to  NIL. 
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VdigType 


list 

Contains  an  array  of  Vdi  gBufferRec  (IV-2498)  structures.  Each  buffer  is 
represented  by  a  buffer  structure. 

Associated  Functions 

VDSetupBuffers  (III — 2055) 
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See  Also 

See  Vdi  gBufferRec  (IV-2498). 


VdigType 


Defines  a  video  digitizer's  type. 

struct  VdigType  { 
long  digType; 

long  reserved: 

}; 

di gType 

A  constant  (see  below)  that  defines  a  video  digitizer  type, 
reserved 

Reserved;  do  not  use. 

digType  Constants 

vdTypeBasi c 

Basic  video  digitizer;  does  not  support  any  clipping. 
vdTypeAl pha 

Supports  clipping  by  means  of  an  a  1  pha  channel. 
vdTypeMask 

Supports  clipping  by  means  of  a  mask  plane. 
vdTypeKey 

Supports  clipping  by  means  of  key  colors. 
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See  Also 

See  VdigTypeList  (IV-2501). 
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VdigTypeList 


Contains  a  list  of  Vdi  gType  (IV-2500)  structures. 

struct  VdigTypeList  { 
short  count; 

VdigType  1 i s t [  1  ] ; 


STR 


count 

Number  of  structures  in  the  list. 


list 

An  array  of  Vdi  gType  (IV-2500)  structures. 

Programming  Info 
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See  Also 

See  Vdi  gType  (IV-2500). 


VideoBottles 


Identifies  the  callback  functions  to  be  assigned  to  a  sequence  grabber  channel. 


struct  VideoBottles  { 
short 

SGGrabBottl  ellPP 
SGGrabCompl  eteBottl  ellPP 
SGDi  spl  ayBottl  ellPP 
SGCompressBottl  ellPP 
SGCompressCompl  eteBottl  ellPP 
SGAddFrameBottl  ellPP 
SGT ransferFrameBottl  ellPP 
SGGrabCompressCompl  eteBottl  ellPP 
SGDi  spl  ayCompressBottl  ellPP 


procCount ; 

grabProc ; 

grabCompl eteProc ; 

di spl ayProc ; 

compressProc; 

comp res sCompl eteProc ; 

addFrameProc ; 

transferFrameProc; 

grabCompres sCompl eteProc ; 

d i spl ayCompressProc; 


procCount 

Specifies  the  number  of  callback  functions  that  may  be  identified  in  the 
structure.  Set  this  field  to  9. 
grabProc 

Identifies  the  SGGrabBottl  eProc  (III— 2142)  function.  If  you  are  setting  such  a 
function,  set  this  field  so  that  it  points  to  the  function's  entry  point.  If  you  are 
not  setting  such  a  function,  set  this  field  to  NIL. 
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grabCompl eteProc 

Identifies  the  SGGrabCompl  eteBottl  eProc  (III— 2143)  function.  If  you  are  setting 
such  a  function,  set  this  field  so  that  it  points  to  the  function's  entry  point.  If  you 
are  not  setting  such  a  function,  set  this  field  to  NIL. 
di spl ayProc 

Identifies  the  SGDi  spl  ay  Bottl  eProc  (III— 2140)  function.  If  you  are  setting  such  a 
function,  set  this  field  so  that  it  points  to  the  function's  entry  point.  If  you  are 
not  setting  such  a  function,  set  this  field  to  NIL. 

compressProc 

Identifies  the  SGCompressBottl  eProc  (III— 2137)  function.  If  you  are  setting  such 
a  function,  set  this  field  so  that  it  points  to  the  function's  entry  point.  If  you  are 
not  setting  such  a  function,  set  this  field  to  NIL. 
comp r ess Comp 1 eteProc 

Identifies  the  SGCompressCompl  eteBottl  eProc  (III— 2138)  function.  If  you  are 
setting  such  a  function,  set  this  field  so  that  it  points  to  the  function's  entry 
point.  If  you  are  not  setting  such  a  function,  set  this  field  to  NIL. 
addFrameProc 

Identifies  the  SGAddFrameBottl  eProc  (III— 2136)  function.  If  you  are  setting  such 
a  function,  set  this  field  so  that  it  points  to  the  function's  entry  point.  If  you  are 
not  setting  such  a  function,  set  this  field  to  NIL. 

transferFrameProc 

Identifies  the  SGT ransferFrameBottl  eProc  (III— 2145)  function.  If  you  are  setting 
such  a  function,  set  this  field  so  that  it  points  to  the  function's  entry  point.  If  you 
are  not  setting  such  a  function,  set  this  field  to  NIL. 
grabCompressCompl eteProc 

Identifies  the  SGGrabCompressCompl  eteBottl  eProc  (III— 2143)  function.  If  you  are 
setting  such  a  function,  set  this  field  so  that  it  points  to  the  function's  entry 
point.  If  you  are  not  setting  such  a  function,  set  this  field  to  NIL. 
di spl ayCompressProc 

Identifies  the  SGDi  spl  ayCompressBottl  eProc  (III— 2141)  function.  If  you  are 
setting  such  a  function,  set  this  field  so  that  it  points  to  the  function's  entry 
point.  If  you  are  not  setting  such  a  function,  set  this  field  to  NIL. 

Associated  Functions 

SGGetVi  deoBottl  enecks  (III — 1741) 
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VideoMedialnfoHeader 


VideoMedialnfoHeader 


Defines  the  graphics  transfer  characteristics  for  a  video  media, 
struct  VideoMedialnfoHeader  { 


1  ong 

fl ags  ; 

short 

graphi  csMode ; 

short 

opCol orRed ; 

short 

opCol orGreen ; 

short 

opCol orBl ue ; 

}; 

fl  ags 

One  byte  of  version  information  followed  by  three  bytes  of  flags.  The  flags 
bytes  are  not  currently  used, 
graphi csMode 

A  transfer  mode  constant;  see  "Graphics  Transfer  Modes"  (IV-2670). 
opCol orRed 

Red  parameter  to  be  passed  to  the  transfer  operation. 
opCol orGreen 

Green  parameter  to  be  passed  to  the  transfer  operation. 
opCol orBl ue 

Blue  parameter  to  be  passed  to  the  transfer  operation. 

Programming  Info 
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See  Also 

For  the  atom  structure  that  contains  Vi deoMedi alnfoHeader,  see  '  vmhd '  [media] 
(IV-2611). 


wide 


Stores  a  signed  64-bit  value  as  a  signed  32-bit  integer  and  an  unsigned  32-bit  integer. 


struct  wide  { 

SInt32  hi ; 

UInt32  lo; 


//  big-endian  version 


struct  wide  { 

UInt32  lo; 

SInt32  hi ; 


//  little-endian  version 


STR 
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XMLAttribute 


}; 

hi 

The  signed  high-order  32-bit  integer. 

1  o 

The  unsigned  low-order  32-bit  integer. 
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See  Also 

See  the  Unsi  gnedWi  de  (IV-2496)  structure. 


XMLAttribute 


An  XML  attribute-value  pair 

struct  XMLAttribute  { 

UInt32 
char  * 

1  ong 

XMLAttri buteVal ue 
char  * 

}; 

i denti f i er 

A  tokenized  identifier,  if  the  attribute  name  was  recognized  by  the  parser. 

name 

The  attribute's  name.  This  is  present  only  if  the  identifier  parameter  has  the 
value  xml  Identi f i erUnrecogni zed. 

val ueKi nd 

The  type  of  the  parsed  value,  if  the  value  was  recognized  and  parsed; 
otherwise,  the  value  attri  buteVal  ueKi  ndCharStri  ng. 
val  ue 

The  parsed  attribute  value, 
val ueStr 

The  value  string. 
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i denti tier; 
name ; 

val ueKi nd ; 
value; 
val ueStr ; 


IV-2504 
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XMLContent 

Undocumented 

struct  XMLContent  { 

UInt32  kind; 

XMLE1 ementContent  actual  Content ; 


STR 


ki  nd 

Undocumented 
actual  Content 

Undocumented 


Programming  Info 
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XMLDocRecord 

Undocumented 

struct  XMLDocRecord  { 

void  *  xml  Datastorage ; 

XMLElement  rootElement; 

}; 

xml  Datastorage 
Undocumented 
rootEl ement 

Undocumented 


Programming  Info 
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XMLElement 


Undocumented 


i denti fi er ; 
name ; 

attri butes ; 


struct  XMLElement  { 
UInt32 
char  * 

XMLAttri butePtr 
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XMLContentPtr  contents; 

}; 

i  denti  tier 

A  tokenized  identifier,  if  the  element  name  was  recognized  by  the  parser. 

name 

The  element  name,  only  present  if  the  identifier  parameter  contains 
xml  Identi f i erllnrecogni zed. 
attri butes 

An  array  of  attributes,  terminated  with  a  value  ofxmlldentifierlnvalid. 
contents 

Array  of  contents,  terminated  with  a  value  ofxmlldentifierlnvalid 
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0x00000000 


Atoms 


0x00000000 


Terminates  an  audio  atom  list. 

struct  Audi oTerminatorAtom  { 
long  size; 

OSType  atomType; 


ATM 


si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  kAudi  oTermi  natorAtomType;  see  "Atom  ID  Codes"  (IV-2649). 
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See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  Tile  Format 

(listed  in  the  bibliography). 


0x00000001 

A  sprite  property  matrix  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

0x00000001. 

data 

The  sprite  matrix  property,  a  structure  of  type  Matri  xRecord  (IV-2304). 

Parent  Atom 

'  sprt '  ( I V - 2584 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 
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0x00000004 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


0x00000004 

A  sprite  visible  property  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

0x00000004. 

data 

The  sprite  visible  property,  of  type  short. 

Parent  Atom 

'  sprt '  ( I V - 2584 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


0x00000005 


A  sprite  property  layer  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

0x00000005. 

data 

The  sprite  layer  property,  of  type  short. 

Parent  Atom 

'sprt'  (IV-2584) 

Parent  atom  can  contain  only  one  atom  of  this  type. 
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0x00000006 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


0x00000006 

A  sprite  graphics  mode  property  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

0x00000006. 

data 

The  sprite  graphics  mode  property,  a  structure  of  type 
ModifierTrackGraphicsMode Record  (IV-2311). 

Parent  Atom 

'  sprt '  ( I V - 2584 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


ATM 


0x00000064 


A  sprite  image  index  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

0x00000064. 

data 

The  sprite  image  index  property,  of  type  short. 

Parent  Atom 

'sprt'  ( I V - 2584 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 
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0x00000065 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


0x00000065 


A  sprite  background  color  property  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

0x00000065. 

data 

The  sprite  background  color  property,  a  structure  of  type  RGBCol  or  (IV-2403). 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

0x00000066 


A  sprite  property  offscreen  bit  depth  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

0x00000066. 

data 

The  sprite  offscreen  bit  depth  property,  of  type  short. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


0x00000067 


A  sprite  property  sample  format  atom. 
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This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

0x00000067. 

data 

The  sprite  sample  format  property,  of  type  short. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  Tile  Format 

(listed  in  the  bibliography). 

'A11F' 


ATM 


User  data  list  entry  atom  to  play  all  frames. 

struct  Movi esUserData  { 
long  size; 

long  udType; 

char  data [ 1 ] ; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
udType 

'All  F'. 

data 

A  byte  indicating  that  all  frames  of  video  should  be  played,  regardless  of 
timing. 

Parent  Atom 

'  udta '  ( I V - 2 60 7 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 
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See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 
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'beha' 


'beha' 


Defines  sprite  behavior. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Value  is  '  beha ' . 

Optional  Child  Atoms 

'imag'  (IV-2547) 

A  sprite  image  atom. 

'crsr'  (IV-2524) 

Color  custom  cursor  child  atom. 

'  sstr '  (IV-2587) 

Specifies  the  ID  of  a  string  variable,  contained  in  a  sprite  track,  to  display  in  the 
status  area  of  the  browser. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  Tile  Format 

(listed  in  the  bibliography). 


'chap' 


Chapter  or  scene  list  track  reference  type  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kT rackReferenceChapterLi  st,  designating  atom  type  '  chap ';  see 
"Atom  ID  Codes"  (IV-2649). 

data 

A  list  of  track  ID  values  (32-bit  integers)  specifying  the  related  tracks.  Note  that 
a  track  ID  value  can  be  set  to  0  to  indicate  an  unused  entry  in  the  atom.  Doing 
this  can  be  more  convenient  than  deleting  the  reference. 

Parent  Atom 

'tref'  (IV-2602) 

Parent  atom  can  contain  only  one  atom  of  this  type. 


IV-2512 


Inside  QuickTime:  Atoms 


'clip' 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'clip' 

Defines  a  clipping  region, 
struct  ClippingAtom  { 


1  ong 

si  ze ; 

1  ong 

atomType ; 

ATM 

RgnAtom 

aRgnCl ip; 

}; 

> 
r— 1- 

o 

si  ze 

3 

CO 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  Cl  i  pAI  D,  designating  atom  type  'clip';  see  "Atom  ID  Codes" 
(IV-2649). 

aRgnCl i p 

A  '  crgn '  (IV-2523)  atom  that  defines  the  clipping  region. 

Discussion 

You  can  treat  this  atom  either  as  a  declared  structure  or  as  a  QT  atom,  which  you 
can  create  it  with  QTInsertChi  1  d  (11-1183). 

Programming  Info 

MoviesFormat.h 

See  Also 

For  the  atoms  that  may  contain  this  atom,  see  'moov'  (IV-2566)  and  'trak' 
(IV-2600).  For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File 
Format  (listed  in  the  bibliography). 

'cion' 

Contains  information  about  a  track  clone. 

struct  CloneAtom  { 

long  size; 

long  atomType; 

CloneRecord  clonelnfo; 

}; 


Inside  QuickTime:  Atoms  IV-2513 


'cmov' 


si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Value  is  'cion', 
cl onelnfo 

A  CloneRecord  (api>CloneRecord-C  1  oneRecord)  structure. 

See  Also 

See  the  Cl  oneRecord  (api>CloneRecord-Cl  oneRecord)  structure  and 

AddCl  onedT rackToMovi  e  (1-22).  For  general  information  about  atoms,  see  Inside 

QuickTime:  QuickTime  File  Format  (listed  in  the  bibliography). 

'cmov' 


Contains  a  compressed  movie. 

This  is  a  QT  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameter: 

atomType 

Constant  CompressedMovi  eAID,  designating  atom  type  '  cmov ';  see  "Atom  ID 
Codes"  (IV-2649). 

Parent  Atom 

' moov '  ( I V - 2 5 6 6 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Required  Child  Atoms 

'  doom '  (IV-2527) 

Indicates  the  compression  algorithm  used  to  compress  a  movie.  Only  one 
allowed. 

' cmvd '  (IV-2514) 

Stores  the  data  for  a  compressed  movie.  Only  one  allowed. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'cmvd' 


Stores  the  data  for  a  compressed  movie. 


IV-2514 
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'co64' 


Parent  Atom 


'co64' 


See  Also 


'©cpy' 


This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  CompressedMovi  eDataAID,  designating  atom  type  '  cmvd see  "Atom  ID 
Codes"  (IV-2649). 

data 

An  integer  of  type  UInt32  that  gives  the  length  of  the  uncompressed  movie  in 
bytes,  followed  by  the  compressed  movie  data. 

' cmov '  (IV-2514) 

Parent  atom  can  contain  only  one  atom  of  this  type. 


A  64-bit  version  of  the  '  stco '  (IV-2589)  atom. 

For  details,  see  'stco'  (IV-2589). 
atomType 

Constant  STChunk0ffset64AID,  designating  atom  type  'co64';  see  "Atom  ID 
Codes"  (IV-2649). 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


User  data  list  entry  atom:  copyright  information. 

struct  Movi esUserData  { 
long  size; 

long  udType; 

char  data [  1  ] ; 


si  ze 

The  size  in  bytes  of  this  atom  structure. 


ATM 
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IV-2515 


Atoms 


’©day’ 


udType 

Constant  kllserDataTextCopy  ri  ght,  designating  atom  type  '©cpy see  "User 
Data  Identifiers"  (IV-2696). 

data 

A  string  containing  copyright  information. 

Parent  Atom 

'  udta '  (IV-2607) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Programming  Info 

MoviesFormat.h 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'©day' 

User  data  list  entry  atom:  creation  date. 

struct  Movi  estlserData  { 
long  size; 

long  udType; 

char  da ta [  1  ] ; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
udType 

Constant  kllserDataTextCreati  on  Date,  designating  atom  type  '©day see  "User 
Data  Identifiers"  (IV-2696). 

data 

A  string  containing  the  creation  date. 

Parent  Atom 

'udta'  (IV-2607) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Programming  Info 

MoviesFormat.h 


IV-2516 
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'©dir' 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'©dir' 


User  data  list  entry  atom:  name  of  movie's  director. 

struct  Movi esUserData  { 
long  size; 

long  udType; 

char  data [  1  ] ; 


ATM 


si  ze 

The  size  in  bytes  of  this  atom  structure. 
udType 

Constant  kllserDataTextDi  rector,  designating  atom  type  ’§di  r  see  "User  Data 
Identifiers"  (IV-2696). 

data 

A  string  containing  the  name  of  the  movie's  director. 

Parent  Atom 

'  udta '  ( I V - 2 60 7 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Programming  Info 

MoviesFormat.h 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'©edl' 


User  data  list  entry  atom:  edit  date  1. 

struct  Movi esUserData  { 
long  size; 

long  udType; 

char  data [  1  ] ; 
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IV-2517 
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'©fmt' 


si  ze 

The  size  in  bytes  of  this  atom  structure. 
udType 

Constant  ktlserDataTextEdi  tDatel,  designating  atom  type  '©edl see  "User 
Data  Identifiers"  (IV-2696). 

data 

A  string  containing  the  first  edit  date. 

Parent  Atom 

'  udta '  (IV-2607) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Discussion 

Similar  atoms  of  types  '©ed2'  through  '©ed9'  may  contain  other  edit  date  strings. 

Programming  Info 

MoviesFormat.h 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'©fmt' 


User  data  list  entry  atom:  indication  of  movie's  format. 

struct  Movi esUserData  { 
long  size; 

long  udType; 

char  da  ta [ 1 ] ; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
udType 

Constant  kllserDataTextOri  gi  nal  Format,  designating  atom  type  '©fmt see 
"User  Data  Identifiers"  (IV-2696). 

data 

A  string  indicating  the  movie's  format. 

Parent  Atom 

’udta'  (IV-2607) 

Parent  atom  can  contain  only  one  atom  of  this  type. 


IV-2518 
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'©inf' 


Programming  Info 

Movi esFormat . h 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'©inf' 


User  data  list  entry  atom:  information  about  the  movie. 


ATM 


struct  Movi esUserData  { 
long  size; 

long  udType; 

char  d  a  t  a [ 1 ] ; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
udType 

Constant  kUserDataTextlnf  ormati  on,  designating  atom  type  '©inf';  see  "User 
Data  Identifiers"  (IV-2696). 

data 

A  string  containing  information  about  the  movie. 

Parent  Atom 

'  udta '  ( I V - 2 60 7 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Programming  Info 

MoviesFormat.h 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'©prd' 


User  data  list  entry  atom:  name  of  movie's  producer. 

struct  Movi esUserData  { 
long  size; 

long  udType; 
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IV-2519 
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'©prf' 


char  da ta [  1  ] ; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
udType 

Constant  kUserDataTextProducer,  designating  atom  type  ' ©p r d ' ;  see  "User  Data 
Identifiers"  (IV-2696). 

data 

A  string  containing  the  name  of  the  movie's  producer. 

Parent  Atom 

’  udta 1  (IV-2607) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Programming  Info 

MoviesFormat.h 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'©prf' 


User  data  list  entry  atom:  names  of  performers. 

struct  Movi esUserData  { 
long  size; 

long  udType; 

char  data [ 1 ] ; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
udType 

Constant  kUserDataTextPerformers,  designating  atom  type  '©prf';  see  "User 
Data  Identifiers"  (IV-2696). 

data 

A  string  containing  names  of  the  performers. 

Parent  Atom 

'udta'  (IV-2607) 

Parent  atom  can  contain  only  one  atom  of  this  type. 


IV-2520 


Inside  QuickTime:  Atoms 


'©req' 


Programming  Info 

Movi esFormat . h 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'©req' 


User  data  list  entry  atom:  special  hardware  or  software  requirements. 


ATM 


struct  Movi esUserData  { 
long  size; 

long  udType; 

char  d  a  t  a [ 1 ] ; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
udType 

Constant  kUserDataTextSpeci  al  PI  aybackRequi  rements,  designating  atom  type 
'©req';  see  "User  Data  Identifiers"  (IV-2696). 

data 

A  string  detailing  special  hardware  or  software  requirements. 

Parent  Atom 

'  udta '  ( I V - 2 60 7 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Programming  Info 

MoviesFormat.h 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'©src' 


User  data  list  entry  atom:  credits  for  those  who  provided  movie  source  content. 

struct  Movi esUserData  { 
long  size; 

long  udType; 
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IV-2521 


Atoms 


'©wrt' 


char  da ta [  1  ] ; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
udType 

Constant  ktlserDataTextOri  ginal  Source,  designating  atom  type  '©src see 
"User  Data  Identifiers"  (IV-2696). 

data 

A  string  containing  credits  for  those  who  provided  movie  source  content. 

Parent  Atom 

'  udta '  (IV-2607) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Programming  Info 

MoviesFormat.h 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'©wrt' 


User  data  list  entry  atom:  name  of  movie's  writer. 

struct  Movi esUserData  { 
long  size; 

long  udType; 

char  data [ 1 ] ; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
udType 

Constant  kUserDataTextWri  ter,  designating  atom  type  '©wrt see  "User  Data 
Identifiers"  (IV-2696). 

data 

A  string  containing  the  name  of  the  movie's  writer. 

Parent  Atom 

'udta'  (IV-2607) 

Parent  atom  can  contain  only  one  atom  of  this  type. 


IV-2522 
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'crgn' 


Programming  Info 

Movi esFormat . h 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'crgn' 


Defines  a  clipping  region. 


ATM 


struct  RgnAtom  { 


1  ong 

size; 

1  ong 

atomType ; 

short 

rgnSi ze ; 

Rect 

rgnBBox; 

char 

d  a  t  a  [  1  ]  ; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  RgnCl  i  pAID,  designating  atom  type  '  crgn see  "Atom  ID  Codes" 
(IV-2649). 
rgnSi ze 

The  size  in  bytes  of  the  region. 
rgnBBox 

The  bounding  box  for  the  region. 

data 

Additional  data  if  the  clipping  region  is  not  rectangular. 

Parent  Atom 

'clip'  (IV-2513) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Programming  Info 

Movi esFormat . h 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 
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IV-2523 


Atoms 


'crsr' 


'crsr' 

Color  custom  cursor  child  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kSpri  teCursorBehavi  orAtomType,  designating  atom  type  '  crsr see 
"Atom  ID  Codes"  (IV-2649). 

data 

A  cursor  description. 

Parent  Atom 

' vrcp '  (IV-2612) 

Parent  atom  can  contain  multiple  atoms  of  this  type. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'cspd' 

Contains  the  connection  speed  currently  set  in  the  QuickTime  preferences. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  Connecti  onSpeedPref  sType,  designating  atom  type  '  cspd ';  see  "Atom 
ID  Codes"  (IV-2649). 

data 

The  connection  speed. 

See  Also 

See  the  GetQui  ckT i mePreference  (1-507)  and  SetQui  ckT i mePref  erence  (III — 1639) 
functions.  For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File 
Format  (listed  in  the  bibliography). 


IV-2524 
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'ctab' 


'ctab' 


Parent  Atom 


Discussion 


See  Also 


'cufa' 


Discussion 


Color  table  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  Col  orTabl  eAID,  designating  atom  type  '  ctab see  "Atom  ID  Codes" 
(IV-2649). 

data 

A  color  table. 

'moov '  (IV-2566) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Color  table  atoms  define  a  list  of  preferred  colors  for  displaying  the  movie  on 
devices  that  support  only  256  colors.  The  list  may  contain  up  to  256  colors. 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


Non-standard  cubic  QTVR  panorama  data  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Value  is  '  cufa  ' . 

data 

A  QTVRCubi  cFaceData  (IV-2393)  structure. 

Each  entry  in  the  QTVRCubi  cFaceData  structure  describes  one  face  of  the  polyhedron 
being  described. 


ATM 
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IV-2525 


Atoms 


'CURS' 


See  Also 


'CURS' 


Parent  Atom 


See  Also 


'cuvw' 


See  Also 


IV-2526 


For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


Custom  cursor  child  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kQTVRCursorAtomType,  designating  atom  type  'CURS';  see  "Atom  ID 
Codes"  (IV-2649). 

data 

A  cursor  description. 

' vrcp'  (IV-2612) 

Parent  atom  can  contain  multiple  atoms  of  this  type. 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


Cubic  view  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Value  is  '  cuvw ' . 

data 

A  QTVRCubi  cVi  ewAtom  (IV-2394)  structure. 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 
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'dasz' 


'dasz' 

Data  size  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kQTTargetDataSi  ze,  designating  atom  type  '  dasz see  "Atom  ID 
Codes"  (IV-2649). 


ATM 


A  QTTargetDataSize  (IV-2391)  structure. 

Parent  Atom 

'vide'  (IV-2610) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'dcom' 

Indicates  the  compression  algorithm  used  to  compress  a  movie. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  DataCompressionAtomAID,  designating  atom  type  '  d  c  om ' ;  see  "  Atom  ID 
Codes"  (IV-2649). 

data 

A  32-bit  constant  (see  below)  that  indicates  which  lossless  algorithm  was  used 
to  compress  the  movie  contained  in  the  parent  atom. 

Data  Constants 

Appl eDataCompressorSubType 

The  Apple  data  compressor;  value  is  '  a  dec ' . 
zl i bDataCompressorSubType 

The  zlib  data  compressor;  value  is  '  z  1  i  b ' . 
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'defi' 


Parent  Atom 

' cmov '  (IV-2514) 

Parent  atom  can  contain  only  one  atom  of  this  type. 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'defi' 


A  sprite  image  data  reference  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kSpri  telmageDefaul  tlmagelndexAtomType,  designating  atom  type 
'  defi see  "Atom  ID  Codes"  (IV-2649). 

data 

The  image  index  of  a  traditional  image,  of  type  short,  to  use  while  waiting  for 
the  referenced  image  to  load. 

Parent  Atom 

'imag'  (IV-2547) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Discussion 

You  use  the  this  atom  type  to  specify  that  an  image  is  referenced  and  how  to  access 
it.  Its  ID  should  be  1. 

Version  Notes 

Added  to  QuickTime  4. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'desc' 


Graphics  export  description  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 


IV-2528 
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'dflt' 


atomType 

Constant  kCustomHandl  erDesc,  designating  atom  type  '  desc see  "Atom  ID 
Codes"  (IV-2649). 

data 

A  nonterminated  string  containing  a  human-readable  format  name. 

Parent  Atom 

'expo'  ( I V - 2 5 3 5 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

See  the  Graphi  csExportGetMIMETypeLi  st  (1-577)  and 

Graphi  cs  ImportGetExportlmageTypeLi  st  (1-632)  functions.  For  general  information 
about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the 

bibliography). 


ATM 


'dflt' 


Key  frame  shared-data  atom. 

This  is  a  QT  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameter: 

atomType 

Constant  kSpriteSharedDataAtomType,  designating  atom  type  'dflt';  see  "Atom 
ID  Codes"  (IV-2649). 

Required  Child  Atoms 

' i met '  ( I V  -  2 549 ) 

Only  one  allowed. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'dimm' 


Number  of  bytes  of  immediate  data  to  be  sent. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 


Inside  QuickTime:  Atoms 


IV-2529 


Atoms 


'dinf' 


atomType 

Value  is  '  di mm' . 

data 

8-byte  value. 

Parent  Atom 

'hinf'  ( I V - 2541 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'dinf' 


Specifies  where  media  data  is  stored. 

struct  DatalnfoAtom  { 
long  size; 

long  atomType; 

DataRefAtom  dataRef; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  DatalnfoAID,  designating  atom  type  'di  nf see  "Atom  ID  Codes" 
(IV-2649). 

dataRef 

A  value  that  contains  the  data  for  this  atom.  The  4-byte  DataRefAtom  data  type 
is  private  and  is  not  documented. 

Optional  Child  Atoms 

'dref'  (IV-2532) 

Only  one  allowed. 

Programming  Info 

MoviesFormat.h 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


IV-2530 
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'dmax' 


'dmax' 


Parent  Atom 


See  Also 


'dmed' 


Parent  Atom 


See  Also 


The  largest  packet  duration. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Value  is  'dmax'. 

data 

4  bytes  packet  duration,  in  milliseconds. 

'hint'  ( I V - 2  54 1  ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


Number  of  bytes  from  the  media  track  to  be  sent. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Value  is  '  dmed ' . 

data 

8-byte  value. 

'hint'  ( I V - 2  54 1  ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


ATM 


Inside  QuickTime:  Atoms 


IV-2531 


Atoms 


'dref' 


'dref' 


Data  reference  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  DataRefAID,  designating  atom  type  'dref';  see  "Atom  ID  Codes" 
(IV-2649). 

data 

Data  references. 

Parent  Atom 

'  di nf '  (IV-2530) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

See  the  A1  i  asRecord  (IV-2159)  structure.  For  general  information  about  atoms,  see 
Inside  QuickTime:  QuickTime  File  Format  (listed  in  the  bibliography). 


'drep' 

Number  of  bytes  of  repeated  data  to  be  sent. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Value  is  'drep ' . 

data 

8-byte  value. 

Parent  Atom 

'hinf'  ( I V - 2  54 1 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


IV-2532 
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'edts' 


'edts' 


Contains  an  atom  that  defines  an  edit  list. 

struct  EditsAtom  { 

1  ong 
1  ong 

Ed 1 tLi stAtom 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  Ed i  tsAID,  designating  atom  type  '  edts see  "Atom  ID  Codes" 
(IV-2649). 

edi  tLi  st 

An  '  el  st '  (IV-2533)  atom. 

Parent  Atom 

'trak'  (IV-2600) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Required  Child  Atoms 

' el st '  (IV-2533) 

Only  one  allowed. 

Programming  Info 

Movi esFormat . h 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


size; 
atomType ; 
edi  tLi  st ; 


ATM 


'elst' 


Contains  a  list  of  edit  segment  definitions  for  a  media. 

struct  Edi tLi stAtom  { 

long  size; 

long  atomType; 

long  flags; 

long  numEntries; 

Edi  tLi  stType  edi  tLi  stTabl  e [  1  ] ; 


Inside  QuickTime:  Atoms 


IV-2533 


Atoms 


'end  ' 


si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  Edi  t Li  stAID,  designating  atom  type  '  el  st see  "Atom  ID  Codes" 
(IV-2649). 

fl  ags 

One  byte  of  version  information  followed  by  three  bytes  of  flags.  The  flag  bytes 
are  not  currently  used. 
numEntri es 

The  number  of  entries  in  edi  t Li  stTabl  e. 
edi t  L i stTabl e 

An  array  of  Edi  t  Li  stType  (IV-2241)  data  structures,  each  of  which  locates  and 
defines  an  edit  segment  within  a  media. 

Parent  Atom 

' edts '  ( I V - 2 5 3 3  ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Discussion 

You  can  use  the  edit  list  atom  to  tell  QuickTime  how  to  map  from  a  time  in  a  movie 
to  a  time  in  a  media,  and  ultimately  to  each  segment  of  the  media's  data. 

Programming  Info 

MoviesFormat.h 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'end ' 

Defines  the  ending  offset  of  hypertext  in  a  text  stream. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Value  is  '  end  '  (the  fourth  character  is  a  space). 

data 

The  ending  offset  of  hypertext  in  a  text  stream. 


IV-2534 


Inside  QuickTime:  Atoms 


'enda' 


Parent  Atom 

' htxt '  (IV-2546) 

Parent  atom  can  contain  only  one  atom  of  this  type. 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  Tile  Format 

(listed  in  the  bibliography). 


'enda' 


Determines  the  endian  status  of  the  sound  component  that  interprets  data 
contained  in  an  audio  atom  list. 

struct  Audi oEndi anAtom  { 
long  size; 

OSType  atomType; 

short  1 i ttl eEndi an ; 

}; 


ATM 


si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  kAudi  oEndi  anAtomType,  designating  atom  type  '  enda  see  "Atom  ID 
Codes"  (IV-2649). 

1 i ttl eEndi an 

Set  this  field  to  TRUE  if  the  audio  component  is  to  operate  on  little-endian  data, 
and  FALSE  otherwise. 


Programming  Info 

Sound . h 

See  Also 

To  choose  the  sound  component  for  an  audio  atom  list,  see  the  '  f  rma '  (IV-2538) 
atom.  For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File 
Format  (listed  in  the  bibliography). 

'expo' 


Defines  a  graphics  export  group. 


Inside  QuickTime:  Atoms 


IV-2535 


Atoms 


'ext ' 


This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameters: 

atomType 

Constant  kGraphi  csExportGroup,  designating  atom  type  '  expo see  "Atom  ID 
Codes"  (IV-2649). 

Required  Child  Atoms 

'ftyp'  (IV-2539) 

An  OSType  representing  the  exported  file  type. 

'ext  '  ( I V - 2 5 3 6 ) 

A  nonterminated  string  containing  the  suggested  file  extension  for  this  format. 
' desc '  (IV-2528) 

A  nonterminated  string  containing  a  human-readable  name  for  this  format. 

Optional  Child  Atoms 

'mime'  (IV-2561) 

A  nonterminated  string  containing  the  MIME  type  for  this  format. 

See  Also 

See  the  Graphi  cs  ImportGetExportlmageTypeLi  st  (1-632)  function.  For  general 
information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the 

bibliography). 

'ext' 


Defines  a  graphics  export  extension. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kGraphicsExportExtension,  designating  atom  type  'ext  '  (the  fourth 
character  is  a  space);  see  "Atom  ID  Codes"  (IV-2649). 

data 

A  nonterminated  string  containing  a  file  extension. 

Parent  Atom 

'expo'  (IV-2535) 

Parent  atom  can  contain  only  one  atom  of  this  type. 


IV-2536 
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See  Also 


'flap' 


See  the  Graphi  csImportGetExportlmageTypeLi  st  (1-632)  function.  For  general 
information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the 

bibliography). 


'flap' 


Extension  to  the  SoundDescri  pti  on  (IV-2449)  structure. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  si  SI  opeAndlntercept,  designating  atom  type  'flap';  see  "Sound 
Information  Selectors"  (IV-2693). 

data 

A  SoundSl  opeAndlnterceptRecord  (IV-2456)  structure. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


ATM 


'flov' 


Contains  a  floating-point  variable  for  a  sprite. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Value  is  'flov'. 

Parent  Atom 

'vars'  (IV-2610) 

Contains  variables  for  a  sprite. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 
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IV-2537 


Atoms 


'free' 


'free' 


Provides  unused  space  in  a  movie  file. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  Free  AtomType,  designating  atom  type  '  f  ree see  "Atom  ID  Codes" 
(IV-2649). 

data 

Any  number  of  bytes  of  free  space. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'frma' 


Specifies  which  sound  component  is  responsible  for  the  atoms  contained  in  an 
audio  atom  list. 


struct  Audi oFormatAtom  { 
long  size; 

OSType  atomType; 

OSType  format; 


si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  kAudi  oFormatAtomType,  designating  atom  type  '  frma  see  "Atom  ID 
Codes"  (IV-2649). 

format 

A  constant  that  identifies  a  sound  component.  See  "Codec  Identifiers" 
(IV-2655). 


Programming  Info 

Sound . h 


IV-2538 
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'ftyp' 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'ftyp' 

Defines  a  graphics  export  file  type. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kGra phi  cs  Export Fi  1  eType,  designating  atom  type  '  ftyp see  "Atom 
ID  Codes"  (IV-2649). 

data 

An  OSType  representing  the  exported  file  type. 

Parent  Atom 

'expo'  ( I V - 2 5 3 5 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

See  the  Graphi  csImportGetExportlmageTypeLi  st  (1-632)  function.  For  general 
information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the 

bibliography). 


ATM 


'gmhd' 

Contains  a  generic  media  information  atom. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Constant  Generi  cMedi  a  InfoHeaderAID,  designating  atom  type  '  gmhd ';  see  "Atom 
ID  Codes"  (IV-2649). 

Parent  Atom 

'minf' [generic]  ( IV-2562) 

Parent  atom  can  contain  only  one  atom  of  this  type. 
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IV-2539 


Atoms 


'gmin' 


Required  Child  Atoms 

'gmin'  (IV-2540) 

Provides  data  that  is  specific  to  a  handler  for  media  other  than  video  or  sound. 
Only  one  allowed. 

Discussion 

This  atom  is  currently  used  only  as  a  container  for  a  'gmin'  (IV-2540)  atom. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  Tile  Format 

(listed  in  the  bibliography). 

'gmin' 


Provides  data  that  is  specific  to  a  handler  for  media  other  than  video  or  sound. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  Generi  cMedi  alnfoAID,  designating  atom  type  '  gmi n see  "Atom  ID 
Codes"  (IV-2649). 

data 

Data  required  by  the  media  handler  that  is  designated  by  the  '  hdl  r '  (IV-2540) 
atom  contained  in  the  'minf'[generic]  (IV-2562)  atom  that  also  contains  the 
parent  of  this  atom. 

Parent  Atom 

' gmhd '  (IV-2539) 

Parent  atom  can  contain  any  number  of  atoms  of  this  type. 

Discussion 

This  atom  contains  handler-specific  information  to  support  your  use  of  a 

'mirif'  [generic]  (IV-2562)  atom.  Note  that  the  data  in  this  atom  is  not  used  by  RTP 

servers. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'hdlr' 


Specifies  the  component  that  is  to  interpret  a  media's  data. 


IV-2540 
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'hinf' 


struct  HandlerAtom  { 

long  size; 

long  atomType; 

Publ i cHandl erlnfo  hlnfo; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  Handl  erAID,  designating  atom  type  '  hdl  r see  "Atom  ID  Codes" 
(IV-2649). 

hlnfo 

APublicHandlerlnfo  (IV-2341)  structure,  which  contains  the  actual  data  for  this 
atom. 

Discussion 

RTP  servers  ignore  this  atom's  data  when  it  is  contained  in  a  'minf'[generic] 
(IV-2562)  atom. 

Programming  Info 

Movi esFormat . h 

See  Also 

For  the  atoms  that  may  contain  this  atom,  see  'mdia'  (IV-2560),  'mi  nf '  [generi  c] 
(IV-2562),  'minf'  [sound]  (IV-2564),  and  'mi  nf '  [vi  deo]  (IV-2565).  For  general 
information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the 

bibliography). 


ATM 


f 


hinf' 


Contains  statistics  for  the  hint  track. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Value  is  'hinf'. 

Required  Child  Atoms 

' trpy '  (IV-2603) 

Total  number  of  bytes  that  will  be  sent,  including  12-byte  RTP  headers  but  not 
including  network  headers.  Only  one  allowed. 
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IV-2541 


Atoms 


'hint' 


'nump'  (IV-2570) 

Total  number  of  network  packets  that  will  be  sent.  Only  one  allowed. 

' tpyl  '  (IV-2600) 

Total  number  of  bytes  that  will  be  sent,  not  including  12-byte  RTP  headers. 
Only  one  allowed. 

' maxr '  (IV-2558) 

Maximum  data  rate.  Only  one  allowed. 

' dmed '  (IV-2531) 

Number  of  bytes  from  the  media  track  to  be  sent.  Only  one  allowed. 

'dimm'  (IV-2529) 

Number  of  bytes  of  immediate  data  to  be  sent.  Only  one  allowed. 

'drep'  (IV-2532) 

Number  of  bytes  of  repeated  data  to  be  sent.  Only  one  allowed. 

' tmi n '  ( I V - 2 5 9 9  ) 

Smallest  relative  transmission  time,  in  milliseconds.  Only  one  allowed. 

' tmax '  (IV-2598) 

Largest  relative  transmission  time,  in  milliseconds.  Only  one  allowed. 

' pmax '  (IV-2572) 

Largest  packet,  in  bytes,  including  12-byte  RTP  header.  Only  one  allowed. 

' dmax '  (IV-2531) 

The  largest  packet  duration.  Only  one  allowed. 

' payt '  (IV-2571) 

Payload  type.  Only  one  allowed. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  Tile  Format 

(listed  in  the  bibliography). 


'hint' 

Hint  track  reference  type  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Value  is  'hint'. 


IV-2542 
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'hlit' 


data 

A  list  of  track  ID  values  (32-bit  integers)  specifying  the  related  tracks.  Note  that 
a  track  ID  value  can  be  set  to  0  to  indicate  an  unused  entry  in  the  atom.  Doing 
this  can  be  more  convenient  than  deleting  the  reference. 

Parent  Atom 

'tret'  ( I V - 2 60 2 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'hlit' 


ATM 


Defines  the  highlighted  portion  in  text. 

struct  HiliteAtom  { 
long  size; 

long  atomType; 

long  selStart; 

long  selEnd; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Value  is  'hlit'. 
sel Start 

Character  number  of  highlighted  selection  start  character, 
sel End 

Character  number  of  highlighted  selection  end  character. 

Discussion 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

Programming  Info 

MoviesFormat.h 
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IV-2543 


Atoms 


'hnti' 


'hnti' 


Hint  track  user  data  atom. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Value  is  '  hnti ' . 

Required  Child  Atoms 

' sdp  ’  (IV-2582) 

SDP  text  for  a  hint  track.  Only  one  allowed. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'hots' 

A  QTVR  hot  spot. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Constant  kQTVRHotSpotAtomType,  designating  atom  type  '  hots  ';  see  "Atom  ID 
Codes"  (IV-2649). 

Parent  Atom 

' hspa  '  ( I V - 2 54 5  ) 

Parent  atom  can  contain  any  number  of  atoms  of  this  type. 

Required  Child  Atoms 

'hsin'  ( I V - 2  54  5 ) 

Contains  general  hot  spot  information.  Only  one  allowed. 

'link'  ( I V - 2  5  5  6 ) 

Specific  information  about  a  link  hot  spot.  Only  one  allowed. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


IV-2544 
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'hsin' 


'hsin' 


Contains  general  hot  spot  information. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kQTVRHotSpotlnfoAtomType,  designating  atom  type  '  hsi  n ';  see  "Atom 
ID  Codes"  (IV-2649). 


ATM 


Hot  spot  information. 

Parent  Atom 

'hots'  ( I V - 2544 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'hspa' 

Hot  spot  parent  atom. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Constant  kQTVRHotSpotParentAtomType,  designating  atom  type  '  hspa  ';  see 
"Atom  ID  Codes"  (IV-2649). 

Parent  Atom 

'  vrnp '  (IV-2614) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Required  Child  Atoms 

'hots'  ( I V - 2544 ) 

A  QTVR  hot  spot.  Any  number  allowed. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 
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IV-2545 


Atoms 


'htxt' 


'htxt' 

Hypertext  in  a  text  stream. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Value  is  '  htxt ' . 

Parent  Atom 

' wtxt '  (IV-2616) 

Parent  atom  can  contain  multiple  atoms  of  this  type. 

Required  Child  Atoms 

' strt '  (IV-2589) 

Defines  the  starting  offset  of  hypertext  in  a  text  stream.  Only  one  allowed. 

'end  ’  (IV-2534) 

Defines  the  ending  offset  of  hypertext  in  a  text  stream.  Only  one  allowed. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'idat' 


Image  data  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  qui  ckTimelmageFi  1  elmageDataAtom,  designating  atom  type  'idat';  see 
"Atom  ID  Codes"  (IV-2649). 

data 

The  image  data. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


IV-2546 
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'idsc' 


'idsc' 


Image  description  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  qui  ckTimelmageFi  1  elmageDescri  pt  1  on  Atom,  designating  atom  type 
'  i dsc see  "Atom  ID  Codes"  (IV-2649). 


ATM 


The  image  description. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'iicc' 


ColorSync  profile  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  qui  ckT i melmageFi  1  eCol  orSyncProf  i  1  eAtom,  designating  atom  type 
'iicc';  see  "Atom  ID  Codes"  (IV-2649). 

data 

A  ColorSync  profile. 

Version  Notes 

This  is  a  new  optional  atom  in  QuickTime  4. 

See  Also 

See  the  Graphi  csExportSetCol  orSyncProf  i  1  e  (1-589)  function.  For  general 
information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the 

bibliography). 

'imag' 


A  sprite  image  atom. 


Inside  QuickTime:  Atoms 


IV-2547 


Atoms 


'imap' 


This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Constant  kSpri  telmageAtomType,  designating  atom  type  '  imag see  "Atom  ID 
Codes"  (IV-2649). 

Parent  Atom 

' i met '  (IV-2549) 

Parent  atom  can  contain  any  number  of  atoms  of  this  type. 

Required  Child  Atoms 

' i mda '  (IV-2549) 

Contains  sprite  image  data.  Only  one  allowed. 

Optional  Child  Atoms 

'  name ' [spri te]  ( I V - 2 568 ) 

A  sprite  name  atom.  Only  one  allowed. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'imap' 

An  input  map. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Constant  InputMapAID,  designating  atom  type  '  imap ';  see  "Atom  ID  Codes" 
(IV-2649). 

Parent  Atom 

'trak'  (IV-2600) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Required  Child  Atoms 

'  in'  (IV-2554) 

Track  input  atom.  Only  one  allowed. 


IV-2548 


Inside  QuickTime:  Atoms 


'imct' 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'imct' 

A  sprite  image  container  atom. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Constant  kSpri  telmagesContai  nerAtomType,  designating  atom  type  '  i met see 
"Atom  ID  Codes"  (IV-2649). 

Parent  Atom 

'  df 1 1 '  ( I V - 2 5 2 9 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Required  Child  Atoms 

' 1  mag '  (IV-2547) 

Sprite  image  atom.  Any  number  allowed. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


ATM 


'imda' 


A  sprite  image  data. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kSpri  te  Image  Data  AtomType,  designating  atom  type  '  imda ';  see  "Atom 
ID  Codes"  (IV-2649). 

data 

Image  data. 
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'imgp' 


Parent  Atom 

'imag'  (IV-2547) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'imgp' 

Panorama  imaging  parent  atom. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Constant  kQTVRImagi  ng  Pa  rent  AtomType,  designating  atom  type  '  imgp see 
"Atom  ID  Codes"  (IV-2649). 

Required  Child  Atoms 

' i mpn '  (IV-2551) 

Panorama  imaging  atom.  Any  number  allowed. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'imgr' 

A  sprite  image  group  ID  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kSpri  telmageGroupIDAtomType,  designating  atom  type  '  imgr ';  see 
"Atom  ID  Codes"  (IV-2649). 

data 

The  group  ID,  of  type  long. 


IV-2550 
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'impn' 


Parent  Atom 

'imag'  (IV-2547) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Discussion 

Each  image  in  a  sprite  media  key  frame  sample  is  assigned  to  a  group.  Add  an  atom 
of  this  type  as  a  child  of  the  'imag'  (IV-2547)  atom  and  set  its  leaf  data  to  a  long 
containing  the  group  ID.  For  example,  if  the  sample  contains  ten  images  where  the 
first  two  images  are  equivalent,  and  the  last  eight  images  are  equivalent,  then  you 
could  assign  a  group  ID  of  1000  to  the  first  two  images,  and  a  group  ID  of  1001  to 
the  last  eight  images.  This  divides  the  images  in  the  sample  into  two  sets.  The  actual 
ID  does  not  matter,  it  just  needs  to  be  a  unique  positive  integer.  Note  that  you  must 
assign  group  IDs  to  your  sprite  sample  if  you  want  a  sprite  to  display  images  with 
non-equivalent  image  descriptions  (i.e.,  images  with  different  dimensions). 

Special  Considerations 

Although  QuickTime  does  not  currently  use  this  atom  internally,  tools  that  edit 
sprite  media  can  use  the  information  provided  to  optimize  certain  operations,  such 
as  cut,  copy,  and  paste. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


ATM 


'impn' 


Panorama  imaging  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QT  Insert  Chi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kQTVRPanoImagi  ngAtomType,  designating  atom  type  '  impn ';  see  "Atom 
ID  Codes"  (IV-2649). 

data 

A  QTVRPanoImagi  ngAtom  (IV-2398)  structure. 

Parent  Atom 

' imgp '  (IV-2550) 

Parent  atom  can  contain  any  number  of  atoms  of  this  type. 


Inside  QuickTime:  Atoms 
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'imre' 


Discussion 

A  QTVRPanoImagi  ngAtom  describes  the  default  imaging  characteristics  for  all  the 
panoramic  nodes  in  a  scene.  This  atom  overrides  QuickTime  VR's  own  defaults. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'imre' 

A  sprite  image  data  reference  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kSpri  te  Image  Data  Ref  AtomType,  designating  atom  type  '  imre see 
"Atom  ID  Codes"  (IV-2649). 

data 

The  data  reference,  which  is  similar  to  the  data  Ref  parameter  of  GetDataHandl  er 
(1-407). 

Parent  Atom 

'imag'  (IV-2547) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Discussion 

You  use  the  this  atom  type  to  specify  that  an  image  is  referenced  and  how  to  access 
it.  Add  this  atom  as  a  child  of  the  'imag'  (IV-2547)  atom  instead  of  an  '  i  mda  ' 
(IV-2549)  atom.  Its  ID  should  be  1. 

Version  Notes 

Added  in  QuickTime  4. 

See  Also 

See  the  GetDataHandl  er  (1—407)  function.  For  general  information  about  atoms,  see 
Inside  QuickTime:  QuickTime  File  Format  (listed  in  the  bibliography). 

'imrg' 

Custom  sprite  image  registration  point  atom. 


IV-2552 
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'imrt' 


Parent  Atom 


Discussion 


See  Also 


'imrt' 


Parent  Atom 


Discussion 


This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kSpri  telmageRegi  strati  onAtomType,  designating  atom  type  '  i mrg 
see  "Atom  ID  Codes"  (IV-2649). 

data 

The  desired  sprite  registration  point,  a  FixedPoi  nt  (IV-2258)  structure. 

'imag'  (IV-2547) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Sprite  images  have  a  default  registration  point  of  0, 0.  To  specify  a  different  point, 
add  an  atom  of  this  type  as  a  child  atom  of  the  'imag'  (IV-2547)  and  set  its  leaf  data 
to  a  Fi  xedPoi  nt  value  with  the  desired  registration  point. 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


A  sprite  image  data  reference  type  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kSpri  telmageDataRefTypeAtomType,  designating  atom  type  '  i  mrt ';  see 
"Atom  ID  Codes"  (IV-2649). 

data 

The  data  reference  type,  which  is  similar  to  the  dataRefType  parameter  of 
GetDataHandl  er  (1-407). 

'imag'  (IV-2547) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

You  use  the  this  atom  type  to  specify  that  an  image  is  referenced  and  how  to  access 
it.  Add  this  atom  as  a  child  of  the  '  imag '  (IV-2547)  atom.  Its  ID  should  be  1. 


ATM 
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'  in' 


Version  Notes 

Added  in  QuickTime  4. 

See  Also 

See  the  GetDataHandl  er  (1—407)  function.  For  general  information  about  atoms,  see 
Inside  QuickTime:  QuickTime  File  Format  (listed  in  the  bibliography). 

'  in' 

Track  input  atom. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Value  '  in';  the  first  two  characters  are  spaces. 

Parent  Atom 

'imap'  ( I V - 2548 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Required  Child  Atoms 

'  ty'  (IV-2606) 

Input  atom  type.  Only  one  allowed. 

Optional  Child  Atoms 

'obid'  (IV-2571) 

Object  ID  atom.  Only  one  allowed. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'kmat' 

Defines  a  matte  for  a  track's  compressed  media. 

struct  MatteCompressedAtom  { 
long  size; 

long  atomType; 

long  flags; 

ImageDescription  mattelmageDescription; 
char  matteData[l] ; 


IV-2554 
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'krok' 


}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  MatteCompAID,  designating  atom  type  '  kmat see  "Atom  ID  Codes" 
(IV-2649). 

fl  ags 

One  byte  of  version  information  followed  by  three  bytes  of  flags.  The  flags 
bytes  are  not  currently  used. 
mattelmageDescri pti  on 

An  ImageDescri  pti  on  (IV-2285)  data  structure  for  the  matte. 
matteData 

An  array  of  matte  data. 

Programming  Info 

Movi esFormat . h 

See  Also 

For  the  structure  that  contains  this  atom,  see  the  '  matt '  (IV-2557)  atom.  For  general 
information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the 

bibliography). 


ATM 


'krok' 


Contains  a  KaraokeAtom  (IV-2298)  structure. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  '  krok ' . 

data 

A  KaraokeAtom  (IV-2298)  structure. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 
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'link' 


Contains  specific  information  about  a  link  hot  spot. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kQTVRLi  nklnfoAtomType,  designating  atom  type  '  1  i  nk';  see  "Atom  ID 
Codes"  (IV-2649). 

data 

Link  hot  spot  information. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  Tile  Format 

(listed  in  the  bibliography). 

'load' 


Contains  preloading  information  for  a  track. 

struct  TrackLoadSetti ngsAtom  { 
long  size; 

long  atomType; 

TrackLoadSetti ngs  settings; 

}; 


si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  LoadSetti  ngs  AID,  designating  atom  type  '  1  oad see  "Atom  ID  Codes" 
(IV-2649). 

setti ngs 

A  TrackLoadSetti  ngs  (IV-2491)  data  structure,  which  contains  the  actual  data 
for  this  atom. 


Programming  Info 

MoviesFormat.h 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


IV-2556 
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'LOOP' 


User  data  list  entry  atom:  looping  style. 

struct  Movi esUserData  { 
long  size; 

long  udType; 

char  da ta [  1  ] ; 


si  ze 

The  size  in  bytes  of  this  atom  structure. 
udType 

Value  is  '  LOOP'. 


ATM 


data 

A  long  integer:  0  for  none,  1  for  looping,  2  for  palindromic  looping. 

Parent  Atom 

'  udta '  ( I V - 2 60 7 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Programming  Info 

MoviesFormat.h 


See  Also 

See  the  Movi  esUserData  (IV-2319)  structure.  For  general  information  about  atoms, 
see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the  bibliography). 


'matt' 


Defines  a  matte  for  a  track's  media. 

struct  MatteAtom  { 

1  ong 
1  ong 

MatteComp res sed Atom 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  MatteAI  D,  designating  atom  type  ’  matt ' ;  see  "Atom  ID  Codes" 
(IV-2649). 


size; 
atomType ; 
aCompressedMatte ; 
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'maxr' 


aCompressedMatte 

A  'kmat'  (IV-2554)  atom. 

Required  Child  Atoms 

'kmat'  (IV-2554) 

Only  one  allowed. 

Programming  Info 

MoviesFormat.h 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'maxr' 


Maximum  data  rate. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Value  is  '  maxr  ’ . 

data 

8  bytes. 

Parent  Atom 

'hint'  (IV-2541) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'mdat' 


Media  data  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 


IV-2558 
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'mdhd' 


atomType 

Constant  Movi  eDataAtomType,  designating  atom  type  '  mdat see  "Atom  ID 
Codes"  (IV-2649). 

data 

Media  data. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'mdhd' 


ATM 


Specifies  the  characteristics  of  a  media. 

struct  Medi aHeaderAtom  { 
long  size; 

long  atomType; 

MediaHeader  header; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  Medi  a  Header  AID,  designating  atom  type  'mdhd see  "Atom  ID  Codes" 
(IV-2649). 

header 

A  Medi  aHeader  (IV-2305)  data  structure,  which  contains  the  actual  data  for  this 
atom. 

Parent  Atom 

' mdi a '  (IV-2560) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Programming  Info 

Movi esFormat . h 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 
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IV-2559 


Atoms 


'mdia' 


'mdia' 

Defines  the  media  for  a  movie  track. 

struct  Medi aDi rectory  { 

long  size; 

long  atomType; 

Medi aHeaderAtom  mediaHeader; 

HandlerAtom  medi aHandl er ; 

Medialnfo  medialnfo; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  Medi aAID,  designating  atom  type  'mdi  a  ';  see  "Atom  ID  Codes" 
(IV-2649). 

medi aHeader 

A  '  mdhd '  (IV-2559)  atom  that  specifies  general  characteristics  of  the  media, 
medi aHandl er 

A  '  hdl  r '  (IV-2540)  atom  that  defines  a  handler  for  the  media, 
medi alnfo 

A  'mint'  [generic]  (IV-2562)  atom  structure  that  contains  data  to  be  passed  to 
the  media  handler. 

Parent  Atom 

■trak'  (IV-2600) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Required  Child  Atoms 

'mdhd'  (IV-2559) 

General  characteristics  of  the  media.  Only  one  allowed. 

Optional  Child  Atoms 

'hdl r '  (IV-2540) 

The  type  of  media  this  atom  contains.  Only  one  allowed. 

'minf'lgeneric]  (IV-2562) 

Data  that  is  specific  to  a  media  handler.  Only  one  allowed. 

'  udta '  (IV-2607) 

User  data  atom.  Only  one  allowed. 


IV-2560 
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Discussion 

The  '  hdl  r '  atom  specifies  what  type  of  media  this  atom  contains;  for  example,  video 
or  sound.  The  content  of  the  'minf'[generic]  atom  is  specific  to  the  media  handler 
that  is  to  interpret  the  media. 

Programming  Info 

MoviesFormat.h 

See  Also 

See  the  Medi  aHeader  (IV-2305)  structure.  For  general  information  about  atoms,  see 
Inside  QuickTime:  QuickTime  File  Format  (listed  in  the  bibliography). 
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'mime' 


Defines  a  graphics  export  MIME  type. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kGraphi  csExportMIMEType,  designating  atom  type  'mi me ';  see  "Atom 
ID  Codes"  (IV-2649). 

data 

A  nonterminated  string  containing  a  MIME  type. 

Parent  Atom 

'expo'  ( I V - 2 5 3 5 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

See  the  Graphi  csImportGetExportlmageTypeLi  st  (1-632), 

Graphi  cs  ImportGetMIMETypeLi  st  (1-641),  and  Graphi  csExportGetMIMETypeLi  st 
(1-577)  functions.  For  general  information  about  atoms,  see  Inside  QuickTime: 
QuickTime  File  Format  (listed  in  the  bibliography). 


'minf'[base] 


Provides  data  that  is  specific  to  a  handler  for  media  other  than  video  or  sound. 

struct  Medialnfo  { 
long  size; 

long  atomType; 
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'minf' [generic] 


si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  Medi  alnfoAID,  designating  atom  type  'mint';  see  "Atom  ID  Codes" 
(IV-2649). 

Parent  Atom 

■nidi  a'  (IV-2560) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Required  Child  Atoms 

' gmhd '  (IV-2539) 

Generic  media  information  atom.  Only  one  allowed. 

' gmi n '  (IV-2540) 

Provides  data  that  is  specific  to  a  handler  for  media  other  than  video  or  sound. 
Only  one  allowed. 

Discussion 

Media  information  atoms  store  handler-specific  information  for  the  media  data  that 
constitutes  a  track.  The  media  handler  uses  this  information  to  map  from  media 
time  to  media  data.  The  format  and  content  of  media  information  atoms  are  dictated 
by  the  media  handler  that  is  responsible  for  interpreting  the  media  data  stream. 
Another  media  handler  would  not  know  how  to  interpret  this  information. 

Programming  Info 

MoviesFormat.h 

See  Also 

This  isotope  of  the  'minf'  atom  provides  data  that  is  specific  to  a  handler  for  media 
other  than  video  or  sound.  Handler-specific  data  for  sound  and  video  are  provided 
by  the  'mi  nf '  [sound]  (IV-2564)  atom  and  the  'minf '  [video]  (IV-2565)  atom.  For 
general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  Tile  Format  (listed 
in  the  bibliography). 


'minf' [generic] 


Provides  data  that  is  specific  to  a  handler  for  media  other  than  video  or  sound. 

struct  Medialnfo  { 
long  size; 

long  atomType; 


IV-2562 
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'minf'  [generic] 


si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  Medi  a  Inf  oAID,  designating  atom  type  'minf';  see  "Atom  ID  Codes" 
(IV-2649). 

Parent  Atom 

'India'  (IV-2560) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Required  Child  Atoms 

' gmhd '  (IV-2539) 

Generic  media  information  atom.  Only  one  allowed. 

'  hdl r '  (IV-2540) 

The  type  of  media  this  atom  contains.  Only  one  allowed. 

Optional  Child  Atoms 

'dinf'  (IV-2530) 

Specifies  where  media  data  is  stored.  Only  one  allowed. 

' stbl '  ( I V - 2 58 7 ) 

Contains  information  for  converting  from  media  time  to  sample  number  to 
sample  location  and  indicates  how  to  interpret  samples  and  chunks.  Only  one 
allowed. 

Discussion 

Media  information  atoms  store  handler-specific  information  for  the  media  data  that 
constitutes  a  track.  The  media  handler  uses  this  information  to  map  from  media 
time  to  media  data.  The  format  and  content  of  media  information  atoms  are  dictated 
by  the  media  handler  that  is  responsible  for  interpreting  the  media  data  stream. 
Another  media  handler  would  not  know  how  to  interpret  this  information. 

Programming  Info 

Movi esFormat . h 

See  Also 

This  isotope  of  the  'minf'  atom  provides  data  that  is  specific  to  a  handler  for  media 
other  than  video  or  sound.  Handler-specific  data  for  sound  and  video  are  provided 
by  the  'minf '  [sound]  (IV-2564)  atom  and  the  ' mi nf '  [vi  deo]  (IV-2565)  atom.  For 
general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed 
in  the  bibliography). 


ATM 
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Atoms 


'minf' [sound] 


'minf' [sound] 


Sound  media  information  atom. 

struct  Medialnfo  { 
long  size; 

long  atomType; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  Medi  alnfoAID,  designating  atom  type  'mint';  see  "Atom  ID  Codes" 
(IV-2649). 

Parent  Atom 

'India'  (IV-2560) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Required  Child  Atoms 

' smhd '  (IV-2584) 

Contains  sound  stereo  balance  information.  Only  one  allowed. 

'  hdl r '  (IV-2540) 

The  type  of  media  this  atom  contains.  Only  one  allowed. 

Optional  Child  Atoms 

' di nf '  ( I V - 2 5 3 0  ) 

Specifies  where  media  data  is  stored.  Only  one  allowed. 

' stbl '  (IV-2587) 

Contains  information  for  converting  from  media  time  to  sample  number  to 
sample  location  and  indicates  how  to  interpret  samples  and  chunks.  Only  one 
allowed. 

Discussion 

Media  information  atoms  store  handler-specific  information  for  the  media  data  that 
constitutes  a  track.  The  media  handler  uses  this  information  to  map  from  media 
time  to  media  data.  The  format  and  content  of  media  information  atoms  are  dictated 
by  the  media  handler  that  is  responsible  for  interpreting  the  media  data  stream. 
Another  media  handler  would  not  know  how  to  interpret  this  information. 

Programming  Info 

MoviesFormat.h 


IV-2564 
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'minf'[video] 


See  Also 

This  isotope  of  the  '  mi  nf '  atom  provides  handler-specific  data  for  sound. 
Handler-specific  data  for  video  is  provided  by  the  the  'mi  nf '  [vi  deo]  (IV-2565) 
atom.  For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File 
Format  (listed  in  the  bibliography). 


'minf' [video] 

Video  media  information  atom. 

struct  Medialnfo  { 
long  size; 

long  atomType; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  Medi  a  Inf  oAID,  designating  atom  type  'minf';  see  "Atom  ID  Codes" 
(IV-2649). 

Parent  Atom 

' md i a '  (IV-2560) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Required  Child  Atoms 

' vmhd ' [medi a]  (IV-2611) 

Stores  handler-specific  information  for  video  media  in  a  track.  Only  one 
allowed. 

'  hdl r '  (IV-2540) 

The  type  of  media  this  atom  contains.  Only  one  allowed. 

Optional  Child  Atoms 

'dinf'  (IV-2530) 

Specifies  where  media  data  is  stored.  Only  one  allowed. 

'  stbl '  ( I V - 2 587 ) 

Contains  information  for  converting  from  media  time  to  sample  number  to 
sample  location  and  indicates  how  to  interpret  samples  and  chunks.  Only  one 
allowed. 

Discussion 

Media  information  atoms  store  handler-specific  information  for  the  media  data  that 
constitutes  a  track.  The  media  handler  uses  this  information  to  map  from  media 


ATM 
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IV-2565 


Atoms 


'moov' 


time  to  media  data.  The  format  and  content  of  media  information  atoms  are  dictated 
by  the  media  handler  that  is  responsible  for  interpreting  the  media  data  stream. 
Another  media  handler  would  not  know  how  to  interpret  this  information. 

Programming  Info 

MoviesFormat.h 

See  Also 

This  isotope  of  the  'mint'  atom  provides  handler-specific  data  for  video. 
Handler-specific  data  for  sound  is  provided  by  the  'minf'[sound]  (IV-2564)  atom. 
For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'moov' 

Contains  the  top-level  atoms  that  constitute  a  movie. 

struct  Movi eDi rectory  { 

1  ong 
1  ong 

Movi eHeaderAtom 
Cl i ppi ngAtom 
TrackDi rectory  Entry 
UserDataAtom 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  Movi  eAID,  designating  atom  type  'moov see  "Atom  ID  Codes" 
(IV-2649). 

header 

A  '  mvhd '  (IV-2567)  atom  that  specifies  the  general  characteristics  of  the  movie, 
movi eCl i p 

A  'clip'  (IV-2513)  atom  that  defines  the  clipping  region  for  the  movie, 
track 

An  array  of  one  or  more  TrackDi  rectory  Entry  (IV-2489)  data  structures,  each  of 
which  includes  a  '  tra k '  (IV-2600)  atom  that  defines  a  track  in  the  movie. 

userData 

A  '  udta  '  (IV-2607)  atom,  which  contains  user  data. 


size; 
atomType ; 
header ; 
movi eCl i p ; 
track[l] ; 
userData ; 


IV-2566 
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Required  Child  Atoms 

'mvhd'  ( I V - 2 5 6 7 ) 

Specifies  the  general  characteristics  of  a  movie.  Only  one  allowed. 

Optional  Child  Atoms 

'clip'  (IV-2513) 

Defines  the  clipping  region  for  the  movie.  Only  one  allowed. 

'trak'  (IV-2600) 

Defines  a  single  track  of  the  movie.  Any  number  allowed. 

' udta '  ( I V - 2 60 7 ) 

User  data  atom.  Only  one  allowed. 

' ctab '  (IV-2525) 

Color  table  atom.  Only  one  allowed. 

Discussion 

You  use  movie  atoms  to  specify  the  information  that  defines  a  movie;  that  is,  the 
information  that  allows  your  application  to  understand  the  data  that  is  stored  in  the 
movie  data  atom.  The  movie  atom  contains  the  movie  header  atom,  which  defines 
the  time  scale  and  duration  information  for  the  entire  movie,  as  well  as  its  display 
characteristics.  In  addition,  the  movie  atom  contains  each  track  in  the  movie. 

Programming  Info 

Movi esFormat . h 

See  Also 

See  the  Movi  eHeader  (IV-2316)  structure.  For  general  information  about  atoms,  see 
Inside  QuickTime:  QuickTime  Tile  Format  (listed  in  the  bibliography). 


ATM 


'mvhd' 


Specifies  the  characteristics  of  an  entire  movie. 

struct  Movi eHeaderAtom  { 
long  size; 

long  atomType; 

MovieHeader  header; 


si  ze 

The  size  in  bytes  of  this  atom  structure. 
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'name'[sprite] 


atomType 

Constant  Movi eHeaderAID,  designating  atom  type  'mvhd see  "Atom  ID  Codes" 
(IV-2649). 

header 

A  Movi  eHeader  (IV-2316)  data  structure,  which  contains  the  actual  data  for  this 
atom. 

Parent  Atom 

' moov '  ( I V - 2 5 6 6 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Discussion 

You  use  the  movie  header  atom  to  specify  the  characteristics  of  an  entire  QuickTime 
movie.  The  data  contained  in  this  atom  defines  characteristics  of  the  entire 
QuickTime  movie,  such  as  time  scale  and  duration. 

Programming  Info 

MoviesFormat.h 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  Tile  Format 

(listed  in  the  bibliography). 

'name' [sprite] 

A  sprite  name  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kSpri  teNameAtomType,  designating  atom  type  '  name see  "Atom  ID 
Codes"  (IV-2649). 

data 

One  or  more  ASCII  characters  comprising  the  sprite's  name. 

Parent  Atom 

’  sprt 1  ( I V - 2584 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


IV-2568 
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'name'[userdata] 


User  data  list  entry  atom:  name  of  object. 

struct  Movi esUserData  { 
long  size; 

long  udType; 

char  data [ 1 ] ; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
udType 

Constant  kUserDataName,  designating  atom  type  '  name see  "Atom  ID  Codes" 
(IV-2649). 

data 

A  name  string. 

Parent  Atom 

' udta '  ( I V - 2 607 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Programming  Info 

MoviesFormat.h 


See  Also 

See  the  Movi  esUserData  (IV-2319)  structure.  For  general  information  about  atoms, 
see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the  bibliography). 


'ndhd' 

Node  header  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kQTVRNodeHeaderAtomType,  designating  atom  type  '  ndhd see  "Atom 
ID  Codes"  (IV-2649). 

data 

Node  header  information. 
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'nloc' 


See  Also 


'nloc' 


Parent  Atom 


See  Also 


'nump' 


Parent  Atom 


For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


QTVR  node  location  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kQTVRNodeLocati  on  AtomType,  designating  atom  type  '  nl  oc see  "Atom 
ID  Codes"  (IV-2649). 

data 

Node  location. 

' vrni '  (IV-2613) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


Total  number  of  network  packets  that  will  be  sent. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Value  is  'nump ' . 

data 

8  bytes. 

'hint'  ( I V - 2541 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 


IV-2570 
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See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'obid' 

Object  ID  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kTrackModifierObjectID,  designating  atom  type  'obid';  see  "Atom  ID 
Codes"  (IV-2649). 

data 

The  object  ID. 

Parent  Atom 

'  in'  (IV-2554) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


ATM 


'payt' 

Payload  type  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Value  is  '  payt ' . 

data 

Payload  type,  which  includes  payload  number  (32-bits)  followed  by  an  RTP 
map  payload  string  (a  Pascal  string). 

Parent  Atom 

'hint'  ( I V - 2 54 1  ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 
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'pdat' 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'pdat' 

Panorama  sample  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kQTVRPanoSampl  eDataAtomType,  designating  atom  type  '  pdat see 
"Atom  ID  Codes"  (IV-2649). 

data 

A  panorama  sample. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'pmax' 

Largest  packet,  in  bytes;  includes  12-byte  RTP  header. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Value  is  '  pmax' . 

data 

4  bytes. 

Parent  Atom 

'hint'  ( I V - 2  54 1  ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 
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'pnot' 

Reference  to  movie  preview  data. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  ShowFi  1  ePrevi  ewComponentType,  designating  atom  type  '  pnot see 
"Atom  ID  Codes"  (IV-2649). 


ATM 


Reference  to  a  movie  preview. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'ptv' 

Displays  a  movie  in  full  screen  mode. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

si  ze 

Value  is  OxOOOOOOOC. 
atomType 

Value  is  '  ptv  ' . 

Parent  Atom 

'moov '  (IV-2566) 

Contains  the  top-level  atoms  that  constitute  a  movie. 

Data  offsets 

0x00000000 

Display  size:  a  16-bit  little-endian  integer  (see  below)  indicating  the  display 
size  for  the  movie. 

0x00000002 

Reserved:  set  to  0. 
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'qdrg' 


0x00000004 

Reserved:  set  to  0. 

0x00000006 

Slide  show:  an  8-bit  Boolean  whose  value  is  1  for  a  slide  show.  In  slide  show 
mode,  the  movie  advances  one  frame  each  time  the  right-arrow  key  is  pressed. 
Audio  is  muted. 

0x00000007 

Play  on  open:  an  8-bit  boolean  whose  value  is  normally  1,  indicating  that  the 
movie  should  play  when  opened.  Since  there  is  no  visible  controller  in 
full-screen  mode,  applications  should  always  set  this  field  to  1  to  prevent  user 
confusion. 

Display  size  constants 

0x00000000 

The  movie  should  be  played  at  its  normal  size. 

0x00000001 

The  movie  should  be  played  at  double  size. 

0x00000002 

The  movie  should  be  played  at  half  size. 

0x00000003 

The  movie  should  be  scaled  to  fill  the  screen. 

0x00000004 

The  movie  should  be  played  at  its  current  size.  This  value  is  normally  used 
when  the  '  ptv  '  atom  is  inserted  transiently  and  the  movie  has  been 
temporarily  resized. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  Tile  Format 

(listed  in  the  bibliography). 

'qdrg' 

QuickDraw  region  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 


IV-2574 


Inside  QuickTime:  Atoms 


'rdrf' 


Discussion 

See  Also 

'rdrf' 


Parent  Atom 

Discussion 

See  Also 


atomType 

Constant  kTweenRegi  onData,  designating  atom  type  '  qdrg see  "Atom  ID 
Codes"  (IV-2649). 

data 

Two  Rect  (IV-2399)  structures  and  a  MacRegi  on  (IV-2303)  structure. 

This  atom's  ID  must  be  1. 

See  the  Tweener  Ini  ti  al  i  ze  (III— 1977)  function.  For  general  information  about  atoms, 
see  Inside  QuickTime:  QuickTime  Tile  Format  (listed  in  the  bibliography). 


Provides  a  reference  to  an  alternate  movie. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QT  Insert  Chi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  ReferenceMovi  eDataRef  AID,  designating  atom  type  ’  rdrf’;  see  "Atom 
ID  Codes"  (IV-2649). 

data 

A  ReferenceMovi  eDataRef  Record  (IV-2400)  data  structure.  The  alternate  movie 
referenced  by  this  structure  is  the  movie  associated  with  the  parent  ’  rmda  ’ 
(TV-2577)  atom. 

'rmda'  (IV-2577) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Alias  data  references  are  the  contents  ofAliasHandle 

(api>AliasHandle-Al  i  asHandl  e)  structures.  The  QuickTime  plug-in  is  smart  enough 
to  convert  a  relative  alias  to  a  relative  URL.  To  designate  the  anchor  file  for  a  relative 
alias,  pass  the  FSSpec  (IV-2262)  structure  that  specifies  the  file  you  are  creating.  You 
can  pass  absolute  or  relative  URLs;  if  the  movie  is  loaded  from  the  desktop, 
QuickTime  will  convert  a  relative  URL  into  a  relative  alias. 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


ATM 
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IV-2575 


Atoms 


'reso' 


'reso' 


Pi  xmap  resolution  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kQTResol  uti  onSetti  ngs,  designating  atom  type  '  reso see  "Atom  ID 
Codes"  (IV-2649). 

data 

A  QTResol  uti  onSetti  ngs  (IV-2362)  structure. 

Parent  Atom 

'vide'  (IV-2610) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Discussion 

This  atom  specifies  the  resolution  for  the  PixMap  (IV-2332)  structure  passed  to  the 
compressor. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  Tile  Format 

(listed  in  the  bibliography). 

'rmcd' 


Provides  component  availability  information  for  selecting  an  alternate  movie. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  ReferenceMovi  eComponentCheckAID,  designating  atom  type  '  rmcd ';  see 
"Atom  ID  Codes"  (IV-2649). 

data 

A  QTA1  tComponentCheckRecord  (IV-2345)  data  structure. 

Parent  Atom 

' rmda '  (IV-2577) 

Parent  atom  can  contain  any  number  of  atoms  of  this  type. 


IV-2576 


Inside  QuickTime:  Atoms 


'rmcs' 


See  Also 

See  the  QTA1  tComponentCheckRecord  (IV-2345)  structure.  For  general  information 
about  atoms,  see  Inside  QuickTime:  QuickTime  Tile  Format  (listed  in  the 

bibliography). 

'rmcs' 


Provides  CPU  speed  information  for  selecting  an  alternate  movie. 

This  is  a  QT  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  ReferenceMovi eCPURati ngAID,  designating  atom  type  '  rmcs  see 
"Atom  ID  Codes"  (IV-2649). 

data 

A  QTA1  tCPURati ngRecord  (IV-2346)  data  structure. 

Parent  Atom 

' rmda '  (IV-2577) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

See  the  QTA1  tCPURati  ngRecord  (IV-2346)  structure.  For  general  information  about 
atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the  bibliography). 


ATM 


'rmda' 


Provides  criteria  for  selecting  an  alternate  movie. 

This  is  a  QT  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameter: 

atomType 

Constant  ReferenceMovi  eDescri  ptorAID,  designating  atom  type  '  rmda  ';  see 
"Atom  ID  Codes"  (IV-2649). 

Parent  Atom 

' rmra '  (IV-2580) 

Parent  atom  can  contain  only  one  atom  of  this  type. 


Inside  QuickTime:  Atoms 


IV-2577 


Atoms 


'rmdr' 


Required  Child  Atoms 

'  rdrf '  (IV-2575) 

A  reference  to  an  alternate  movie.  Only  one  allowed. 

Optional  Child  Atoms 

'rmdr'  (IV-2578) 

Data  rate  information  for  selecting  an  alternate  movie.  Only  one  allowed. 

' rmvc '  ( I V - 2 58 1  ) 

Version  criteria  for  selecting  an  alternate  movie.  Multiples  allowed. 

' rmcd '  (IV-2576) 

Component  availability  information  for  selecting  an  alternate  movie.  Multiples 
allowed. 

'  rmqu '  (IV-2579) 

Playback  quality  information  for  selecting  an  alternate  movie.  Only  one 
allowed. 

' rml a '  (IV-2579) 

Language  information  for  selecting  an  alternate  movie.  Only  one  allowed. 

' rmcs '  ( I V - 2 5 7 7  ) 

CPU  speed  information  for  selecting  an  alternate  movie.  Only  one  allowed. 

Discussion 

The  'rdrf'  atom  contains  a  ReferenceMovieDataRef  Record,  which  designates  an 
alternate  movie.  The  '  rmda  '  atom's  optional  atoms  help  QuickTime  decide  whether 
or  not  to  run  that  movie.  If  multiple  ’  rmvc  ’  or  '  rmcd '  atoms  are  present,  all  their 
criteria  must  be  satisfied  for  the  movie  to  play. 

See  Also 

See  the  ReferenceMovi  eData  Ref  Record  (IV-2400)  structure.  For  general  information 
about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the 

bibliography). 

'rmdr' 

Provides  data  rate  information  for  selecting  an  alternate  movie. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  ReferenceMovi  eData  Rat  eA  ID,  designating  atom  type  '  rmdr ';  see  "Atom 
ID  Codes"  (IV-2649). 


IV-2578 


Inside  QuickTime:  Atoms 


'rmla' 


Parent  Atom 


See  Also 


'rmla' 


Parent  Atom 


See  Also 


'rmqu' 


data 

A  QTA1 tDataRateRecord  (IV-2347)  data  structure. 

' rmda '  (IV-2577) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


Provides  language  information  for  selecting  an  alternate  movie. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  ReferenceMovi  eLanguageAID,  designating  atom  type  '  rml  a  see  "Atom 
ID  Codes"  (IV-2649). 

data 

A  QTA1  tLanguageRecord  (IV-2348)  structure. 

'rmda'  (IV-2577) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


Provides  playback  quality  information  for  selecting  an  alternate  movie. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  ReferenceMovi  eQual  ityAID,  designating  atom  type  '  rmqu';  see  "Atom 
ID  Codes"  (IV-2649). 


ATM 
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IV-2579 


Atoms 


'rmra' 


data 

A  quality  value  of  type  S I  n  1 3  2 .  Higher  quality  values  are  selected  over  lower 
quality  values. 

Parent  Atom 

'  rmda '  (IV-2577) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Discussion 

If  the  criteria  established  by  the  'rmdr'  (IV-2578),  'rmvc'  (IV-2581),  and  'rmcd' 
(IV-2576)  atoms  are  equally  satisfied  by  two  or  more  alternate  movies,  the  one  with 
the  highest  quality  value  will  be  selected. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  Tile  Format 

(listed  in  the  bibliography). 


'rmra' 


Designates  a  reference  movie. 

This  is  a  QT  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameter: 

atomType 

Constant  ReferenceMovi  eRecordAID,  designating  atom  type  '  rmra see  "Atom 
ID  Codes"  (IV-2649). 

Parent  Atom 

' moov '  ( I V - 2 5 6 6 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Required  Child  Atoms 

'rmda'  (IV-2577) 

Provides  criteria  for  selecting  an  alternate  movie.  Only  one  allowed. 

Discussion 

You  insert  an  '  rmra  '  atom  in  a  '  moov '  atom  to  create  a  reference  movie.  Each  '  rmda  ’ 
atom  in  the  '  rmra  '  atom  designates  an  alternate  movie. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


IV-2580 


Inside  QuickTime:  Atoms 


'rmvc' 


'rmvc' 


Parent  Atom 


Discussion 


See  Also 


'sept' 


Parent  Atom 


Provides  version  criteria  for  selecting  an  alternate  movie. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  ReferenceMovi  eVersi  onCheckAID,  designating  atom  type  '  rmvc see 
"Atom  ID  Codes"  (IV-2649). 

data 

A  QTA1  tVersi  onCheckRecord  (IV-2348)  data  structure. 


' rmda '  (IV-2577) 

Parent  atom  can  contain  any  number  of  atoms  of  this  type. 

This  optional  atom  in  a  '  rmda '  atom  lets  you  demand  minimum  product  version 
criteria  for  selecting  an  alternate  movie.  For  example,  a  movie  that  needs  QuickTime 
VR  2.1  or  later  could  require  a  Gestalt  '  qtvv '  value  of  0x02100000  or  higher. 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


Transcript  track  reference  type  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Value  is  'sept ' . 

data 

A  list  of  track  ID  values  (32-bit  integers)  specifying  the  related  tracks.  Note  that 
a  track  ID  value  can  be  set  to  0  to  indicate  an  unused  entry  in  the  atom.  Doing 
this  can  be  more  convenient  than  deleting  the  reference. 

'tret'  ( I V - 2 60 2 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 


ATM 


Inside  QuickTime:  Atoms 


IV-2581 


Atoms 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'sdp ' 

SDP  text  for  a  hint  track. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Value  is  '  sdp  ' .  The  fourth  character  is  a  space. 

data 

SDP  text. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'sean' 


The  outermost  atom  container,  of  which  all  other  atoms  are  children. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203),  using  the  following  parameter: 

atomData 

A  pointer  to  a  memory  location  that  will  hold  the  new  atom. 

Discussion 

After  creating  a  '  sean '  atom,  you  can  populate  it  with  other  atoms  by  using 
QTInsertChi  1  d  (11-1183). 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'SelO' 


User  data  list  entry  atom:  play  selection  only. 


IV-2582 


Inside  QuickTime:  Atoms 


'skip' 


struct  Movi esUserData  { 
long  size; 

long  udType; 

char  data [  1  ] ; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
udType 

Constant  'SelO'. 


ATM 


A  byte  indicating  that  only  the  selected  area  of  the  movie  should  be  played. 

Parent  Atom 

' udta '  ( I V - 2 60 7  ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Programming  Info 

MoviesFormat.h 


See  Also 

See  the  Movi  esUserData  (IV-2319)  function.  For  general  information  about  atoms, 
see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the  bibliography). 


'skip' 

Unused  space  available  in  the  file. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  Ski  pAtomType,  designating  atom  type  'skip';  see  "Atom  ID  Codes" 
(IV-2649). 

data 

Any  number  of  bytes  of  free  space. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 
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IV-2583 


Atoms 


'smhd' 


'smhd' 


Contains  sound  stereo  balance  information. 

struct  SoundMedi alnfoHeaderAtom  { 
long  size; 

long  atomType; 

SoundMedialnfoHeader  smiHeader; 

}; 


si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  SoundMedialnfoHeaderAID,  designating  atom  type  '  smhd see  "Atom 
ID  Codes"  (IV-2649). 

smi Header 

A  SoundMedialnfoHeader  (IV-2453)  data  structure,  which  contains  the  actual 
data  for  this  atom. 


Discussion 

The  SoundMedialnfoHeader  data  structure  currently  contains  only  stereo  balance 
information. 

Programming  Info 

MoviesFormat.h 

See  Also 

For  the  structure  that  contains  this  atom,  see  'mi  nf'  [sound]  (IV-2564).  For  general 
information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the 

bibliography). 

'sprt' 


A  key  frame  sprite  definition. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kSpri  teAtomType,  designating  atom  type  '  sprt see  "Atom  ID  Codes" 
(IV-2649). 


IV-2584 


Inside  QuickTime:  Atoms 


'sprt' 


data 

A  list  of  sprite  property  constants  (see  below). 

Sprite  property  constants 

kSpri tePropertyMatri x 

(Value  is  1).  Describes  the  sprite's  location  and  scaling  within  its  sprite  world 
or  sprite  track.  By  modifying  a  sprite's  matrix,  you  can  modify  the  sprite's 
location  so  that  it  appears  to  move  in  a  smooth  path  on  the  screen  or  so  that  it 
jumps  from  one  place  to  another.  You  can  modify  a  sprite's  size,  so  that  it 
shrinks,  grows,  or  stretches.  Depending  on  which  image  compressor  is  used  to 
create  the  sprite  images,  other  transformations,  such  as  rotation,  may  be 
supported  as  well.  Translation-only  matrixes  provide  the  best  performance. 

kSpri tePropertyVi si bl e 

(Value  is  4).  Specifies  whether  or  not  the  sprite  is  visible.  To  make  a  sprite 
visible,  you  set  the  sprite's  visible  property  to  true. 
kSpri te Property Layer 

(Value  is  5).  Contains  a  16-bit  integer  value  specifying  the  layer  into  which  the 
sprite  is  to  be  drawn.  Sprites  with  lower  layer  numbers  appear  in  front  of 
sprites  with  higher  layer  numbers.  To  designate  a  sprite  as  a  background  sprite, 
you  should  assign  it  the  special  layer  number  kBackgroundSpri  teLayerNum. 

kSpri tePropertyGraphi csMode 

(Value  is  6).  Specifies  a  graphics  mode  and  blend  color  that  indicates  how  to 
blend  a  sprite  with  any  sprites  behind  it  and  with  the  background.  To  set  a 
sprite's  graphics  mode,  you  call  SetSpri  teProperty  (III— 1641),  passing  a  pointer 
to  a  Modi  f i  erT rackGraphi  csModeRecord  (IV-2311)  structure. 

kSpri tePropertyActi onHandl i ngSpri telD 

(Value  is  8).  Specifies  another  sprite  by  ID  that  delegates  QT  events. 
kSpri teProperty I mage  Index 

(Value  is  100).  Contains  the  atom  ID  of  the  sprite's  image  atom. 
kSpri teUses ImagelDsAtomType 

(Value  is  '  uses').  Lets  a  sprite  specify  the  subset  of  images  that 
kSpritePropertylmagelndex  can  refer  to. 

Parent  Atom 

'stss'  (IV-2593) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Discussion 

Sprite  atoms  should  have  ID  numbers  start  at  1  and  count  consecutively  upward. 


ATM 


Inside  QuickTime:  Atoms 


IV-2585 


Atoms 


'sptl' 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'sptl' 


Specifies  which  graphics  export  compressor  to  use,  its  depth,  and  the  spatial 
quality. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  scSpati al  Setti ngsType,  designating  atom  type  'sptl  see  "Atom  ID 
Codes"  (IV-2649). 

data 

A  pointer  to  SCSpati  al  Setti  ngs  (IV-2423)  structure. 

See  Also 

See  the  Graphi  csExportCanllseCompressor  (1-553)  function.  For  general  information 
about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the 

bibliography). 

'ssrc' 


Nonprimary  source  track  reference  type  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kT rackModi  f  i  erReference,  designating  atom  type  '  ssrc ';  see  "Atom 
ID  Codes"  (IV-2649). 

data 

A  list  of  track  ID  values  (32-bit  integers)  specifying  the  related  tracks.  Note  that 
a  track  ID  value  can  be  set  to  0  to  indicate  an  unused  entry  in  the  atom.  Doing 
this  can  be  more  convenient  than  deleting  the  reference. 


IV-2586 


Inside  QuickTime:  Atoms 


'sstr' 


Parent  Atom 

'tref'  ( I V  -  2  60  2 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  Tile  Format 

(listed  in  the  bibliography). 


'sstr' 


Specifies  the  ID  of  a  string  variable,  contained  in  a  sprite  track,  to  display  in  the 
status  area  of  the  browser. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Value  is  '  sstr ' . 

Parent  Atom 

'beha'  (IV-2512) 

Defines  sprite  behavior. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


ATM 


'stbl' 


Contains  information  for  converting  from  media  time  to  sample  number  to  sample 
location  and  indicates  how  to  interpret  samples  and  chunks. 


struct  Sampl eTabl eAtom  { 

1  ong 
1  ong 

Sampl eDescri pti onAtom 
T i meToSampl eNumAtom 
Sampl eToChunkAtom 
SyncSampl eAtom 
Sampl eSi zeAtom 
ChunkOf f setAtom 
ShadowSyncAtom 

1; 


size; 
atomType ; 

sampl eDescri pti on ; 
timeToSampl eNum; 
sampl eToChunk; 
syncSampl e ; 
sampl eSi ze ; 
chunkOf f set ; 
shadowSync ; 
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IV-2587 


Atoms 


'stbl' 


si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  Sampl eTabl eAID,  designating  atom  type  'stbl  ';  see  "Atom ID  Codes" 
(IV-2649). 

sampl eDescri pti on 

A  '  stsd '  (IV-2591)  atom,  which  contains  information  required  to  decode  the 
samples  in  the  media. 
timeToSampleNum 

A  '  stts '  (IV-2595)  atom  that  relates  sample  numbers  to  sample  durations, 
sampl eToChunk 

A  '  stsc '  (IV-2590)  atom  that  maps  sample  numbers  to  chunk  numbers. 
syncSampl e 

A  '  stss '  (IV-2593)  atom  that  identifies  the  key  frames  in  the  media, 
sampl eSi ze 

A  '  stsz '  (IV-2594)  atom,  which  identifies  the  size  of  each  sample  in  the  media. 
chunkOffset 

A  '  st co '  (IV-2589)  atom  that  identifies  the  location  of  each  data  chunk  in  the 
media. 

shadowSync 

A  '  stsh '  (IV-2592)  atom,  which  lists  self-contained  sync  samples  that  are 
alternates  for  existing  frame  difference  samples.  This  field  may  be  omitted. 

Discussion 

This  atom  contains  the  information  you  need  to  find  a  sample  number  based  on  a 
time  and  to  find  the  sample's  location  based  on  the  sample  number.  Samples  are 
organized  into  chunks,  containing  one  or  more  samples.  This  atom  contains  the 
information  you  need  to  find  out  which  chunk  holds  a  given  sample,  where  that 
chunk  begins,  and  where  in  that  chunk  you  can  find  the  sample. 

Programming  Info 

MoviesFormat.h 

See  Also 

For  the  atoms  that  may  contain  this  atom,  see  'mi  nf '  [generi  c]  (IV-2562), 

'  mi  nf '  [sound]  (IV-2564),  and  'minf'  [video]  (IV-2565).  For  general  information 
about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the 

bibliography). 


IV-2588 


Inside  QuickTime:  Atoms 


'stco' 


'stco' 


Identifies  the  location  of  each  chunk  of  data  in  the  media's  data  stream. 

struct  ChunkOf f setAtom  { 
long  size; 

long  atomType; 

long  flags; 

long  numEntries; 

long  chunkOffsetTabl e [ 1 ] ; 

}; 


ATM 


si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  STChunkOffsetAID,  designating  atom  type  '  stco see  "Atom  ID 
Codes"  (IV-2649). 
fl  ags 

One  byte  of  version  information  followed  by  three  bytes  of  flags.  The  flags 
bytes  are  not  currently  used. 

numEntri es 

The  number  of  entries  in  chunkOffsetTabl  e. 
chunkOffsetTabl e 

An  array  of  chunk  offset  values. 

Discussion 

A  chunk  is  a  collection  of  data  samples  in  a  media  that  allows  optimized  data  access. 
A  chunk  may  contain  one  or  more  samples.  Chunks  in  a  media  may  have  different 
sizes,  and  the  samples  within  a  chunk  may  have  different  sizes. 

Programming  Info 

Movi esFormat . h 


See  Also 

For  the  structure  that  contains  this  atom,  see  '  stbl '  (IV-2587).  For  general 
information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the 

bibliography). 


'strt' 


Defines  the  starting  offset  of  hypertext  in  a  text  stream. 


Inside  QuickTime:  Atoms 


IV-2589 


Atoms 


'strv' 


This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Value  is  '  strt  ’ . 

data 

The  starting  offset  of  hypertext. 

Parent  Atom 

' htxt '  (IV-2546) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  Tile  Format 

(listed  in  the  bibliography). 


'strv' 


Contains  a  string  variable  for  a  sprite. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Value  is  '  strv ' . 

Parent  Atom 

'vars'  (IV-2610) 

Contains  variables  for  a  sprite. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'stsc' 


Maps  sample  numbers  to  chunk  numbers. 

struct  Sampl eToChunkAtom  { 
long  size; 

long  atomType; 

long  flags; 


IV-2590 


Inside  QuickTime:  Atoms 


'stsd' 


long  numEntri es ; 

SampleToChunk  sampleToChunkTable[l]; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  STSampl  eToChunkAID,  designating  atom  type  '  stsc see  "Atom  ID 
Codes"  (IV-2649). 
fl  ags 

One  byte  of  version  information  followed  by  three  bytes  of  flags.  The  flags 
bytes  are  not  currently  used. 
numEntri es 

The  number  of  entries  in  sampl  eToChunkTabl  e. 
sampl eToChunkTabl e 

An  array  of  Sampl  eToChunk  (IV-2417)  data  structures,  which  contain  the  actual 
data  for  this  atom. 

Discussion 

A  chunk  is  a  collection  of  data  samples  in  a  media  that  allows  optimized  data  access. 
A  chunk  may  contain  one  or  more  samples.  Chunks  in  a  media  may  have  different 
sizes,  and  the  samples  within  a  chunk  may  have  different  sizes. 

Programming  Info 

Movi esFormat . h 

See  Also 

For  the  structure  that  contains  this  atom,  see  '  stbl '  (IV-2587).  For  general 
information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the 

bibliography). 


ATM 


'stsd' 


Holds  one  or  more  sample  description  structures. 

struct  Sampl eDescri pti onAtom  { 
long  size; 

long  atomType; 

long  flags; 

long  numEntries; 

Sampl eDescri pti on  sampl eDescTabl e [ 1 ] ; 


Inside  QuickTime:  Atoms 


IV-2591 


Atoms 


'stsh' 


si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  STSampl  eDescAI  D,  designating  atom  type  '  stsd see  "Atom  ID  Codes" 
(IV-2649). 

fl  ags 

One  byte  of  version  information  followed  by  three  bytes  of  flags.  The  flags 
bytes  are  not  currently  used. 
numEntri es 

Number  of  entries  in  sampl  eDescTabl  e. 
sampl eDescTabl e 

An  array  of  Sampl  eDescri  pti  on  (IV-2414)  data  structures,  which  contain  the 
actual  data  for  this  atom. 

Discussion 

In  QuickTime  streaming,  this  atom  describes  the  data  format  of  the  hint  samples 
and  contains  track-level  information,  such  as  the  RTP  timescale  for  a  track. 

Programming  Info 

MoviesFormat.h 

See  Also 

For  the  structure  that  contains  this  atom,  see  '  stbl '  (IV-2587).  For  general 
information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the 

bibliography). 


'stsh' 


Lists  self-contained  sync  samples  that  are  alternates  for  existing  frame  difference 
samples. 

struct  ShadowSyncAtom  { 


1  ong 

size; 

1  ong 

atomType ; 

1  ong 

fl ags  ; 

1  ong 

numEntri es ; 

ShadowSync 

shadowSyncTabl e [ 1 ] 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 


IV-2592 
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'stss' 


atomType 

Constant  STShadowSyncAID,  designating  atom  type  '  stsh see  "Atom  ID  Codes" 
(IV-2649). 

fl  ags 

One  byte  of  version  information  followed  by  three  bytes  of  flags.  The  flags 
bytes  are  not  currently  used. 

numEntri es 

The  number  of  entries  in  shadowSyncTabl  e. 
shadowSyncTabl e 

An  array  of  ShadowSync  (IV-2436)  data  structures,  which  contain  the  actual  data 
for  this  atom. 

Discussion 

Shadow  sync  atoms  are  used  to  optimize  random  access  operations  on  a  movie, 
thereby  enhancing  playback  performance. 

Programming  Info 

Movi esFormat . h 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


ATM 


'stss' 


Identifies  the  key  frames  in  a  media, 
struct  SyncSampl eAtom  { 


1  ong 

size; 

1  ong 

atomType ; 

1  ong 

fl ags  ; 

1  ong 

numEntri es ; 

1  ong 

syncSampl eTabl e [ 1  ] 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  STSyncSampl  eAID,  designating  atom  type  '  stss see  "Atom  ID  Codes" 
(IV-2649). 

fl  ags 

Flags  (currently  not  used). 


Inside  QuickTime:  Atoms 


IV-2593 


Atoms 


'stsz' 


numEntri es 

The  number  of  entries  in  syncSampl  eTabl  e. 
syncSampl eTabl e 

An  array  of  physical  sample  numbers,  each  of  which  identifies  a  key  frame  in 
the  media. 

Discussion 

In  a  media  that  contains  compressed  data,  key  frames  define  starting  points  for 
portions  of  a  temporally  compressed  sequence.  Each  key  frame  is  independent  of 
the  preceding  frames.  Subsequent  frames  may  depend  on  the  key  frame. 

Programming  Info 

MoviesFormat.h 

See  Also 

For  the  structure  that  contains  this  atom,  see  '  stbl '  (IV-2587).  For  general 
information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the 

bibliography). 


'stsz' 


Identifies  the  size  of  each  sample  in  a  media, 
struct  Sampl eSi zeAtom  { 


1  ong 

size; 

1  ong 

atomType ; 

1  ong 

fl ags  ; 

1  ong 

sampl eSi ze ; 

1  ong 

numEntri es ; 

1  ong 

sampl eSi zeTabl e  [  1  ] 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  STSampl  eSi  zeAI  D,  designating  atom  type  '  stsz see  "Atom  ID  Codes" 
(IV-2649). 

fl  ags 

One  byte  of  version  information  followed  by  three  bytes  of  flags.  The  flags 
bytes  are  not  currently  used. 


IV-2594 
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'stts' 


sampl eSi ze 

The  number  of  bytes  in  the  samples.  If  all  the  samples  are  the  same  size, 
sampl  eSize  indicates  the  size  of  all  the  samples.  If  sampl  eSi  ze  is  set  to  0,  then  the 
samples  have  different  sizes,  and  those  sizes  are  stored  in  samples izeTable. 
numEntri es 

The  number  of  entries  in  sampl  eSi  zeTabl  e. 
sampl eSi zeTabl e 

An  array  of  numbers,  one  for  every  sample.  This  field  is  indexed  by  sample 
number;  the  first  entry  corresponds  to  the  first  sample,  the  second  to  the  second 
sample,  and  so  on. 

Programming  Info 

MoviesFormat.h 

See  Also 

For  the  structure  that  contains  this  atom,  see  '  stbl '  (IV-2587).  For  general 
information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the 

bibliography). 


ATM 


'stts' 


Flolds  one  or  more  structures  that  relate  sample  numbers  to  sample  durations. 

struct  TimeToSampl eNumAtom  { 
long  size; 

long  atomType; 

long  flags; 

long  numEntries; 

T i meToSampl eNum  ti meToSampl eNumTabl e [ 1 ] ; 


si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  STTimeToSampAID,  designating  atom  type  '  stts see  "Atom  ID  Codes" 
(IV-2649). 

fl  ags 

One  byte  of  version  information  followed  by  three  bytes  of  flags.  The  flags 
bytes  are  not  currently  used. 
numEntri es 

The  number  of  entries  in  ti  meToSampl  eNumTabl  e. 


Inside  QuickTime:  Atoms 


IV-2595 


Atoms 


'sync' 


timeToSampl eNumTabl e 

An  array  of  T i  meToSampl  eNum  (IV-2486)  data  structures,  each  of  which  maps  a 
sample  number  to  its  sample  duration. 

Discussion 

Entries  in  timeToSampl  eNumTabl  e  collect  samples  according  to  their  order  in  the 
media  and  their  duration.  If  consecutive  samples  have  the  same  duration,  a  single 
table  entry  may  be  used  to  define  more  than  one  sample.  In  these  cases,  the  count 
field  indicates  the  number  of  consecutive  samples  that  have  the  same  duration.  For 
example,  if  a  video  media  had  a  constant  frame  rate,  ti  meT oSampl  eNumTabl  e  would 
have  one  entry. 

Programming  Info 

MoviesFormat.h 

See  Also 

For  the  structure  that  contains  this  atom,  see  '  stbl '  (IV-2587).  For  general 
information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the 

bibliography). 

'sync' 

Synchronization  track  reference  type  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Value  is  '  sync ' . 

data 

A  list  of  track  ID  values  (32-bit  integers)  specifying  the  related  tracks.  Note  that 
a  track  ID  value  can  be  set  to  0  to  indicate  an  unused  entry  in  the  atom.  Doing 
this  can  be  more  convenient  than  deleting  the  reference. 

Parent  Atom 

'tref'  (IV-2602) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


IV-2596 
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'tbox' 


'tbox' 


Defines  a  text  box  rectangle. 

struct  TextBoxAtom  { 
long  size; 

long  atomType; 

Rect  textBox; 

}; 


si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Value  is  'tbox'. 
textBox 

A  new  text  box  rectangle,  which  overrides  the  rectangle  defined  by  the 
defaul  tTextBox  constant. 


ATM 


Discussion 

This  is  a  classic  atom;  you  can  access  its  information  by  calculating  offsets. 

Programming  Info 

MoviesFormat.h 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'tcmi' 

Time  code  media  information  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Value  is  '  tcmi ' . 

data 

Time  code  media  information. 

Parent  Atom 

'mi nf ' [vi deo]  (IV-2565) 

Parent  atom  can  contain  only  one  atom  of  this  type. 


Inside  QuickTime:  Atoms 
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Atoms 


'tkhd' 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'tkhd' 


Specifies  the  characteristics  of  a  track  in  a  movie. 

struct  TrackHeaderAtom  { 
long  size; 

long  atomType; 

TrackHeader  header; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  TrackHeaderAID,  designating  atom  type  '  tkhd see  "Atom  ID  Codes" 
(IV-2649). 

header 

A  T rackHeader  (IV-2489)  structure  that  contains  the  actual  data  for  this  atom. 

Parent  Atom 

■trak'  (IV-2600) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Programming  Info 

MoviesFormat.h 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'tmax' 


Largest  relative  transmission  time,  in  milliseconds. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Value  is  '  tmax ' . 


IV-2598 
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'tmcd' 


Parent  Atom 


See  Also 


'tmcd' 


Parent  Atom 


See  Also 


'tmin' 


data 

4  bytes. 

'hint'  ( I V - 2  54 1  ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


Time  code  track  reference  type  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  Ti  meCodeMedi  aType,  designating  atom  type  '  tmcd see  "Atom  ID 
Codes"  (IV-2649). 

data 

A  list  of  track  ID  values  (32-bit  integers)  specifying  the  related  tracks.  Note  that 
a  track  ID  value  can  be  set  to  0  to  indicate  an  unused  entry  in  the  atom.  Doing 
this  can  be  more  convenient  than  deleting  the  reference. 

'tref'  ( I V - 2 60 2 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  the  TimeCodeDescri  pti  on  (IV-2483)  structure.  For  general  information  about 
atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the  bibliography). 


Smallest  relative  transmission  time,  in  milliseconds. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 


ATM 


Inside  QuickTime:  Atoms 


IV-2599 


Atoms 


'tpyl' 


atomType 

Value  is  '  tmi  n  ' . 

data 

4  bytes. 

Parent  Atom 

'hinf'  ( I V - 2541 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'tpyl' 

Total  number  of  bytes  that  will  be  sent,  not  including  12-byte  RTP  headers. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Value  is  '  tpyl  ’ . 

data 

8  bytes. 

Parent  Atom 

'hinf'  (IV-2541) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'trak' 


Defines  a  single  track  of  a  movie. 


struct  TrackDi rectory 
1  ong 
1  ong 

T  rackHeaderAtom 
Cl i ppi ngAtom 
Edi tsAtom 


{ 

size; 
atomType ; 
trackHeader ; 
trackCl i p ; 
edi ts ; 


IV-2600 


Inside  QuickTime:  Atoms 


'trak' 


Medi aDi rectory  media; 

UserDataAtom  userData; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  T  r  a  c  kA  I D,  designating  atom  type  'trak';  see  "Atom  ID  Codes" 
(IY-2649). 

trackHeader 

A  '  tkhd '  (IV-2598)  atom,  which  specifies  general  characteristics  of  the  track. 
trackCl  i p 

A  'clip'  (IV-2513)  atom,  which  defines  the  track's  clipping  region, 
edi  ts 

An  ’  edts  ’  (IV-2533)  atom,  which  defines  the  portions  of  the  track's  media  that 
are  going  into  the  track. 

medi  a 

A  '  mdi  a '  (IV-2560)  atom  structure  that  defines  the  media  for  the  track. 
userData 

A  '  udta  '  (IV-2607)  atom  that  contains  user  data. 

Parent  Atom 

'moov '  (IV-2566) 

Parent  atom  can  contain  any  number  of  atoms  of  this  type. 

Required  Child  Atoms 

'tkhd'  (IV-2598) 

Specifies  general  characteristics  of  the  track.  Only  one  allowed. 

'mdi a '  (IV-2560) 

The  media  for  the  track.  Only  one  allowed. 

Optional  Child  Atoms 

'clip'  (IV-2513) 

Defines  the  clipping  region  for  the  track.  Only  one  allowed. 

'matt'  (IV-2557) 

Defines  a  matte  for  a  track's  media.  Only  one  allowed. 

'edts'  (IV-2533) 

Defines  the  portions  of  the  track's  media  that  are  going  into  the  track.  Only  one 
allowed. 


ATM 
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IV-2601 


Atoms 


'tref' 


■tref'  (IV-2602) 

Track  reference  atom.  Only  one  allowed. 

'load'  ( I V - 2  5  5  6 ) 

Contains  preloading  information  for  a  track.  Only  one  allowed. 

'imap'  (IV-2548) 

An  input  map.  Only  one  allowed. 

'  udta '  (IV-2607) 

User  data  atom.  Only  one  allowed. 

Discussion 

A  movie  may  consist  of  one  or  more  tracks.  Each  track  is  independent  of  the  other 
tracks  in  the  movie  and  carries  its  own  temporal  and  spatial  information.  Each  track 
atom  contains  an  associated  media  atom.  Note  that  there  must  be  at  least  one  media 
track  within  a  QuickTime  movie.  All  media  tracks  that  are  present  must  remain  in 
the  movie,  even  if  the  media  data  within  them  is  not  referenced  by  the  hint  tracks. 
After  deleting  all  hint  tracks,  the  entire  unhinted  movie  must  remain. 

Programming  Info 

MoviesFormat.h 

See  Also 

See  the  T rackDi  rectoryEntry  (IV-2489)  structure.  For  general  information  about 
atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the  bibliography). 


'tref' 


Track  reference  atom. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameters: 

atomType 

Constant  TrackHeaderAID,  designating  atom  type  '  tref ';  see  "Atom  ID  Codes" 
(IV-2649). 

data 

One  track  reference  atom  of  a  type  listed  below. 

Parent  Atom 

'trak'  (IV-2600) 

Parent  atom  can  contain  only  one  atom  of  this  type. 


IV-2602 


Inside  QuickTime:  Atoms 


'trpy' 


Required  Child  Atoms  (one  from  this  list) 

' tmcd '  ( I V  -  2 5 9 9 ) 

Time  code  track  reference  type  atom.  Only  one  allowed. 

'chap'  ( IV-2512) 

Chapter  or  scene  list  track  reference  type  atom.  Only  one  allowed. 

'sync'  (IV-2596) 

Synchronization  track  reference  type  atom.  Only  one  allowed. 

'sept'  ( I V - 2  58 1  ) 

Transcript  track  reference  type  atom.  Only  one  allowed. 

'ssrc'  (IV-2586) 

Nonprimary  source  track  reference  type  atom.  Only  one  allowed. 

'hint'  ( I V - 2 54 2 ) 

Hint  track  reference  type  atom.  Only  one  allowed. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  Tile  Format 

(listed  in  the  bibliography). 


'trpy' 


Total  number  of  bytes  that  will  be  sent,  including  12-byte  RTP  headers,  but  not 
including  network  headers. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Value  is  '  trpy ' . 

data 

8  bytes. 

Parent  Atom 

'hint'  ( I V - 2 54 1 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


ATM 
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IV-2603 


Atoms 


'twdt' 


'twdt' 


Parent  Atom 


See  Also 


'twdu' 


Parent  Atom 


See  Also 


Tween  data  type  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Value  is  '  twdt ' . 

data 

Tween  data. 

■twen'  (IV-2605) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  Tile  Format 

(listed  in  the  bibliography). 


Tween  duration  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kTweenDurati  on,  designating  atom  type  '  twdu ';  see  "Atom  ID  Codes" 
(IV-2649). 

data 

Tween  duration  data. 

'twen'  (IV-2605) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


IV-2604 
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'twen' 


'twen' 

Tween  entry  atom. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Constant  kTweenEntry,  designating  atom  type  '  twen see  "Atom  ID  Codes" 
(IV-2649). 

Required  Child  Atoms 

' twst '  (IV-2606) 

Tween  start  atom.  Only  one  allowed. 

' twdu '  ( I V - 2604 ) 

Tween  duration  atom.  Only  one  allowed. 

' twdt '  (IV-2604) 

Tween  data  type  atom.  Only  one  allowed. 

' twnt '  ( I V - 2 60 5 ) 

Tween  type  atom.  Only  one  allowed. 

See  Also 

See  the  TweenSequenceEntryRecord  (IV-2494)  structure.  For  general  information 
about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the 

bibliography). 


ATM 


'twnt' 

Tween  type  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kTweenType,  designating  atom  type  '  twnt ';  see  "Atom  ID  Codes" 
(IV-2649). 

data 

Tween  type. 


Inside  QuickTime:  Atoms 


IV-2605 


Atoms 


'twst' 


Parent  Atom 

■twen'  (IV-2605) 

Parent  atom  can  contain  only  one  atom  of  this  type. 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'twst' 

Tween  start  offset  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kTweenStartOffset,  designating  atom  type  'twst';  see  "Atom  ID 
Codes"  (IV-2649). 

data 

Tween  start  offset. 

Parent  Atom 

'twen'  (IV-2605) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'  ty' 

Input  atom  type. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Value  is  '  ty ';  first  and  second  characters  are  spaces. 

data 

Track  input  atom  type  code. 


IV-2606 
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'udta' 


Parent  Atom 

'  in'  (IV-2554) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  Tile  Format 

(listed  in  the  bibliography). 


'udta' 

Holds  one  or  more  structures  of  movie  user  data. 

struct  UserDataAtom  { 

1  ong 
1  ong 

Movi esUserData 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  UserDataAID,  designating  atom  type  '  udta  see  "Atom  ID  Codes" 
(IV-2649). 

userData 

An  array  of  Movi  esUserData  (IV-2319)  data  structures,  which  contain  the  actual 
data  for  this  atom.  The  currently  defined  types  are  listed  below. 

Parent  atom  (one  or  the  other) 

'moov '  (IV-2566) 

Parent  atom  can  contain  any  number  of  atoms  of  this  type. 

'trak'  (IV-2600) 

Parent  atom  can  contain  any  number  of  atoms  of  this  type. 

Optional  child  atom 

'©cpy '  (IV-2515) 

Copyright  statement. 

'©day'  (IV-2516) 

Date  the  movie  content  was  created. 

'©dir'  (IV-2517) 

Name  of  movie's  director. 


size; 
atomType ; 
userData[l] ; 


ATM 
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Atoms 


'udta' 


'©edl '  ( I V - 2 5 1 7  ) 

First  edit  date  and  description.  Similar  for  '©ed2 '  through  '©ed9 ' . 

'©fmt '  (IV-2518) 

Indication  of  movie  format  (computer-generated,  digitized,  and  so  on). 

'©inf'  (IV-2519) 

Information  about  the  movie. 

'©prd '  (IV-2519) 

Name  of  movie's  producer. 

'©prf 1  ( I V - 2 5 2 0 ) 

Names  of  performers. 

'©req'  (IV-2521) 

Special  hardware  and  software  requirements. 

'©src '  (IV-2521) 

Credits  for  those  who  provided  movie  source  content. 

'©wrt '  (IV-2522) 

Name  of  movie's  writer. 

' WLOC '  (IV-2615) 

Default  window  location  for  movie.  Two  16-bit  values,  {xy}. 

' name ' [userdata]  (IV-2569) 

Name  of  object. 

'LOOP'  ( I V - 2  5  5  7 ) 

Looping.  Long  integer  indicating  looping  style.  0  for  none,  1  for  looping,  2  for 
palindromic  looping. 

'  Sel 0 '  (IV-2582) 

Play  selection  only.  Byte  indicating  that  only  the  selected  area  of  the  movie 
should  be  played. 

' All F '  (IV-2511) 

Play  all  frames.  Byte  indicating  that  all  frames  of  video  should  be  played, 
regardless  of  timing. 

Discussion 

Inside  the  user  data  atom  is  a  list  of  atoms  describing  each  piece  of  user  data.  Each 
data  element  contains  size  and  type  information  along  with  the  data.  Furthermore, 
for  historical  reasons,  the  list  of  atoms  is  optionally  terminated  by  a  32-bit  integer 
set  to  0.  If  you  are  writing  a  program  to  read  user  data  atoms,  you  should  allow  for 
the  terminating  0.  However,  if  you  are  writing  a  program  to  create  user  data  atoms, 
you  can  safely  leave  out  the  trailing  0. 


IV-2608 
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'url ' 


Programming  Info 

Movi esFormat . h 

See  Also 

See  the  Movi  esUserData  (IV-2319)  structure.  For  general  information  about  atoms, 
see  Inside  QuickTime:  QuickTime  File  Format  (listed  in  the  bibliography). 


'url' 


Contains  a  URL  for  a  sprite. 


ATM 


This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Value  is  '  url  ' . 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'uses' 


Lets  a  sprite  specify  the  subset  of  images  that  its  image  index  property  can  refer  to. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Value  is  '  uses  ' . 

Parent  Atom 

'  sprt '  ( I V - 2584 ) 

A  key  frame  sprite  definition. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 
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IV-2609 


Atoms 


'vars' 


'vars' 


Contains  variables  for  a  sprite. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Value  is  '  vars ' . 

Optional  Child  Atoms 

'flov'  ( I V  -  2  5  3  7  ) 

Contains  a  floating-point  variable  for  a  sprite.  Multiple  atoms  allowed. 

' strv '  (IV-2590) 

Contains  a  string  variable  for  a  sprite.  Multiple  atoms  allowed. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'vide' 


Contains  compression  information  for  the  Base  Image  Exporter. 

This  is  a  QT  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameter: 

atomType 

Constant  Vi  deoMedi  aType,  designating  atom  type  'vide';  see  "Component 
Identifiers"  (IV-2657). 

Optional  Child  Atoms 

'  dasz '  (IV-2527) 

Only  one  allowed.  If  present,  it  specifies  a  desired  data  size.  The  base  exporter 
repeats  compression  attempts,  decreasing  the  quality  parameter  until  it 
reaches  this  size  or  lower,  or  it  runs  out  of  patience. 

'reso'  (IV-2576) 

Only  one  allowed.  If  present,  it  specifies  the  resolution  for  the  p  i  xma  p  passed  to 
the  compressor. 


IV-2610 
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'vmhd'[media] 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


'vmhd' [media] 


Stores  handler-specific  information  for  video  media  in  a  track. 

struct  VideoMedi alnfo  { 

1  ong 
1  ong 

Vi deoMedi alnfoHeaderAtom 
Handl erAtom 
DatalnfoAtom 
Sampl  eTabl eAtom 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  Vi  deoMedi  a  Inf  oAID,  designating  atom  type  '  vmhd see  "Atom  ID 
Codes"  (IV-2649). 
header 

A  '  vmhd '  [transfer]  (IV-2612)  atom,  which  defines  the  graphics  transfer  mode 
for  this  video  media. 

dataHandl er 

A  '  hdl  r '  (IV-2540)  atom  that  specifies  the  component  that  is  to  handle  this 
media. 

datalnfo 

A  '  di  nf '  (IV-2530)  atom,  which  specifies  where  the  video  media  data  is  stored, 
sampl eTabl e 

A  '  stbl '  (IV-2587)  atom,  which  tells  the  media  handler  how  to  locate  and 
interpret  data  samples. 

Discussion 

This  atom  stores  handler-specific  information  for  the  media  that  constitutes  a  video 
track.  A  video  media  handler  uses  this  information  to  map  from  media  time  to 
media  data.  Another  type  of  media  handler  would  not  know  how  to  interpret  this 
information. 


size; 
atomType ; 
header ; 
dataHandl er ; 
datalnfo; 
sampl eTabl e ; 


ATM 


Inside  QuickTime:  Atoms 


IV-2611 


Atoms 


’vmhd'[transfer] 


Programming  Info 

MoviesFormat.h 

See  Also 

Seethe  'mint'  [sound]  (IV-2564)  atom  for  sound  media  and  the  'mi nf ' [generi  c] 
(IV-2562)  atom  for  media  other  than  video  or  sound.  Also  see  the 
VideoMedialnfoHeader  (IV-2503)  structure.  For  general  information  about  atoms,  see 
Inside  QuickTime:  QuickTime  File  Format  (listed  in  the  bibliography). 


'vmhd' [transfer] 


Defines  the  graphics  transfer  characteristics  for  a  video  media. 

struct  Vi deoMedi alnfoHeaderAtom  { 
long  size; 

long  atomType; 

VideoMedialnfoHeader  vmiHeader; 

}; 


si  ze 

The  size  in  bytes  of  this  atom  structure. 
atomType 

Constant  Vi  deoMedi  alnfoHeaderAID,  designating  atom  type  '  vmhd  see  "Atom 
ID  Codes"  (IV-2649). 

vmi Header 

A  VideoMedialnfoHeader  (IV-2503)  data  structure,  which  contains  the  actual 
data  for  this  atom. 


Programming  Info 

MoviesFormat.h 

See  Also 

For  the  structure  that  contains  this  atom,  see  '  m  i  n  f '  [  v  i  d  e  o  ]  (IV-2565) .  Also  see  the 
VideoMedialnfoHeader  (IV-2503)  structure.  For  general  information  about  atoms,  see 
Inside  QuickTime:  QuickTime  File  Format  (listed  in  the  bibliography). 

'vrcp' 


Custom  cursor  atom  parent. 


IV-2612 
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'vrni' 


This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Constant  kQTVRCursor  Pa  rent  AtomType,  designating  atom  type  '  vrcp see  "Atom 
ID  Codes"  (IV-2649). 

Required  Child  Atoms 

'CURS'  ( IV-2526) 

Custom  cursor  child  atom.  Multiple  atoms  of  this  type  allowed. 

'crsr'  ( IV-2524) 

Color  custom  cursor  child  atom.  Multiple  atoms  of  this  type  allowed. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'vrni' 


QTVR  node  ID  atom. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Constant  kQTVRNodelDAtomType,  designating  atom  type  'vrni ';  see  "Atom  ID 
Codes"  (IV-2649). 

Parent  Atom 

'  vrnp '  (IV-2614) 

Parent  atom  can  contain  any  number  of  atoms  of  this  type. 

Required  Child  Atoms 

'nioc'  (IV-2570) 

QTVR  node  location  atom.  Only  one  allowed. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 
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IV-2613 


'vrnp' 


'vrnp' 

QTVR  node  parent  atom. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Constant  kQTVRNode  Pa  rent  AtomType,  designating  atom  type  '  vrnp see  "Atom 
ID  Codes"  (IV-2649). 

Required  Child  Atoms 

' vrni '  (IV-2613) 

QTVR  node  ID  atom.  Any  number  allowed. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  Tile  Format 

(listed  in  the  bibliography). 

'vrsc' 


VR  world  header  atom. 

This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  kQTVRWorl  dHeaderAtomType,  designating  atom  type  '  vrsc ';  see  "Atom 
ID  Codes"  (IV-2649). 

data 

Contains  the  name  of  the  scene  and  the  default  node  ID. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'wide' 


Wide  atom  name  placeholder  atom. 


IV-2614 
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'WLOC 


This  is  a  QT  leaf  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it  with 
QTInsertChi  1  d  (11-1183)  using  the  following  parameters: 

atomType 

Constant  Wi  deAtomPl  acehol  derType,  designating  atom  type  'wide';  see  "Atom 
ID  Codes"  (IV-2649). 

data 

8  bytes  of  placeholder  space  to  allow  an  atom  to  be  converted  from  a  32-bit  to  a 
64-bit  atom. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 


ATM 


'WLOC' 


User  data  list  entry  atom:  default  window  location  for  movie. 

struct  Movi esUserData  { 
long  size; 

long  udType; 

char  data [  1  ] ; 

}; 

si  ze 

The  size  in  bytes  of  this  atom  structure. 
udType 

Value  is  'WLOC'. 


data 

2  16-bit  values,  {xy}. 

Parent  Atom 

' udta '  ( I V - 2 60 7 ) 

Parent  atom  can  contain  only  one  atom  of  this  type. 

Programming  Info 

Movi esFormat . h 


See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 
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'wtxt' 


'wtxt' 


Parent  atom  for  hypertext  items. 

This  is  a  QT  container  atom;  it  is  not  declared  in  the  header  files.  You  can  create  it 
with  QTNewAtomContai  ner  (11-1203)  and  insert  it  with  QTInsertChi  1  d  (11-1183),  using 
the  following  parameter: 

atomType 

Value  is  'wtxt'. 

Required  Child  Atoms 

' strt '  (IV-2589) 

Defines  the  starting  offset  of  hypertext  in  a  text  stream.  Only  one  allowed. 

'end  '  (IV-2534) 

Defines  the  ending  offset  of  hypertext  in  a  text  stream.  Only  one  allowed. 

Optional  Child  Atoms 

' htxt '  (IV-2546) 

Multiple  atoms  allowed. 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 

'vrsg' 


Contains  the  name  of  a  VR  scene. 

This  is  a  QT  leaf  atom  that  contains  a  struct  in  its  data  field.  Using  the  constant 
kQTVRStri  ngAtomType  and  a  pointer  to  the  atom,  you  can  access  its  data  with 
QTGetAtomDataPtr  (11-1171)  and  change  it  with  QTSetAtomData  (11-1223).  The  struct  is 
declared  as  follows: 

struct  QTVRStri ngAtom  { 

UIntl6  stringtlsage; 

UIntl6  stri ngLength ; 

unsigned  char  theStr1ng[4] ; 

}; 

stri  ngllsage 

Unused  field. 


IV-2616 
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'vrsg' 


stri ngLength 

The  length  of  the  name  string  in  bytes. 
theStri ng 

The  name  as  a  C  string. 

Discussion 

One  leaf  atom  of  this  type  is  contained  in  a  VR  world  container.  You  can  get  a 
pointer  to  this  container  by  calling  QTVRGetVRWorl  d  (11-1385).  One  of  this  atom's 
siblings  in  the  VR  world  is  a  '  v  rs  c '  (IV-2614)  atom,  which  contains  the  atom  ID  of 
this  atom  in  its  nameAtomID  field.  The  following  code  illustrates  a  function  that 
returns  the  name  of  a  VR  node  as  a  Pascal  string,  given  the  node's  ID: 


OSErr  MyGetNodeName  (QTVRInstance  thelnstance,  UInt32  theNodelD, 
StringPtr  theStringPtr) 


OSErr 

QTAtomContai ner 

QTVRNodeHeaderAtomPtr 

QTAtom 


theErr  =  noErr; 
theNodelnfo; 
theNodeHeader ; 
theNodeHeaderAtom  =  0; 


//  Get  the  node  information  atom  container 

theErr  =  QTVRGetNodeInfo(theInstance,  theNodelD,  &theNode!nfo) ; 


//  Get  the  node  header  atom, 
i f  ( ItheErr) 

theNodeHeaderAtom  =  QTFindChildByID(theNodeInfo, 

kParentAtomlsContai ner , 
kQTVRNodeHeaderAtomType ,  1,  nil); 

if  (theNodeHeaderAtom  !=  0)  { 

QTLockContainer(theNodelnfo); 


//  Get  a  pointer  to  the  node  header  atom  data. 

theErr  =  QTGetAtomDataPtr(theNodeInfo,  theNodeHeaderAtom,  nil, 

(Ptr  *)&theNodeHeader) ; 

//  See  if  there  is  a  name  atom. 

if  (ItheErr  &&  theNodeHeader->nameAtomID  !=  0)  { 

QTAtom  theNameAtom; 

theNameAtom  =  QTFi ndChi 1 dByID( theNodelnfo , 

kParentAtomlsContai ner ,  kQTVRStri ngAtomType , 
theNodeHeader->nameAtomID,  nil  ) ; 
if  (theNameAtom  !=  0)  { 

VRStri ngAtomPtr  theStri ngAtomPtr ; 


ATM 
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'vrsg' 


//  Get  a  pointer  to  the  name  atom  data;  copy  it  into  string 
theErr  =  QTGetAtomDataPtrttheNodelnfo,  theNameAtom,  nil, 

(Ptr  *)&theStringAtomPtr) ; 

if  (ItheErr)  { 

short  theLen  =  theStringAtomPtr->stri ngLength ; 
if  (theLen  >  255) 
theLen  =  255; 

B1 ockMovet  theStri ngAtomPtr->theStri ng , 

&theStri ngPtr[l] ,  theLen); 
theStri ngPtr[0]  =  theLen; 

} 

} 

} 

QTUnl ockContainer(theNodelnfo) ; 

} 

QTDi sposeAtomContai ner(theNodelnfo) ; 
return(theErr) ; 

} 

Programming  Info 

Qui ckT imeVRFormat . h 

See  Also 

For  general  information  about  atoms,  see  Inside  QuickTime:  QuickTime  Tile  Format 

(listed  in  the  bibliography). 
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Atom  Types 

Provide  access  to  data  stored  in  QuickTime  atoms. 

typedef  Handle  QTAtomContai ner ; 

typedef  long  QTAtom; 

typedef  long  QTAtomType; 

typedef  long  QTAtomID; 

typedef  long  DataRefAtom; 

Special  Considerations 

The  DataRefAtom  type  is  a  private  structure  and  is  not  documented. 

See  Also 

See  Discovering  QuickTime  (listed  in  the  bibliography).  Chapter  18. 
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Codec  Types 

Support  codec  components  and  the  Image  Compression  Manager. 

typedef  Component  CompressorComponent ; 

typedef  Component  DecompressorComponent ; 

typedef  Component  CodecComponent ; 

typedef  OSType  CodecType; 

typedef  unsigned  short  CodecFlags; 

typedef  unsigned  long  CodecQ; 

typedef  CDSequenceDataSourceQueueEntry  *  CDSequenceDataSourceQueueEntryPtr ; 
typedef  CDSequenceDataSource  *  CDSequenceDataSourcePtr ; 
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union  SourceData  { 

CDSequenceDataSourcePtr  image; 

EffectSourcePtr  effect; 

}; 

typedef  ICMFrameTimelnfo  *  ICMFrameTimelnfoPtr; 

typedef  ICMProgressProcRecord  *  ICMProgressProcRecordPtr ; 

typedef  ICMCompl eti onProcRecord  *  ICMCompl eti onProcRecordPtr ; 

typedef  ICMDataProcRecord  *  ICMDataProcRecordPtr ; 

typedef  ICMF1 ushProcRecord  *  ICMF1 ushProcRecordPtr ; 

typedef  ICMA1 i gnmentProcRecord  *  ICMA1 i gnmentProcRecordPtr ; 

typedef  DataRateParams  *  DataRateParamsPtr ; 

typedef  ImageDescri pti on  *  ImageDescri pti onPtr ; 

typedef  ImageDescri pti onPtr  *  ImageDescri pti onHandl e ; 

typedef  CodecNameSpecLi st  *  CodecNameSpecLi stPtr ; 

typedef  ICMFrameTimeRecord  *  ICMFrameTimePtr; 

typedef  Previ ewResourceRecord  *  Previ ewResourcePtr ; 

typedef  Previ ewResourcePtr  *  Previ ewResource ; 

typedef  ICMPi xel Formatlnfo  *  ICMPixel FormatlnfoPtr ; 

typedef  unsigned  short  MatrixFlags; 

typedef  void  *  ICMCursorNoti fy ; 

typedef  long  ImageSequence ; 

typedef  long  ImageSequenceDataSource ; 

typedef  long  ImageTranscodeSequence ; 

typedef  long  ImageFi el dSequence ; 

See  Also 

See  Discovering  QuickTime  (listed  in  the  bibliography).  Chapter  5. 
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Define  component  types  and  support  QuickTime  component  interfaces. 

typedef  ComponentResource  *  ComponentResourcePtr ; 

typedef  ComponentResourcePtr  *  ComponentResourceHandl e ; 

typedef  ExtComponentResource  *  ExtComponentResourcePtr ; 

typedef  ExtComponentResourcePtr  *  ExtComponentResourceHandl e ; 

typedef  ComponentRecord  *  Component; 

typedef  ComponentlnstanceRecord  *  Componentlnstance; 

typedef  Regi steredComponentRecord  *  Regi steredComponentRecordPtr ; 

typedef  Regi steredComponentRecord  *  Regi steredComponentPtr ; 

typedef  Regi steredComponentlnstanceRecord  * 

Regi steredComponentlnstanceRecordPtr ; 

typedef  Regi steredComponentlnstanceRecord  *  RegisteredComponentlnstancePtr; 

typedef  long  ComponentResul t ; 

typedef  Uni versal ProcPtr  ComponentFuncti onUPP ; 

typedef  const  Component  *  ConstComponentLi stPtr ; 

typedef  Componentlnstance  Graphi cs ImportComponent ; 

typedef  Componentlnstance  GraphicsExportComponent; 

typedef  Componentlnstance  ImageTranscoderComponent ; 

typedef  Componentlnstance  Movi elmportComponent ; 

typedef  Componentlnstance  Movi eExportComponent ; 

typedef  Componentlnstance  TextExportComponent ; 

typedef  Componentlnstance  Graphi clmageMovi elmportComponent ; 

typedef  Componentlnstance  pnotComponent ; 

typedef  Componentlnstance  DataCompressorComponent ; 
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typedef  Componentlnstance  DataDecompressorComponent ; 
typedef  Componentlnstance  DataCodecComponent ; 
typedef  Componentlnstance  SequenceFi 1 terComponent ; 
typedef  Componentlnstance  Medi aHandl er ; 
typedef  Component  Medi aHandl erComponent ; 
typedef  Componentlnstance  TweenerComponent ; 
typedef  QTTweenerRecord  *  QTTweener; 

See  Also 

See  Discovering  QuickTime  (listed  in  the  bibliography).  Chapter  9. 

Data  Handling  Types 

Support  data  handler  components, 
typedef  Componentlnstance  DataHandler; 
typedef  Component  DataHandl erComponent ; 
typedef  DataHVol umeLi stRecord  *  DataHVol umeLi stPtr ; 
typedef  DataHVol umeLi stPtr  *  DataHVol umeLi st ; 
typedef  DataHSchedul eRecord  *  DataHSchedul ePtr ; 
typedef  ComponentResul t  Handl erError ; 
typedef  OSType  *  DataHFi 1 eTypeOrderi ngPtr ; 

typedef  DataHFi 1 eTypeOrderi ngPtr  *  DataHFi 1 eTypeOrderi ngHandl e ; 

Effects  Types 

Support  visual  effects  and  the  standard  parameters  dialog  box. 

typedef  EffectSource  *  EffectSourcePtr ; 

typedef  EffectsFrameParams  *  EffectsFrameParamsPtr ; 
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typedef  long  QTParameterVal idati onOpti ons ; 

typedef  long  SMPTEFlags; 

typedef  long  SMPTEFrameReference ; 

typedef  unsigned  long  SMPTEWi peType ; 

typedef  Gradi entCol orRecord  *  Gradi entCol orPtr ; 

typedef  long  Gradi entType ; 

typedef  MatrixRecord  *  MatrixRecordPtr ; 

typedef  QTParamPreviewRecord  *  QTParamPreviewPtr; 

typedef  QTParamDi al ogEventRecord  *  QTParamDial ogEventPtr; 

typedef  QTParamFetchPreviewRecord  *  QTParamFetchPreviewPtr; 

typedef  long  QTParameterDi al og ; 

typedef  long  QTEf fectLi stOpti ons ; 

typedef  long  QTParameterDi al ogOptions ; 

See  Also 

See  Discovering  QuickTime  (listed  in  the  bibliography).  Chapter  14. 

Endian  Types 

Define  various  big-endian  and  little-endian  formats  for  conversion  functions. 

typedef  long  Bi gEndi anLong ; 

typedef  unsigned  long  BigEndi anUnsi gnedLong ; 

typedef  short  Bi gEndi anShort ; 

typedef  unsigned  short  Bi gEndi anUnsi gnedShort ; 

typedef  Fixed  Bi gEndi anFixed ; 

typedef  UnsignedFixed  Bi gEndi anUnsi gnedFixed ; 

typedef  OSType  Bi gEndi anOSType ; 
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File  System  Types 


Provide  access  to  Macintosh  file  system  specifications  and  file  aliases. 

typedef  FSSpec  *  FSSpecPtr; 

typedef  FSSpecPtr  *  FSSpecHandl e ; 

typedef  FSSpecPtr  FSSpecArrayPtr ; 

typedef  const  FSSpec  *  ConstFSSpecPtr ; 

typedef  AliasRecord  *  AliasPtr; 

typedef  AliasPtr  *  AliasHandle; 

typedef  short  A1 i asInfoType ; 

typedef  OSType  SFTypeList; 

typedef  CInfoPBRec  *  CInfoPBPtr;  //  in  Files. h 

See  Also 

See  Inside  Macintosh:  Files  (listed  in  the  bibliography). 

Graphics  Types 

Support  Windows  and  Macintosh  graphics  worlds. 

typedef  GDevice  *  GDPtr; 

typedef  GDPtr  *  GDHandle; 

typedef  GrafPort  *  GrafPtr; 

typedef  GrafPtr  WindowPtr; 

typedef  struct  GrafVars  GrafVars;  //  in  Quickdraw.h 
typedef  SInt8  GrafVerb;  //  in  Quickdraw.h 

typedef  WindowPtr  DialogPtr; 
typedef  WindowPtr  WindowRef; 
typedef  CGrafPort  *  CGrafPtr; 
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typedef  CGrafPtr  CWindowPtr; 
typedef  CGrafPtr  GWorldPtr; 
typedef  unsigned  long  GWorldFlags; 
typedef  BitMap  *  BitMapPtr; 
typedef  BitMapPtr  *  Bi tMapHandl e ; 
typedef  Picture  *  PicPtr; 
typedef  PicPtr  *  PicHandle; 
typedef  PixMapExtensi on  *  PixMapExtPtr ; 
typedef  PixMapExtPtr  *  PixMapExtHandl e ; 
typedef  PixMap  *  PixMapPtr; 
typedef  PixMapPtr  *  PixMapHandl e ; 
typedef  PixPat  *  PixPatPtr; 
typedef  PixPatPtr  *  PixPatHandl e ; 
typedef  short  CharParameter; 
typedef  unsigned  char  Style; 
typedef  short  Styl eParameter; 
typedef  Style  Styl  eFi  eld; 
typedef  RGBColor  *  RGBColorPtr; 
typedef  RGBColorPtr  *  RGBCol orHdl  ; 
typedef  VDGammaRecord  *  VDGamRecPtr; 
typedef  UIntl6  DragConstrai nt ; 
typedef  ColorTable  *  CTabPtr; 
typedef  CTabPtr  *  CTabHandle; 
typedef  MacPolygon  Polygon; 
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typedef  MacPolygon  *  PolyPtr; 
typedef  PolyPtr  *  PolyHandle; 
typedef  ColorSpec  *  Col orSpecPtr ; 
typedef  ColorSpec  CSpecArray; 
typedef  CProcRec  *  CProcPtr; 
typedef  CProcPtr  *  CProcHndl ; 
typedef  CQDProcs  *  CQDProcsPtr; 
typedef  QDProcs  *  QDProcsPtr; 
typedef  ITab  *  ITabPtr; 
typedef  ITabPtr  *  ITabHandle; 

See  Also 

See  Inside  Macintosh:  Imaging  With  QidckDrazv  (listed  in  the  bibliography). 

Media  Handling  Types 

Support  QuickTime  media  handlers. 

typedef  Handle  *  dataHandl ePtr ; 

typedef  dataHandl ePtr  *  dataHandl eHandl e ; 

typedef  Sampl eDescri pti on  *  Sampl eDescri pti onPtr ; 

typedef  Sampl eDescri pti onPtr  *  Sampl eDescri pti onHandl e ; 

typedef  Sampl eReferenceRecord  *  Sampl eReferencePtr ; 

typedef  Sampl eReference64Record  *  Sampl eReference64Ptr ; 

typedef  DataReferenceRecord  *  DataReferencePtr ; 

typedef  QTEventRecord  *  QTEventRecordPtr ; 

typedef  QTAtomSpec  *  QTAtomSpecPtr ; 

typedef  Resol vedQTEventSpec  *  Resol vedQTEventSpecPtr ; 
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typedef  unsigned  long  medi aHandl erFl agsEnum; 

typedef  QTCustomActi onTargetRecord  *  QTCustomActionTargetPtr; 

typedef  Medi aEQSpectrumBandsRecord  *  MediaEQSpectrumBandsRecordPtr; 

typedef  FI ashDescri pti on  *  FI ashDescri pti onPtr ; 

typedef  FI ashDescri pti onPtr  *  FI ashDescri pti onHandl e ; 

typedef  ThreeDeeDescri pti on  *  ThreeDeeDescri pti onPtr ; 

typedef  ThreeDeeDescri pti onPtr  *  ThreeDeeDescri pti onHandl e ; 

Memory  Types 

Provide  access  to  memory. 

typedef  char  *  Ptr; 

typedef  Ptr  *  Handle; 

typedef  long  Size; 

typedef  void  *  Logi cal  Address ; 

typedef  const  void  *  ConstLogi cal  Address ; 

typedef  void  *  Physi cal  Address ; 

typedef  UInt8  *  BytePtr; 

typedef  UInt32  ByteCount; 

typedef  UInt32  ByteOffset; 

typedef  Point  *  PointPtr; 

typedef  Rect  *  RectPtr; 

typedef  MacRegion  Region; 

typedef  MacRegion  *  RgnPtr; 

typedef  RgnPtr  *  RgnHandle; 

typedef  QElem  *  QElemPtr; 
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typedef  QHdr  *  QHdrPtr; 


Movie  Controller  Types 

Support  movie  controller  interfaces, 
typedef  Componentlnstance  Movi eControl 1 er ; 
typedef  Movi eControl 1 er  *  Movi eControl 1 erPtr ; 
typedef  unsigned  long  MCInterfaceEl ement ; 
typedef  short  mcAction; 
typedef  unsigned  long  mcFlags; 

typedef  QTStatusStri ngRecord  *  QTStatusStri ngPtr ; 
typedef  QTGetExternal Movi eRecord  *  QTGetExternal Movi ePtr ; 
typedef  QTGetChapterTimeRecord  *  QTGetChapterTimePtr; 
typedef  QTChapterlnfoRecord  *  QTChapterlnfoPtr ; 
typedef  QTEval uateExpressi onRecord  *  QTEval uateExpressi onPtr ; 
typedef  QTFetchParameterAsRecord  *  QTFetchParameterAsPtr ; 
typedef  QTGetCursorByIDRecord  *  QTGetCursorByIDPtr ; 
typedef  QTDoScri ptRecord  *  QTDoScri ptPtr ; 
typedef  QTRestartAtTimeRecord  *  QTRestartAtTimePtr; 

See  Also 

See  Discovering  QuickTime  (listed  in  the  bibliography).  Chapter  10. 

Movie  Types 

Support  movie  creation  and  editing, 
typedef  MovieRecord  *  Movie; 
typedef  Movie  *  MoviePtr; 
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typedef  TrackRecord  *  Track; 

typedef  MediaRecord  *  Media; 

typedef  UserDataRecord  *  UserData; 

typedef  TrackEdi tStateRecord  *  TrackEdi tState ; 

typedef  struct  TrackDi rectory  TrackDi rectory ;  //  see  'trak'  atom. 

typedef  Movi eEdi tStateRecord  *  Movi eEdi tState ; 

typedef  unsigned  long  createMovi eFi 1 eFl agsEnum; 

typedef  unsigned  long  movieFl attenFl agsEnum; 

typedef  unsigned  long  dataRefAttributesFl ags ; 

typedef  unsigned  long  pi ayHintsEnum; 

typedef  Connecti onSpeedPrefsRecord  *  ConnectionSpeedPrefsPtr; 

typedef  ConnectionSpeedPrefsPtr  *  Connecti onSpeedPref sHandl e ; 

typedef  BandwidthManagementPrefsRecord  *  BandwidthManagementPrefsPtr; 

typedef  BandwidthManagementPrefsPtr  *  Bandwi dthManagementPref sHandl e ; 

typedef  struct  OpaqueQTBandwi dthReference  *  QTBandwi dthReference ; 

typedef  struct  OpaqueQTSchedul edBandwi dthReference  * 

QTSchedul ed Bandwi dthReference ; 

typedef  QTSchedul edBandwi dthRecord  *  QTSchedul edBandwi dthPtr ; 
typedef  QTSchedul edBandwi dthPtr  *  QTSchedul edBandwi dthHandl e ; 

Special  Considerations 

The  OpaqueQTBandwi dthReference  and  OpaqueQTSchedul  edBandwi dthReference  data 
structures  are  not  part  of  the  public  QuickTime  API  and  are  not  documented. 

See  Also 

See  Discovering  QuickTime  (listed  in  the  bibliography).  Chapter  11. 
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Music  Types 

Support  the  QuickTime  Music  Architecture. 

typedef  Componentlnstance  Musi cComponent ; 

typedef  Componentlnstance  TunePlayer; 

typedef  SInt32  Musi cControl 1 er ; 

typedef  Musi cDescri pti on  *  Musi cDescri pti onPtr ; 

typedef  Musi cDescri pti onPtr  *  Musi cDescri pti onHandl e ; 

typedef  Componentlnstance  QTMIDIComponent ; 

typedef  QTMIDIPortLi st  *  QTMIDI PortLi stPtr ; 

typedef  QTMIDIPortLi stPtr  *  QTMIDI PortLi stHandl e ; 

typedef  GCInstrumentData  *  GCInstrumentDataPtr ; 

typedef  GCInstrumentDataPtr  *  GCInstrumentDataHandl e ; 

typedef  Generi cKnobDescri pti onLi st  *  Generi cKnobDescri pti onListPtr ; 

typedef  Generi cKnobDescri pti onLi stPtr  *  Generi cKnobDescri pti onLi stHandl e ; 

typedef  Handle  Atomi clnstrument ; 

typedef  Ptr  Atomi clnstrumentPtr ; 

typedef  InstrumentlnfoLi st  *  InstrumentlnfoLi stPtr ; 
typedef  InstrumentlnfoLi stPtr  *  InstrumentlnfoLi stHandl e ; 
typedef  InstrumentAboutlnfo  *  InstrumentAboutlnfoPtr ; 
typedef  InstrumentAboutlnfoPtr  *  InstrumentAboutlnfoHandl e ; 
typedef  GMInstrumentlnfo  *  GMInstrumentlnfoPtr ; 
typedef  GMInstrumentlnfoPtr  *  GMInstrumentlnfoHandl e ; 
typedef  nonGMInstrumentlnfo  *  nonGMInstrumentlnfoPtr ; 
typedef  nonGMInstrumentlnfoPtr  *  nonGMInstrumentlnfoHandl e ; 
typedef  InstCompInfo  *  InstCompInfoPtr ; 
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typedef  InstCompInfoPtr  *  InstCompInfoHandle; 
typedef  Componentlnstance  NoteAl 1 ocator ; 
typedef  struct  OpaqueNoteChannel  *  NoteChannel ; 
typedef  unsigned  long  MusicOpWord; 
typedef  MusicOpWord  *  Musi cOpWordPtr ; 

Special  Considerations 

The  OpaqueNoteChannel  data  structure  is  not  part  of  the  public  QuickTime  API  and 
is  not  documented. 

See  Also 

See  Discovering  QuickTime  (listed  in  the  bibliography).  Chapter  15. 
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Numeric  Types 

Define  numeric  values  in  QuickTime  programming. 

typedef  unsigned  char  UInt8; 

typedef  UInt8  Byte; 

typedef  signed  char  SInt8; 

typedef  SInt8  SignedByte; 

typedef  SInt8  VHSelect; 

typedef  unsigned  short  U I n 1 1 6 ; 

typedef  signed  short  SIntl6; 

typedef  unsigned  long  UInt32; 

typedef  signed  long  SInt32; 

typedef  short  ShortFixed; 

typedef  long  Fixed; 

typedef  Fixed  *  FixedPtr; 

typedef  unsigned  long  Unsi gnedFixed ; 
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typedef  Unsi gnedFixed  *  Unsi gnedFixedPtr ; 

typedef  long  Fract; 

typedef  Fract  *  FractPtr; 

typedef  wide  SInt64; 

typedef  wide  *  WidePtr; 

typedef  UnsignedWide  UInt64; 

typedef  UnsignedWide  *  Unsi gnedWi dePtr ; 

typedef  float  Float32; 

typedef  double  Float64; 

typedef  long  double  Float96; 

typedef  long  double  Float80; 

typedef  Float32  QTF1 oatSi ngl e ; 

typedef  Float64  QTF1 oatDoubl e ; 

typedef  Float80  extended80; 

typedef  Float96  extended96; 

Sequence  Grabbing  Types 

Support  sequence  grabbing  components,  including  channel  and  panel  components. 

typedef  Componentlnstance  SeqGrabComponent ; 

typedef  Componentlnstance  SGChannel ; 

typedef  unsigned  long  SeqGrabDataOutputEnum ; 

typedef  unsigned  long  SeqGrabUsageEnum ; 

typedef  unsigned  long  SeqGrabChannel InfoEnum ; 

typedef  SGOutputRecord  *  SGOutput; 
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typedef  SeqGrabFramelnfo  *  SeqGrabFramelnfoPtr; 
typedef  SeqGrabExtendedFramelnfo  *  SeqGrabExtendedFramelnfoPtr; 
typedef  SGDevi ceLi stRecord  *  SGDevi ceLi stPtr ; 
typedef  SGDevi ceLi stPtr  *  SGDevi ceLi st ; 

See  Also 

See  Discovering  QuickTime  (listed  in  the  bibliography).  Chapter  12. 


SMIL  Types 


Define  XML  types  for  QuickTime  SMIL  features. 

typedef  XMLDocRecord  *  XMLDoc; 

typedef  XMLAttribute  *  XMLAttri butePtr ; 

union  XMLAttri buteVal ue  { 

SInt32  number; 

Boolean  boolean; 

RGBColor  color; 

UInt32  enumType; 

}; 

typedef  XMLContent  *  XMLContentPtr ; 

typedef  XMLElement  *  XMLE1  ementPtr ; 

union  XMLE1 ementContent  { 

XMLElement  element; 

char  *charData; 

}; 
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Sound  Types 


Provide  support  for  the  Sound  Manager. 

typedef  SoundlnfoLi st  *  SoundlnfoListPtr; 

typedef  SoundComponentData  *  SoundComponentDataPtr; 

typedef  ExtendedSoundComponentData  *  ExtendedSoundComponentDataPtr; 
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typedef  SoundDescri pti on  *  SoundDescri pti onPtr ; 

typedef  SoundDescri pti onPtr  *  SoundDescri pti onHandl e ; 

typedef  SoundDescri pti onVl  *  SoundDescri pti onVIPtr ; 

typedef  SoundDescri pti onVIPtr  *  SoundDescri pti onVIHandl e ; 

typedef  SoundHeader  *  SoundHeaderPtr ; 

typedef  CmpSoundHeader  *  CmpSoundHeaderPtr ; 

typedef  ExtSoundHeader  *  ExtSoundHeaderPtr ; 

union  SoundHeaderUni on  { 

SoundHeader  stdHeader; 

CmpSoundHeader  cmpHeader; 

ExtSoundHeader  extHeader; 

}; 

typedef  ExtendedSoundParamBl ock  *  ExtendedSoundParamBl ockPtr ; 

typedef  StateBlock  *  StateBl ockPtr ; 

typedef  LeftOverBl ock  *  LeftOverBl ockPtr ; 

typedef  SndLi stResource  *  SndListPtr; 

typedef  SndListPtr  *  SndLi stHandl e ; 

typedef  SndLi stHandl e  SndListHndl; 

typedef  Snd2Li stResource  *  Snd2ListPtr; 

typedef  Snd2ListPtr  *  Snd2Li stHandl e ; 

typedef  Snd2Li stHandl e  Snd2Li stHndl  ; 

typedef  Conversi onBl ock  *  Conversi onBl ockPtr ; 

typedef  Schedul edSoundHeader  *  Schedul edSoundHeaderPtr ; 

typedef  ExtendedSchedul edSoundHeader  *  ExtendedSchedul edSoundHeaderPtr ; 

typedef  SMStatus  *  SMStatusPtr; 

typedef  SCStatus  *  SCStatusPtr; 

typedef  Audi oSel ecti on  *  Audi oSel ecti onPtr ; 


IV-2634 


Inside  QuickTime:  Defined  Data  Types 


typedef  Compressionlnfo  *  CompressionlnfoPtr; 

typedef  CompressionlnfoPtr  *  Compressi onlnfoHandl e; 

typedef  SoundSl opeAndlnterceptRecord  *  SoundSl  opeAndlnterceptPtr; 

typedef  SoundSource  *  SoundSourcePtr ; 

typedef  struct  OpaqueSoundSource  *  SoundSource; 

typedef  struct  OpaqueSoundConverter  *  SoundConverter ; 

typedef  SoundComponentLi nk  *  SoundComponentLi nkPtr ; 

typedef  Audioinfo  *  AudioInfoPtr; 

typedef  Audi oFormatAtom  *  Audi oFormatAtomPtr ; 

typedef  Audi oEndi anAtom  *  Audi oEndi anAtomPtr ; 

typedef  Audi oTermi natorAtom  *  Audi oTermi natorAtomPtr ; 

typedef  Level Meterlnfo  *  LevelMeterlnfoPtr; 

typedef  EQSpectrumBandsRecord  *  EQSpectrumBandsRecordPtr; 

typedef  SPB  *  SPBPtr; 

typedef  SndDoubl eBuf ferHeader  *  SndDoubl eBuf ferHeaderPtr ; 

typedef  SndDoubl eBuf ferHeader2  *  SndDoubl eBuf ferHeader2Ptr ; 

typedef  SndlnputCmpParam  *  SndlnputCmpParamPtr; 

typedef  SndChannel  *  SndChannel Ptr ; 

typedef  SndDoubl eBuf fer  *  SndDoubl eBuf ferPtr ; 

typedef  SoundParamBl ock  *  SoundParamBl ockPtr; 

typedef  const  short  *  Acti vati onOrderLi stPtr ; 

typedef  const  OSType  *  ConstSFTypeLi stPtr ; 

typedef  struct  SSpLocati onData  SSpLocati onData ;  //  see  SoundSprocket . h 

typedef  struct  SSpVi rtual SourceData  SSpVi rtual SourceData  ; 

//  see  SoundSprocket . h 
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Special  Considerations 

The  OpaqueSoundSource  and  OpaqueSoundConverter  data  structures  are  not  part  of  the 
public  QuickTime  API  and  are  not  documented. 

See  Also 

See  Discovering  QuickTime  (listed  in  the  bibliography).  Chapter  13. 

Sprite  Management  Types 

Support  QuickTime  sprite  programming, 
typedef  Spri teWorl dRecord  *  SpriteWorld; 
typedef  SpriteRecord  *  Sprite; 

typedef  Spri teDescri pti on  *  Spri teDescri pti onPtr ; 
typedef  Spri teDescri pti onPtr  *  Spri teDescri pti onHandl e ; 
typedef  QTRunti meSpri teDescStruct  *  QTRunti meSpri teDescPtr ; 
typedef  QTSpri teButtonBehavi orStruct  *  QTSpri teButtonBehavi orPtr ; 

See  Also 

See  Discovering  QuickTime  (listed  in  the  bibliography).  Chapter  16. 

Streaming  Types 

Support  QuickTime  streaming. 

typedef  QTSSampl eDescri pti on  *  QTSSampl eDescri pti onPtr ; 
typedef  QTSSampl eDescri pti onPtr  *  QTSSampl eDescri pti onHandl e ; 
typedef  UInt32  RTPMPSampl eRef ; 
typedef  UInt32  RTPSSRC; 

typedef  RTPPayl oadSortRequest  *  RTPPayl oadSortRequestPtr ; 
typedef  RTPPayl oadlnfo  *  RTPPayl oadlnfoPtr ; 
typedef  RTPPayl oadlnfoPtr  *  RTPPayl oadlnfoHandl e ; 
typedef  Componentlnstance  RTPReassembl er ; 
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typedef  RTPReassembl erlnfo  *  RTPReassemblerlnfoPtr; 
typedef  RTPReassemblerlnfoPtr  *  RTPReassembl erlnfoHandl e; 
typedef  Componentlnstance  RTPMediaPacketizer; 
typedef  struct  OpaqueRTPPacketGroupRef  *  RTPPacketGroupRef ; 
typedef  struct  OpaqueRTPPacketRef  *  RTPPacketRef ; 

typedef  struct  OpaqueRTPPacketRepeatedDataRef  *  RTPPacketRepeatedDataRef ; 

typedef  Medi aPacketizerRequi rements  *  Medi aPacketi zerRequi rementsPtr ; 

typedef  Medi aPacketizerlnfo  *  Medi aPacketi zerlnfoPtr ; 

typedef  Medi aPacketi zerlnfoPtr  *  Medi aPacketi zer Inf oHandl e ; 

typedef  Componentlnstance  RTPPacketBui 1 der ; 

typedef  QTSPresentati onRecord  *  QTSPresentati on ; 

typedef  QTSStreamRecord  *  QTSStream; 

typedef  QTSEditList  *  QTSEdi t Li stPtr ; 

typedef  QTSEdi t Li stPtr  *  QTSEdi t Li stHandl e ; 

typedef  struct  OpaqueQTSMemPtr  *  QTSMemPtr; 

typedef  QTSStatHel perRecord  *  QTSStatHel per ; 

typedef  UInt32  QTSStatus; 

Special  Considerations 

The  OpaqueRTPPacketGroupRef,  OpaqueRTPPacketRef,  OpaqueQTSMemPtr,  and 
OpaqueRTPPacketRepeatedDataRef  data  structures  are  not  part  of  the  public 
QuickTime  API  and  are  not  documented. 

String  Types 

Represent  string  values  in  QuickTime, 
typedef  char  *  CharsPtr; 
typedef  CharsPtr  *  CharsHandle; 
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typedef  unsigned  char  *  StringPtr; 

typedef  StringPtr  *  Stri ngHandl e ; 

typedef  char  Chars; 

typedef  unsigned  char  St r 255 ; 

typedef  unsigned  char  St r 63 ; 

typedef  unsigned  char  St r 32 ; 

typedef  unsigned  char  Str31; 

typedef  unsigned  char  St r 27 ; 

typedef  unsigned  char  S t r 1 5 ; 

typedef  unsigned  char  Str32Field; 

typedef  const  unsigned  char  *  ConstStri ngPtr ; 

typedef  const  unsigned  char  *  ConstStr255Param; 

typedef  const  unsigned  char  *  ConstStr63Param; 

typedef  const  unsigned  char  *  ConstStr32Param; 

typedef  const  unsigned  char  *  ConstStr31Param; 

typedef  const  unsigned  char  *  ConstStr27Param; 

typedef  const  unsigned  char  *  ConstStrl5Param; 

typedef  UIntl6  UniChar; 

typedef  UInt32  UniCharCount ; 

typedef  Str255  StrFi 1 eName ; 

typedef  ConstStr255Param  ConstStrFi 1 eNameParam ; 

System  and  Toolbox  Types 

Define  basic  data  formats  for  the  QuickTime  system  software. 
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typedef  SIntl6  OSErr; 
typedef  SInt32  OSStatus; 
typedef  unsigned  long  FourCharCode; 
typedef  FourCharCode  OSType; 
typedef  FourCharCode  ResType; 
typedef  OSType  *  OSTypePtr; 
typedef  ResType  *  ResTypePtr; 
typedef  UInt32  OptionBits; 
typedef  UInt32  ItemCount; 
typedef  UInt32  PBVersion; 
typedef  Menulnfo  *  MenuPtr; 
typedef  MenuPtr  *  MenuHandle; 
typedef  UIntl6  EventKind; 
typedef  UIntl6  EventMask; 
typedef  UIntl6  EventModi f i ers  ; 
typedef  DialogPtr  DialogRef; 
typedef  unsigned  long  ProcInfoType; 
typedef  SProcRec  *  SProcPtr; 
typedef  SProcPtr  *  SProcHndl  ; 

typedef  UInt8  RDFlagsType;  //  in  MixedMode.h 

typedef  SInt8  ISAType;  //  in  MixedMode.h 

typedef  unsigned  short  Routi neFl agsType ;  //  in  MixedMode.h 

typedef  ComponentMPWorkFuncti onHeaderRecord  * 

ComponentMPWorkFuncti onHeaderRecordPtr; 

typedef  SIntl6  Di al ogltemlndex;  //  in  Dialogs. h 
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Text  Types 


Support  QuickTime  text  components. 

typedef  TextDescripti on  *  TextDescriptionPtr ; 

typedef  TextDescriptionPtr  *  TextDescripti onHandl e ; 

typedef  TERec  *  TEPtr; 

typedef  TEPtr  *  TEHandle; 

typedef  TCTextOpti ons  *  TCTextOpti onsPtr ; 

typedef  SIntl6  ScriptCode; 

typedef  SIntl6  LangCode; 

typedef  SIntl6  RegionCode; 

typedef  struct  STElement  STElement;  //  see  TextEdit. h 
typedef  STElement  *  STPtr;  //  in  TextEdit. h 

typedef  STPtr  *  STHandle;  //  in  TextEdit. h 

typedef  struct  LHElement  LHElement;  //  see  TextEdit. h 
typedef  LHElement  *  LHPtr;  //  in  TextEdit. h 

typedef  LHPtr  *  LHHandle;  //  in  TextEdit. h 

typedef  struct  NullStRec  NullStRec;  //  see  TextEdit. h 
typedef  NullStRec  *  Null  St Pt  r :  //  in  TextEdit. h 

typedef  NullStPtr  *  Nul 1 StHandl e ;  //  in  TextEdit. h 

typedef  struct  StyleRun  StyleRun;  //  see  TextEdit. h 

See  Also 

See  Discovering  QuickTime  (listed  in  the  bibliography).  Chapter  6. 

Timing  and  Callback  Types 

Support  QuickTime's  timing  and  callback  capabilities. 
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typedef  long  TimeValue; 

typedef  long  TimeScale; 

typedef  SInt64  TimeValue64; 

typedef  UnsignedWide  Absol uteTime ; 

typedef  wide  CompTimeVal  lie; 

typedef  SInt32  Duration; 

typedef  TimeBaseRecord  *  TimeBase; 

typedef  unsigned  long  TimeBaseFl ags ; 

typedef  unsigned  short  nextTimeFl agsEnum; 

typedef  unsigned  long  TimeBaseStatus ; 

typedef  TimeCodeDescription  *  TimeCodeDescri pti onPtr ; 

typedef  TimeCodeDescriptionPtr  *  TimeCodeDescriptionFlandle; 

typedef  unsigned  short  QTCal 1 BackType ; 

typedef  Cal  1 BackRecord  *  QTCallBack; 

typedef  unsigned  short  QTCal 1 BackFl ags ; 

typedef  QTSyncTaskRecord  *  QTSyncTaskPtr; 

Universal  Procedure  Pointers 

Support  the  Macintosh  Mixed  Mode  Manager, 
typedef  ProcPtr  Uni versal ProcPtr ; 
typedef  ProcPtr  *  ProcHandle; 

typedef  struct  Routi neDescri ptor  *  Uni versal ProcPtr ; 
typedef  Uni versal ProcPtr  *  Uni versal ProcHandl e ; 
typedef  STACK_UPP_TYPE(DoMCActionProcPtr)  DoMCActi onUPP ; 
typedef  STACK_UPP_TYPE(Movi eExecuteWi redActi  onsProcPtr) 
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Movi eExecuteWi redActi onsUPP ; 


typedef  STACK__UPP_TYPE(  Movi  ePrePreroll  Compl  eteProcPtr) 

MoviePrePreroll Compl eteUPP ; 

typedef  STACK _UPP_TYPE(  Sequence Fi  IterDataProcPtr)  SequenceFilterDatallPP; 

typedef  STACK_UPP_TYPE(SFModal FilterProcPtr)  SFModal Fi 1 terUPP ; 

typedef  STACK_UPP_TYPE(SGDataProcPtr)  SGDataUPP; 

typedef  STACK _U PP_TYP E ( QTVRI intercept ProcPtr)  QTVRInterceptUPP  ; 

typedef  STACK _U PP_TYP E ( SoundConverterFi 1 1 BufferData ProcPtr ) 
SoundConverterFill BufferDataUPP ; 

typedef  STACK_UPP_TYPE(DlgHookProcPtr)  DlgHookUPP; 

typedef  STACK _UPP_TYPE(  Fi  1  eFi  1  terProcPtr )  Fi  1  eFi  1  terUPP  ; 

typedef  STACK_UPP_TYPE(DlgHookYDProcPtr)  D1 gHookYDUPP ; 

typedef  STACK_.UPP_TYPE(Modal  Fi  1  terYDProcPtr )  Modal  FilterYDUPP; 

typedef  STACK„.UPP_TYPE(  Fi  1  eFi  1  terYDProcPtr )  Fi  1  eFi  1  terYDUPP  ; 

typedef  STACK_UPP_TYPE(ActivateYDProcPtr)  Acti vateYDUPP ; 

typedef  STACK_.UPP_TYPE( Modal  Fi  1  terProcPtr )  Modal  Fi  1  terUPP  ; 

typedef  STACK _UPP_TYPE(  ImageCodecMPDrawBandProcPtr)  ImageCodecMPDrawBandUPP ; 

typedef  STACK_.UPP_TYPE(ICMDataProcPtr)  ICMDataUPP; 

typedef  STACK _UPP_TYPE( ICMF1 ushProcPtr )  ICMF1 ushUPP ; 

typedef  STACK_UPP_TYPE( ICMCompl etionProcPtr)  ICMCompl eti onUPP ; 

typedef  STACK„.UPP_TYPE(ICMProgressProcPtr)  ICMProgressUPP ; 

typedef  STACK_UPP_TYPE(StdPixProcPtr)  StdPixUPP; 

typedef  STACK„UPP_TYPE(QDPixProcPtr)  QDPixUPP; 

typedef  STACK_UPP_TYPE( ICMA1 i gnmentProcPtr )  ICMA1 i gnmentUPP ; 

typedef  STACK_UPP_TYPE( ICMCursorShieldedProcPtr)  ICMCursorShieldedUPP; 

typedef  STACK . UPP_TYPE( ICMMemoryDi sposedProcPtr)  ICMMemoryDi sposedUPP; 
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typedef  STACK_UPP_TYPE( ICMConvertDataFormatProcPtr )  ICMConvertDataFormatUPP ; 

typedef  STACK_UPP_TYPE(  PrePrerol  1  Compl  eteProcPtr)  PrePrerol 1  Comp!  etellPP ; 

typedef  STACK_UPP_TYPE(Movi eRgnCoverProcPtr)  MovieRgnCoverUPP; 

typedef  STAC K_UPP_TYPE( Movi eProgressProcPtr)  MovieProgressUPP; 

typedef  STACK_UPP_TYPE(Movi  eDrawi  ngCompl  eteProcPtr)  Movi  eDrawi  ngCompl  etellPP ; 

typedef  STACK_UPP_TYPE(TrackTransferProcPtr)  TrackTransferUPP ; 

typedef  STACK_UPP_TYPE(GetMovieProcPtr)  GetMovieUPP; 

typedef  STAC K_UPP_TYPE( Movi ePrevi ewCal lOutProcPtr)  MoviePrevi ewCal 1 OutUPP ; 

typedef  STACK_UPP_TYPE(TextMedi aProcPtr)  TextMedi aUPP ; 

typedef  STACK_UPP_TYPE( Acti  onsProcPtr)  ActionslIPP; 

typedef  STAC K_UPP_TYPE(MC Acti  onFi  1  terProcPtr )  MCActi  onFi  1  terllPP ; 

typedef  STACK_UPP_TYPE( MCActi onFi 1 terWi thRefConProcPtr) 

MCActi  onFi  1  terWi  th Ref ConllPP ; 

typedef  STACK_UPP_TYPE(QTCal 1 BackProcPtr)  QTCal 1 BackUPP ; 

typedef  STACK_UPP_TYPE(QTSyncTaskProcPtr)  QTSyncTaskUPP; 

typedef  STACK_UPP_JYPE(TweenerDataProcPtr)  TweenerDatallPP ; 

typedef  STACK_UPP_TYPE(  DataHCompi  eti  onProcPtr)  DataHCompl  eti  onllPP ; 

typedef  STAC K_UPP_TYPE( Movi  eExportGetDataProcPtr )  Movi  eExportGetDatallPP ; 

typedef  STACK_UPP_TYPE(Movi eExportGetPropertyProcPtr) 

Movi eExportGet Property U PP ; 

typedef  STACK_UPP_TYPE( SCModal Fi 1 terProcPtr)  SCModal  FilterUPP; 

typedef  STACK_UPP_TYPE( SCModal HookProcPtr)  SCModal HookUPP ; 

typedef  STACK_UPP_TYPE( SGGrabBottl eProcPtr )  SGGrabBottl eUPP ; 

typedef  STACK_UPP_TYPE( SGGrabCompl eteBottl eProcPtr)  SGGrabCompl eteBottl eUPP ; 

typedef  STACK_UPP_TYPE( SGDi spl ayBottl eProcPtr)  SGDi spl ayBottl eUPP ; 


TYP 
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typedef  STACK... UPP_TYPE( SGCompressBottl eProcPtr)  SGCompressBottl eUPP ; 

typedef  STAC K_UPP_TYPE(SGCompress Comp 1 eteBottl eProcPtr) 

SGComp res s Comp 1 eteBottl eUPP; 

typedef  STACK ..UPP_TYPE(SGAddFrameBottl  eProcPtr)  SGAddFrameBottl  eUPP  ; 

typedef  STACK_.UPP_TYPE(SGT  ransferFrameBottl  eProcPtr) 
SGTransferFrameBottleUPP; 

typedef  STACK_UPP_TYPE(SGGrabCompressCompl eteBottl eProcPtr) 
SGGrabCompressCompl eteBottl eUPP; 

typedef  STACK _U PP_TYP E ( SGD1 spl ayCompressBottl eProcPtr) 

SGD1 spl ayCompressBottl eUPP ; 

typedef  STACK_UPP_TYPE(SGModal Fi 1 terProcPtr )  SGModal Fi 1 terUPP ; 

typedef  STACK_UPP_TYPE(VdigIntProcPtr)  VdiglntUPP; 

typedef  STACK_UPP_TYPE(MusicMIDISendProcPtr)  Musi cMIDISendUPP ; 

typedef  STACK_UPP_TYPE(MusicMIDIReadHookProcPtr)  MusicMIDIReadHookUPP; 

typedef  STACK.. UPP_TYPE( Musi cOfflineDataProcPtr)  Musi cOff 1 i neDataUPP ; 

typedef  STACK_UPP_TYPE(TuneCall BackProcPtr)  TuneCall BackUPP ; 

typedef  STACK_.UPP_TYPE(TunePl  ayCallBackProcPtr)  TunePlayCallBackUPP; 

typedef  STACK_UPP_TYPE( QTVRLeavi ngNodeProcPtr)  QTVRLeavi ngNodeUPP ; 

typedef  STACK_.UPP_TYPE(  QTVREnteri ngNodeProcPtr)  QTVREnteri ngNodeUPP; 

typedef  STACK_UPP_TYPE( QTVRMouseOverHotSpotProcPtr )  QTVRMouseOverHotSpotUPP 

typedef  STACK_UPP_TYPE(QTVRImagi ngCompl eteProcPtr)  QTVRImagi ngCompl eteUPP ; 

typedef  STAC K„UPP_TYPE( QTVRBackBufferlmagi ngProcPtr) 

QTVRBackBufferlmagi ngUPP ; 

typedef  STACK_UPP_TYPE( Fi 1 ePl ay Comp 1 etionProcPtr)  FilePl ay Comp 1 eti onUPP ; 
typedef  STACK._.UPP_TYPE(SICompletionProcPtr)  SICompI  eti  onUPP  ; 
typedef  STACK_UPP_TYPE(SndCall BackProcPtr)  SndCall BackUPP ; 
typedef  STACK„UPP_TYPE(SndDoubl eBackProcPtr)  SndDoubleBackUPP; 
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typedef  STACK_UPP_TYPE(SoundParamProcPtr)  SoundParamUPP; 

typedef  STACK_UPP_TYPE(ComponentMPWorkFuncti onProcPtr) 
ComponentMPWorkFuncti onUPP ; 

typedef  STACK_UPP_TYPE(ComponentRouti neProcPtr)  Component Routi nellPP ; 

typedef  STACK_UPP_TYPE(GetMi ssi ngComponentResourceProcPtr) 

GetMi  ssi  n  gC  ompon  ent  Res  our  cell  PP ; 

typedef  STACK_UPP_TYPE( RTPMPDataReleaseProcPtr)  RTPMPDataReleaseUPP; 

typedef  STACK_UPP_TYPE( RTPPBCal 1 backProcPtr)  RTPPBCal 1 backUPP ; 

typedef  STACK_UPP_TYPE(MoviesErrorProcPtr)  MoviesErrorUPP; 

typedef  STACK_UPP_TYPE(QTSNoti fi cati onProcPtr)  QTSNoti fi cati onUPP; 

typedef  STACK_UPP_TYPE( ImageCodecTimeTri ggerProcPtr) 

ImageCodecTi meT  riggerUPP; 

typedef  STACK_UPP_TYPE(QTBandwi dthNoti fi cati onProcPtr) 

QTBandwi dthNoti fi cati onUPP ; 

typedef  STACK_UPP_TYPE(QDTextProcPtr)  QDTextUPP; 
typedef  STACK_UPP_TYPE(QDLi neProcPtr)  QDLineUPP; 
typedef  STACK_UPP_TYPE(QDRectProcPtr)  QDRectUPP ; 
typedef  STACK_UPP_TYPE(QDRRectProcPtr )  QDRRectUPP ; 
typedef  STACK_UPP_TYPE(QDOval ProcPtr)  QDOvalUPP; 
typedef  STACK_UPP_TYPE(QDArcProcPtr)  QDArcUPP; 
typedef  STACK_UPP_TYPE(QDPolyProcPtr)  QDPolyUPP; 
typedef  STACK_UPP_TYPE(QDRgnProcPtr )  QDRgnUPP ; 
typedef  STACK_UPP_TYPE(QDBitsProcPtr)  QDBitsUPP; 
typedef  STACK_UPP_TYPE(QDCommentProcPtr)  QDCommentUPP ; 
typedef  STACK_UPP_TYPE(QDTxMeasProcPtr)  QDTxMeasUPP ; 
typedef  STACK_UPP_TYPE(QDGetPi cProcPtr )  QDGetPicUPP; 
typedef  STACK_UPP_TYPE(QDPutPi cProcPtr)  QDPutPicUPP; 
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typedef  STACK_UPP_TYPE(QDOpcodeProcPtr)  QDOpcodeUPP; 
typedef  STACK_UPP_TYPE(QDStdGlyphsProcPtr)  QDStdGlyphsUPP ; 
typedef  STACK_UPP_TYPE(QDJShi eldCursorProcPtr)  QDJShieldCursorllPP; 
typedef  STACK_UPP_TYPE(DragGrayRgnProcPtr)  DragGrayRgnUPP ; 
typedef  STACK_UPP_TYPE(ColorSearchProcPtr)  Col orSearchUPP ; 
typedef  STACK_UPP_TYPE( Col orCompl ementProcPtr )  Col  or Comp 1 ementUPP ; 
typedef  STACK_UPP_TYPE( QDPri nterStatusProcPtr)  QDPrinterStatusUPP; 
typedef  REGISTER_UPP_TYPE( Hi ghHookProcPtr)  HighHookUPP; 
typedef  REGISTER„UPP_TYPE( CaretHookProcPtr )  CaretHookUPP ; 
typedef  REGISTER„UPP_TYPE(TEC1 i ckLoopProcPtr )  TEC1 i ckLoopUPP ; 
typedef  REGISTER_UPP_TYPE( WordBreakProcPtr )  WordBreakUPP ; 
typedef  REGISTER„UPP_TYPE(SIInterruptProcPtr)  SI InterruptUPP ; 

See  Also 

See  Inside  Macintosh:  PowerPC  System  Softivare  (listed  in  the  bibliography). 

Video  Types 

Support  QuickTime  video  components, 
typedef  Componentlnstance  Vi deoDi gi ti zerComponent ; 
typedef  Componentlnstance  QTVi deoOutputComponent ; 
typedef  ComponentResul t  Vi deoDi gi ti zerError ; 
typedef  VDCompressionLi st  *  VDCompressionLi stPtr ; 
typedef  VDCompressionLi stPtr  *  VDCompressi onLi stHandl e ; 
typedef  Vdi gBufferRecLi st  *  Vdi gBufferRecLi stPtr ; 
typedef  Vdi gBufferRecLi stPtr  *  Vdi gBufferRecLi stHandl e ; 
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Virtual  Reality  Types 


Support  the  programming  interface  for  QuickTime  Virtual  Reality. 

typedef  struct  OpaqueQTVRInstance  *  QTVRInstance; 

typedef  UInt32  QTVRProcSel ector ; 

typedef  QTVRInterceptRecord  *  QTVRInterceptPtr; 

typedef  UInt32  QTVRImagi ngMode ; 

typedef  UInt32  QTVRAngul arUni ts  ; 

typedef  UInt32  QTVRObjectAnimati onSetti ng ; 

typedef  UInt32  QTVRControl Setti ng ; 

typedef  UInt32  QTVRViewStateType; 

typedef  UInt32  QTVRNudgeControl  ; 

typedef  UInt32  QTVRNudgeMode ; 

typedef  QTVRCursorRecord  CursorRecord ; 

typedef  QTVRAreaOf Interest  AreaOf Interest; 

typedef  QTVRF1  oatPoi  nt  FloatPoint; 

typedef  QTVRLeavi ngNodeProcPtr  Leavi ngNodeProcPtr ; 

typedef  QTVRLeavi ngNodeUPP  Leavi ngNodeUPP ; 

typedef  QTVREnteri ngNodeProcPtr  Enteri ngNodeProcPtr ; 

typedef  QTVREnteri ngNodeUPP  Enteri ngNodeUPP ; 

typedef  QTVRMouseOverHotSpotProcPtr  MouseOverHotSpotProcPtr ; 

typedef  QTVRMouseOverHotSpotUPP  MouseOverHotSpotUPP ; 

typedef  QTVRImagi ngCompI eteProcPtr  Imagi ngCompl eteProcPtr ; 

typedef  QTVRImagi ngCompl eteUPP  Imagi ngCompl eteUPP ; 

typedef  QTVRBackBuffer Imagi ngProcPtr  BackBufferlmagingProcPtr; 

typedef  QTVRBackBuf f erlmagi ngUPP  BackBuf f erlmagi ngUPP ; 
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Special  Considerations 

The  OpaqueQTVRInstance  data  structure  is  not  part  of  the  public  QuickTime  API  and 
is  not  documented. 

See  Also 

See  Discovering  QuickTime  (listed  in  the  bibliography).  Chapter  17. 


Windows  Programming  Types 

Support  QuickTime  on  the  Windows  platform, 
typedef  long  QTMLMutex; 

typedef  struct  OpaqueQTMLSyncVar  *  QTMLSyncVar; 
typedef  QTMLSyncVar  *  QTMLSyncVarPtr ; 

Special  Considerations 

The  OpaqueQTMLSyncVar  data  structure  is  not  part  of  the  public  QuickTime  API  and 
is  not  documented. 

See  Also 

See  Discovering  QuickTime  (listed  in  the  bibliography).  Chapter  8. 


IV-2648 


Inside  QuickTime:  Defined  Data  Types 


Constants 


Atom  ID  Codes 


Identify  the  four-character  type  codes  of  atoms. 

Bandwi dthManagementPref sType 

Cl ipAID 

Col orTabl eAID 

Comp res sedMovi eAID 

Comp res sedMovi eDataAID 

Connect! onSpeedPref sType 

DataCompressi onAtomAID 

DatalnfoAID 

DataRefAID 

Data  Ref ContainerAID 

Ed i t  LI stAID 

Ed i tsAID 

FreeAtomType 

Generi cMedi alnfoAID 

GenericMedialnfoHeaderAID 

Handl erAID 

InputMapAID 

kActi on 

kActi onFl ags 

kActi onLi stAtomType 

kActi onParameter 

kActi onParameterMaxVal ue 

kActi onParameterMi nVal ue 

kActi onTarget 

kAudi oEndi anAtomType 

kAudi oFormatAtomType 

kAudi oTermi natorAtomType 

kAudi oVBRAtomType 

kCommentAtomType 

kCondi ti onal AtomType 

kCustomActi onHandl er 

kCustomHandl erDesc 

kCustomHandl erlD 

kEf f ectManuf acturerAtom 

kEf f ectNameAtom 

kEf f ectTypeAtom 

kExpressi onContai nerAtomType 

kGraphi csExportDescri pti on 


=  'bwmg' 

=  'clip' 

=  'ctab' 

=  'cmov' 

=  'cmvd' 

=  'cspd' 

=  'dcom' 

=  '  d  i  n  f ' 

=  'dref' 

=  'drfc' 

=  '  el  st ' 

=  'edts' 

=  'free' 

=  'gmin' 

=  'gmhd' 

=  ' hdl r ' 

=  'imap' 

=  'actn' 

=  '  fl  ag  ' 

=  'list' 

=  'parm' 

=  'maxv' 

=  'minv' 

=  'targ' 

=  'enda' 

=  'frma' 

=  0x00000000 
=  'vbra' 

=  'why  ' 

=  'test' 

=  'cust' 

=  'desc' 

=  'id 
=  'manu' 

=  'name' 

=  'type' 

=  'expr' 

=  'desc' 
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kGraphl csExportExtensi on 

= 

'ext  ' 

kGraphi csExportFi 1 eType 

= 

' ftyp ' 

kGraphi csExportGroup 

= 

'  expo ' 

kGraphi cs Expo rtM I M EType 

= 

'mime' 

klnitial Rotation Atom 

= 

'  inro ' 

klnputMapSublnputlD 

= 

' subi  ' 

kITextAtomType 

= 

' i txt ' 

kITextStri ngAtomType 

= 

'  text ' 

k  L i st El ementDataType 

= 

' daty ' 

k  L i stEl ementType 

= 

'type' 

kMovi eMedi aAl tText 

= 

' al tt ' 

kMovi eMedi aAutoPl ay 

= 

'play' 

kMovi eMedi aCl i pBegi n 

= 

'  cl pb ' 

kMovi eMediaClipDuration 

= 

' cl pd ' 

kMovi eMedi a  Data  Reference 

= 

'  mmdr ' 

kMovi eMediaEnableFrameStepping 

= 

'  enfs ' 

kMovi eMedi aHei ght 

= 

'  ht  ’ 

kMovi eMedi aLeft 

= 

'  1  eft ' 

kMovi eMedi aLoop 

= 

' 1 oop ' 

kMovi eMedi aRectangl eAtom 

= 

' rect ' 

kMovi eMedi a  Reg i on Atom 

= 

'  regi  ' 

kMovi eMedi aSl aveAudi o 

= 

'  si  au ' 

kMovi eMedi aSlaveTrackDurati on 

= 

'  si  tr ' 

kMovi eMedi aSpati al Adj  ustment 

= 

'fit  ' 

kMovi eMedi aT i tl e 

= 

' ti tl  ' 

kMovi eMedi aTop 

= 

'  top  ' 

kMovi eMedi aUseMIM EType 

= 

'mime' 

kMovi eMedi aWi dth 

= 

'wd 

kNameAtom 

= 

'name ' 

kNonLinearTweenHeader 

= 

'  nl th ' 

kOperandAtomType 

= 

'  oprn ' 

kOperatorAtomType 

= 

'  oper ' 

kQTCol orSyncProfile 

= 

' i ccp' 

kQTDont Recompress 

= 

' dntr ' 

kQT Event Record At omType 

= 

'  erec ' 

kQTEventType 

= 

' evnt ' 

kQTInterl aceStyl e 

= 

'  i  1  a  c  ' 

kQTParseTextHREFBaseURL 

= 

'burl  ' 

kQTParseTextHREFCl i ckPoi nt 

= 

'  c  1  i  k ' 

kQTParseTextHREFDel i mi  ter 

= 

' del m ' 

kQTParseTextHREFHREF 

= 

'href' 

kQTParseTextHREFIsAutoHREF 

= 

'  auto ' 

kQTParseTextHREFRecomposeHREF 

= 

'  rhrf ' 

kQTParseTextHREFTarget 

= 

'targ' 

kQTParseTextHREFUseAl tDel i m 

= 

' al td ' 

kQTResol utionSettings 

= 

' reso ' 

kQTSAnnotati onsChangedNotifi cation 

= 

' meta ' 

kQTSBandwi dthAlertNotifi cation 

= 

' bwal  ' 

kQTSBufferT i meAID 

= 

'  buf r ' 
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kQTSCl i pRectAID 
kQTSConnecti onAtomType 
kQTSConnecti onMethodPref sType 
kQTSConnecti onPrefsType 
kQTSConnecti onPrefsVersi on 
kQTSDi rectConnectPref sType 
kQTSDont Proxy Da t a Type 
kQTSDont Proxy Pref sAtomType 
kQTSDurati onAID 
kQTSDurati onlnfo 
kQTSErrorNoti f i cati on 
kQTSHTTP Proxy Pref sType 
kQTSHTTPT  ransportType 
kQTSLost Percent  Info 
kQTSMedi aDescri pti onTextAID 
kQTSMedi aStreamAID 
kQTSMedi aStreamHeaderAID 
kQTSMedi aTypelnfo 
kQTSNamelnfo 

kQTSNewPresentati onNoti f i cati on 
kQTSNormal St atusDi mens  ions  Info 
kQTSPrerol 1 AckNoti f i cati on 
kQTSPresDoneChangi ngNoti f i cati on 
kQTSPresentati onAID 
kQTSPresentati onChangedNoti f i cati on 
kQTSPresentati onGoneNoti f i cati on 
kQTSPresentati onHeaderAID 
kQTS Proxy Pref sAtomType 
kQTSRTSPProxy Pref sType 
kQTSServerNameNoti f i cati on 
kQTSSOCKS Pref sType 
kQTS SOCKS Proxy Pref sType 
kQTSSourceCl i pRectlnfo 
kQTSSourceGraphi csModelnfo 
kQTSSourceLanguagelnf o 
kQTSSourceMatrixInf o 
kQTSSourceTrackFl agslnfo 
kQTSSourcellserData  Inf  o 
kQTSStartAckNoti f i cati on 
kQTSStati sti cslnfo 
kQTSStati sti csNameAtomType 
kQTSStati sti csStreamAtomType 
kQTSStati sti csUni tsAtomType 
kQTSStati sti csUni tsNameAtomType 
kQTSStatusNoti f i cati on 
kQTSStreamBegi nChangi ngNoti f i cati on 
kQTSStreamDoneChangi ngNoti f i cati on 
kQTSStreamMedi aType 
kQTSTargetBufferDurati onlnfo 


'clip' 
'  conn ' 
'mthd ' 
'  stem' 
' vers ' 
'  dret ' 
'data ' 
'  nopr ' 
' dura ' 
' dura ' 
'err  ' 
'  http ' 
' http ' 
'  1  pet ' 
'mdes ' 
'mstr' 
'mshd ' 
'mtyp' 
'  name ' 
' nprs ' 
'  nstd ' 
' pack' 
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'  pres ' 
'  prch ' 
'xprs ' 
'  phdr ' 
'  prxy ' 
' rtsp ' 
'  snam' 
' sock' 
'  seks ' 
'  ocl  p ' 
' ogrm' 
'  ol  ng ' 
'  omat ' 
'  otf  I  ' 
'  oudt ' 
' sack' 
'  stat ' 
'  name ' 
' strm' 
'unit' 
'unin' 
'  stat ' 
'  steb ' 
'  sted ' 
' strm' 
' buf r ' 
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kQTSTCPT  ransportType 

kQTSTotal Data  Rate  Info 

kQTSTotal DataRatelnlnfo 

kQTSTotal DataRateOutlnfo 

kQTST  ransAndProxyAtomType 

kQTST  ransportPrefsAtomType 

kQTSUDPT  ransportType 

kQTTargetDataSi ze 

kQTVRAngl e Range At omType 

kQTVRCol orCursorAtomType 

kQTVRCursorAtomType 

kQTVRCursorParentAtomType 

kQTVRFOVConstrai nt At omType 

kQTVRHot Spot At omType 

kQTVRHotSpotlnfoAtomType 

kQTVRHot Spot Pa  rent At omType 

kQTVRHotSpotT  rackRef At omType 

kQTVRImageT  rackRef At omType 

kQTVRImagi ng Pa  rent At omType 

kQTVRLi nklnfoAtomType 

kQTVRNodeHeader At omType 

kQTVRNode I DAt omType 

kQTVRNodeLocati on At omType 

kQTVRNode Pa  rent At omType 

kQTVRObjectHotSpotT  rackRef Atom ID 

kQTVRObjectlmageT  rackRef Atom ID 

kQTVRObjectlmagi ngAtomType 

kQTVRObjectlnfoAtomlD 

kQTVRObjectlnfoAtomType 

kQTVRPanConstrai nt At omType 

kQTVRPanoImagi ngAtomType 

kQTVRPanoSampl e Data At omType 

kQTVRStri ngAtomType 

kQTVRStri ngEncodi ngAtomType 

kQTVRT iltConstrai nt At omType 

kQTVRT  rackRef ArrayAtomType 

kQTVRWorl dHeader At omType 

kSpri teAtomType 

kSpriteBehavi orsAtomType 

kSpri teCursorBehavi or At omType 

kSpri teFloatingPointVariabl e At omType 

kSpri telmageAtomType 

kSpri tel mageBehavi or At omType 

kSpri telmageDataAtomType 

kSpri telmageDataRef At omType 

kSpri telmageDataRefTypeAtomType 

kSpri  telmageDefaul t Image  I ndexAt omType 

kSpri telmageGroupIDAtomType 

kSpri telmageNameAtomType 


=  'tcp  ' 

=  'drtt' 

=  ' drti ' 

=  'drto' 

=  'strp' 

=  'trns' 

=  'udp  ' 

=  'dasz' 

=  'arng' 

=  'crsr' 

=  'CURS' 

=  'vrcp' 

=  'fcon' 

=  'hots' 

=  '  h  s  i  n  ' 

=  'hspa' 

=  'hstr' 

=  ' i mtr ' 

=  'imgp' 

=  'link' 

=  'ndhd' 

=  ' vrni ' 

=  ' nl oc ' 

=  'vrnp' 

=  0x00000001 
=  0x00000001 
=  'imob' 

=  0x00000001 
=  ' obj i ' 

=  'peon' 

=  'impn' 

=  'pdat' 

=  'vrsg' 

=  'vrse' 

=  'tcon' 

=  'tref' 

=  'vrsc' 

=  'sprt' 

=  'beha' 

=  'crsr' 

=  'flov' 

=  'imag' 

=  'imag' 

=  'imda' 

=  'imre' 

=  'imrt' 

=  '  def  i ' 

=  'imgr' 

=  'name' 
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kSpri telmageRegi strati onAtomType 

= 

'  i  mrg ' 

kSpri telmagesContai nerAtomType 

= 

' i met ' 

kSpri teNameAtomType 

= 

'  name ' 

kSpri teSharedDataAtomType 

= 

'  df  1 1 ' 

kSpri teSt a t us  St ri ngsBehavi orAtomType 

= 

'  sstr ' 

kSpri teStri ngVari abl eAtomType 

= 

' strv ' 

kSpri teUses ImagelDsAtomType 

= 

'  uses ' 

kSpri  teVari abl esContai nerAtomType 

= 

' vars ' 

kTargetChi 1 dMovieMovi elD 

= 

'momi  ' 

kTargetChi IdMovieTrackID 

= 

'moti  ' 

kTargetChi 1 dMovi eTrackName 

= 

'motn ' 

kTargetMovi elD 

= 

'moi d ' 

kTargetParentMovie 

= 

'mopa ' 

kTargetRootMovi  e 

= 

'moro' 

kTa r get Spri te Index 

= 

'spin' 

kTargetTrackID 

= 

'  tri  d ' 

kTargetTrackName 

= 

' trna ' 

kTrackModi fi er Input 

= 

'  i  n ' 

kTrackModi f i erlnputName 

= 

'  name ' 

kT  rackModi f i erObjectID 

= 

' obi d ' 

kT  rackModi fi erObjectQT Event Send 

= 

'  evnt ' 

kT  rackModi fi erPanAngl e 

= 

'pan  ' 

kTrackModi f i er Reference 

= 

'ssrc' 

kT  rackModi fi erTi 1 tAngl e 

= 

'tilt' 

kTrackModi fi erType 

= 

'  ty' 

kTrackModi fi erVerti cal Fi el dOf Vi ewAngl e 

= 

'  f  ov  ' 

kTrackProperty Inst anti ation 

= 

'  i  n  s  t ' 

kT  rackPropertyMedi aType 

= 

'mtyp' 

kT  rackReferenceChapterLi st 

= 

' chap ' 

kT  rackRef erenceModi f i er 

= 

'ssrc' 

kT  rackRef erenceT i meCode 

= 

'  tmed ' 

kTween3dIni ti al Condi ti on 

= 

' i end ' 

kTweenData 

= 

'data ' 

kTweenDurati on 

= 

'  twdu ' 

kTweenEntry 

= 

'  twen ' 

kTweenFl ags 

= 

'  fl  ag ' 

kTween Interpol ation  ID 

= 

'  i  ntr ' 

kTweenOutputMax 

= 

' omax' 

kTweenOutputMi n 

= 

' omi n ' 

kTweenPi ctureData 

= 

'PICT' 

kTweenRegi onData 

= 

' qdrg ' 

kTween Sequence El ement 

= 

'  seqe ' 

kTweenStartOf f set 

= 

'  twst ' 

kTweenType 

= 

'  twnt ' 

kTweenType3dAngl eAspectCameraData 

= 

'  3caa ' 

kTweenType3d Camer a  Data 

= 

'3cam' 

kTweenType3dMatri x 

= 

'  3mat ' 

kTweenType3dMatri xN on  Li  near 

= 

'  3  n  1  r ' 

kTweenType3dQuaterni on 

= 

'  3qua  ' 
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kTweenType3d Rotate 

= 

'  3rot ' 

kTweenType3dRotateAboutAxi s 

= 

'  3rax ' 

kTweenType3dRotateAboutPoi nt 

= 

'  3rap' 

kTweenType3dRotateAboutVector 

= 

'  3rvc ' 

kTweenType3dScale 

= 

' 3sca ' 

kTweenType3dSound Localization  Data 

= 

' 3sl c ' 

kTweenType3dTranslate 

= 

' 3tra ' 

kTweenType3dVR0bject 

= 

' 3vro ' 

kTweenTypeAtomLi st 

= 

' atom ' 

kTweenTypeMultiMatrix 

= 

'  mul  m ' 

kTweenTypePathToFixedPoint 

= 

'gxfp' 

kTweenTypePathToMatrixRotation 

= 

'  gxpr ' 

kTweenTypePathToMatrixTranslation 

= 

'  gxmt ' 

kTweenTypePathToMatrixTransl at ion And Rotation 

= 

'  gxmr ' 

kTweenTypePathXtoY 

= 

' gxxy ' 

kTweenTypePathYtoX 

= 

'gxyx' 

kTweenTypePolygon 

= 

'poly' 

kTweenTypeSpi n 

= 

'spin' 

kWh i chActi on 

= 

'whic ' 

LoadSetti ngsAID 

= 

'  1 oad ' 

MatteAID 

= 

' matt ' 

MatteCompAID 

= 

' kmat ' 

Medl aAID 

= 

' mdi a ' 

Medi aHeaderAID 

= 

'  mdhd ' 

Medl alnfoAID 

= 

'  mi  nf ' 

Movi eAID 

= 

' moov ' 

Movi eBufferHi ntsAID 

= 

'  mbf h ' 

Movi eDataAtomType 

= 

' mdat ' 

Movi eDataRefAl i as AID 

= 

' mdra ' 

Movi eHeaderAID 

= 

' mvhd ' 

Movi eResourceAtomType 

= 

'  moov ' 

PropertyAtomAID 

= 

'  code ' 

quickTimelmageFileColorSyncProfil eAtom 

= 

'  i i cc ' 

qui ckTi melmageFi 1  el mage Data Atom 

= 

'  i dat ' 

qui ckTi melmageFi 1 elmageDescri pti on Atom 

= 

'  i dsc ' 

qui ckTi melmageFi 1 eMeta Data Atom 

= 

' meta ' 

ReferenceMovieAlternateGroupAID 

= 

' rmag ' 

ReferenceMovi eComponentCheckAID 

= 

' rmcd ' 

ReferenceMovi eCPURatingAID 

= 

' rmcs ' 

ReferenceMovi eDataRateAID 

= 

' rmdr ' 

ReferenceMovi eDataRefAl D 

= 

' rdrf ' 

ReferenceMovi eDescri ptor AID 

= 

' rmda ' 

ReferenceMovi e La nguageA ID 

= 

' rml a ' 

ReferenceMovi eQual i tyAID 

= 

' rmqu ' 

ReferenceMovi eRecordAID 

= 

' rmra ' 

ReferenceMovi eVersionCheckA ID 

= 

' rmvc ' 

RgnCl i pAID 

= 

'  crgn ' 

Sampl eTabl eAID 

= 

' stbl  ' 

scSpati al Setti ngsType 

= 

' sptl  ' 
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Ski pAtomType 

= 

'skip' 

Sound Loca 1 i zationAID 

= 

'sloe' 

SoundMedialnfoHeaderAID 

= 

'  smhd ' 

STChunkOf f set64AID 

= 

'  co64 ' 

STChunkOffsetAID 

= 

'  stco ' 

STSampl eDescAID 

= 

'  stsd ' 

STSampl elDAID 

= 

' sti d ' 

STSampl eSi zeAID 

= 

'  stsz ' 

STSampl eToChunkAID 

= 

' stsc ' 

STShadowSyncAID 

= 

'  stsh ' 

STSyncSampl eAID 

= 

'  stss ' 

STTimeToSampAID 

= 

'  stts ' 

TrackAID 

= 

'trak' 

TrackHeaderAID 

= 

' tkhd ' 

TrackReferenceAID 

= 

' tref ' 

UserDataAID 

= 

'  udta ' 

Vi deoMedi alnfoHeaderAID 

= 

'  vmhd ' 

Wi deAtomPl acehol derType 

= 

'wide' 

See  Also 

The  atoms  used  in  the  QuickTime  API  are  listed  in  the  chapter  "Atoms"  in  this  book. 
For  further  information  about  atoms,  see  Inside  QuickTime:  QuickTime  File  Format 

(listed  in  the  bibliography). 
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Codec  Identifiers 


Identify  codec  components  and  data  types  in  QuickTime. 


kAni mati onCodecType 

kAVRJPEGCodecType 

kBaseCodecType 

kBMPCodecType 

kCi nepakCodecType 

kCl oudCodecType 

kCMYKCodecType 

kComponentVi deoCodecType 

kComponentVi deoSi gned 

kComponentVi  deollnsigned 

kDVCNTSCCodecType 

kDVCPALCodecType 

kDVCProNTSCCodecType 

kDVCProPALCodecType 

k  Fi reCodecType 

kFLCCodecType 

k48RGBCodecType 

kGI FCodecType 

kGraphi csCodecType 


=  '  rl  e 
=  '  avr 
=  'base 
=  ' WRLE 
=  'cvid 
=  'clou 
=  'cmyk 
=  'yuv2 
=  'yuvu 
=  'yuvs 
=  '  dvc 
=  'dvcp 
=  'dvpn 
=  'dvpp 
=  'fire 
=  'flic 
=  'b48r 
=  'gif 
=  '  smc 
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kH261CodecType 

=  ' h261 ' 

kH263CodecType 

=  ' h263 ' 

kIndeo4CodecType 

=  ' IV41 ' 

kJPEGCodecType 

=  'jpeg' 

kMacPai ntCodecType 

=  ' PNTG ' 

kMicrosoftVideolCodecType 

=  'msvc' 

kMoti onJPEGACodecType 

=  'mjpa ' 

kMoti onJPEGBCodecType 

=  'mjpb' 

kMpegYUV420CodecType 

=  'myuv' 

kOpenDHLJPEGCodecType 

=  'dmbl' 

kPhotoCDCodecType 

=  'kpcd' 

kPlanarRGBCodecType 

=  ' 8BPS ' 

kPNGCodecType 

-  'png  ' 

kQui ckDrawCodecType 

=  'qdrw' 

kQui ckDrawGXCodecType 

=  ' qdgx ' 

kRawCodecType 

=  'raw  ' 

kSGICodecType 

=  ’.SGI' 

kl6GrayCodecType 

=  ' bl6g ' 

k64ARGBCodecType 

=  'b64a' 

kSorensonCodecType 

=  ' SVQ1 ' 

kSorensonYUV9CodecType 

=  'syv9' 

kTargaCodecType 

=  ' tga  ' 

k32AlphaGrayCodecType 

=  ' b32a ' 

kTI FFCodecType 

=  'tiff' 

kVectorCodecType 

=  'path' 

kVi deoCodecType 

=  'rpza' 

kWaterRippleCodecType 

=  '  r  i  p  1  ' 

kWi ndowsRawCodecType 

=  'WRAW' 

kYUV420CodecType 

=  ’y420 

'  a  v  r  '  ,  'gif  '  , . . . 

Note  that  the  fourth  character  of  these  type  values  is  a  space  (ASCII  32). 
kComponentVi deoSigned 

For  historical  reasons,  'yuvu '  identifies  the  signed  type. 
kComponentVi  deotlnsigned 

For  historical  reasons,  'yuvs'  identifies  the  unsigned  type. 

Discussion 

All  codec  components  of  the  same  type  provide  the  same  kinds  of  services  and 
support  a  common  application  programming  interface. 

See  Also 

For  more  general  component  types,  see  "Component  Types"  (IV-2621). 
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Color  Constants 


Identify  default  colors  for  a  graphics  importer  component. 


bl  ackCol  or  =  33 

bl ueCol or  =  409 

cyanColor  =  273 

greenCol or  =  341 

magentaColor  =  137 

redColor  =  205 

whi teCol or  =  30 

yellowColor  =  69 


See  Also 

For  an  example  of  passing  color  constants,  see 
Graphi  cs  ImportGetDef  aul  tGraphi  csMode  (1-630). 


Component  Identifiers 


Identify  the  types  of  components. 

BaseMedi aType 

=  'gnrc' 

cl ockComponentType 

=  'clok' 

comp res sorComponent Type 

=  'imco' 

CreateFi 1 ePrevi ewComponentType 

=  'pmak' 

DataHandl erType 

=  ' dhl  r ' 

decomp res sorComponentType 

=  'imdc' 

FI ashMedi aType 

=  'fish' 

HandleDataHandlerSubType 

=  ' hndl  ' 

Medi aHandl erType 

=  'mhlr' 

MovieControll erComponentType 

=  'play' 

Movi eExportType 

=  'spit' 

Movi elmportType 

=  'eat  ' 

Movi eMedi aType 

=  'moov' 

MPEGMedi aType 

=  'MPEG' 

Musi eMedi aType 

=  'musi  ' 

ResourceDataHandlerSubType 

=  'rsrc' 

SeqGrabChannel Type 

=  'sgch' 

SeqGrabComponentType 

=  'barg' 

SeqGrabCompressi onPanelType 

=  'cmpr' 

SeqGrabPanel Type 

=  ' sgpn ' 

SeqGrabSourcePanel Type 

=  'sour' 

ShowFi 1 ePrevi ewComponentType 

=  'pnot' 

SoundMedi aType 

=  'soun' 

Spri teMedi aType 

=  'sprt' 

Standard Comp res  si onSubType 

=  'imag' 
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StandardCompressi onSubTypeSound 

StandardCompressi onType 

systemMi crosecondClock 

systemMi llisecondClock 

systemSecondCl ock 

systemT i ckCl ock 

TextMedi aType 

Three DeeMediaType 

TimeCodeMedi aType 

TweenMedi aType 

URLDataHandlerSubType 

vi deoDi gi ti zerComponentType 

Vi deoMedi aType 

Wi redActi onHandlerType 


=  'soun' 
=  ' scdi  ' 
=  'micr' 
=  'mill' 
=  'seco' 
=  'tick' 
=  'text' 
=  ' qd3d ' 
=  'tmcd' 
=  'twen' 
=  'url  ' 
=  ' vdi g  ' 
=  'vide' 
=  'wire' 


' eat  ' ,  'url  ' 

Note  that  the  fourth  character  of  these  types  is  a  space  (ASCII  32). 

' i mco ' 

Generic  type  for  components  that  compress  graphic  images. 

' i mdc ' 

Generic  type  for  components  that  decompress  graphic  images. 

'micr' 

A  clock  subtype  measuring  millionths  of  a  second  since  user  startup. 

'mill' 

A  clock  subtype  measuring  thousandths  of  a  second  since  user  startup. 

'seco ' 

A  clock  subtype  measuring  seconds  since  January  1, 1904. 

'tick' 

A  clock  subtype  measuring  sixtieths  (1/60)  of  a  second  since  user  startup. 

Discussion 

All  components  of  the  same  type  or  subtype  provide  the  same  kinds  of  services  and 
support  a  common  application  programming  interface.  Codecs  have  their  own  set 
of  types. 

See  Also 

For  the  type  constants  of  codecs,  see  "Codec  Types"  (IV-2619).  For  an  example  of 
using  component  types,  see  GetComponentTypeModSeed  (1-395). 
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kControl 1 erModul ati onWheel  =  1 

kControl 1 erBreath  =  2 

kControl 1 erFoot  =  4 

kControl 1 erPortamentoTime  =  5 

kControl 1 erVol ume  =  7 

kControl 1 erBal ance  =  8 

kControl 1 erPan  =  10 

kControl 1 erExpressi on  =  11 

kControl 1 erLeverl  =  16 

kControl 1 erLever2  =  17 

kControl  1  erl_ever3  =  18 

kControl 1 erLever4  =  19 

kControl  1  erl_ever5  =  80 

kControl 1 erLever6  =  81 

kControl 1 erLever7  =  82 

kControl  1  erl_ever8  =  83 

kControl 1 erPi tchBend  =  32 

kControl 1 erAfterTouch  =  33 

kControl 1 erSustai n  =  64 

kControl 1 erSostenuto  =  66 

kControl 1 erSoftPedal  =  67 

kControl 1 erReverb  =  91 

kControl 1 erTremol o  =  92 

kControl 1 erChorus  =  93 

kControl 1 erCel este  =  94 

kControl 1 erPhaser  =  95 

kControl 1 erEdi tPart  =  113 

kControl 1 erMasterTune  =  114 


kControl 1 erModul ati onWheel 

This  controller  controls  the  modulation  wheel.  A  modulation  wheel  adds  a 
periodic  change  to  the  volume  or  pitch  of  a  sounding  tone,  depending  on  the 
modulation  depth  knobs. 

kControl 1 erBreath 

This  controller  controls  breath. 
kControl 1 erFoot 

This  controller  controls  the  foot  pedal. 
kControl 1 erPortamentoTime 

This  controller  adjusts  the  slur  between  notes.  Set  the  time  to  0  to  turn  off 
portamento;  there  is  no  separate  control  to  turn  portamento  on  and  off. 

kControl 1 erVol ume 

This  controller  controls  volume. 
kControl 1 erBal ance 

This  controller  controls  balance  between  channels. 
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kControl 1 erPan 

This  controller  controls  balance  on  the  QuickTime  music  synthesizer  and  some 
others.  Values  are  256-512,  corresponding  to  left  to  right. 
kControl 1 er Exp  res si  on 

This  controller  provides  a  second  volume  control. 
kControl 1 erLeverl 

Eight  general-purpose  controllers,  kControl  1  erLeverl  through 
kControl  1  erLever8. 
kControl lerPitchBend 

This  controller  bends  the  pitch.  Pitch  bend  is  specified  in  positive  and  negative 
semitones,  with  7  bits  per  fraction. 
kControl 1 erAfterTouch 

This  controller  controls  channel  pressure. 
kControl 1 erSustai n 

This  controller  controls  the  sustain  effect.  The  value  is  a  Bool  e an;  positive  for  on, 
0  or  negative  for  off. 
kControl lerSostenuto 

This  controller  controls  sostenuto. 
kControl lerSoft Pedal 

This  controller  controls  the  soft  pedal. 
kControl 1 erReverb 

This  controller  controls  reverberation. 
kControl 1 erT  remol o 

This  controller  controls  tremolo. 
kControl 1 erChorus 

This  controller  controls  the  amount  of  signal  to  feed  to  the  chorus  special  effect 
unit. 

kControl 1 erCel este 

This  controller  controls  the  amount  of  signal  to  feed  to  the  celeste  special  effect 
unit. 

kControl 1 erPhaser 

This  controller  controls  the  amount  of  signal  to  feed  to  the  phaser  special  effect 
unit. 

kControl lerEditPart 

This  controller  sets  the  part  number  for  which  editing  is  occurring.  For 
synthesizers  that  can  edit  only  one  part. 
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kControllerMasterTune 

This  controller  offsets  the  entire  synthesizer  in  pitch. 

Discussion 

The  controller  numbers  used  by  QuickTime  are  mostly  identical  to  the  standard 
MIDI  controller  numbers.  These  are  signed  8.8  values.  The  full  range,  therefore,  is 
-128.00  to  127+127/128  (or  0x8000  to  0x7  FFF).  All  controls  default  to  zero  except  for 
volume  and  pan. 

Pitch  bend  is  specified  in  fractional  semitones,  which  eliminates  the  restrictions  of  a 
pitch  bend  range.  You  can  bend  as  far  as  you  want,  any  time  you  want. 

The  last  16  controllers  (113  through  128)  are  global  controllers.  Global  controllers 
respond  when  the  part  number  is  given  as  0,  indicating  the  entire  synthesizer. 

See  Also 

Seethe  SynthesizerDescription  (IV-2465)  structure. 


Data  References 


Identify  the  types  of  data  references. 


BaseMedi aType 
FI ashMedi aType 
HandleDataHandlerSubType 
Movi eMedi aType 
MPEGMedi aType 
Musi eMedi aType 
NuilDataHandlerSubType 
PointerDataHandlerSubType 
rAl i asType 

ResourceDataHandlerSubType 
SoundMedi aType 
Spri teMedi aType 
TextMedi aType 
ThreeDeeMedi aType 
TimeCodeMedi aType 
TweenMedi aType 
URLDataHandl erSubType 
Vi deoMedi aType 
Wi redActi onHandl erType 


=  'gnrc' 
=  '  fl  sh  ' 
=  ' hndl  ' 
=  'moov' 
=  'MPEG' 
=  'musi  ' 
=  'null  ' 
=  'ptr  ' 
=  '  a  1  i  s  ' 
=  'rsrc' 
=  'soun' 
=  'sprt' 
=  'text' 
=  'qd3d' 
=  'tmcd' 
=  'twen' 
=  'url  ' 
=  'vide' 
=  'wire' 


rAl i asType 

The  data  reference  is  a  Mac  OS  alias;  for  information  about  aliases,  see  Inside 
Macintosh:  Macintosh  Toolbox  Essentials  (listed  in  the  bibliography). 
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See  Also 

For  an  example  of  using  data  reference  type  codes,  see  DataHGetDataRef  (1-189). 


Effects  Codes 


Identify  QuickTime  visual  effect  components. 


//  One-source  effects 

kBlurlmageFilterType 

kSharpenlmageFilterType 

kEdgeDetectlmageFilterType 

kEmbossImageFi 1 terType 

kConvolvelmageFilterType 

kAl phaGa in  Image Fi 1 terType 

kRGBColorBalancelmageFilterType 

kHSLColorBalancelmageFilterType 

kColorSyncImageFil terType 

kFilmNoiselmageFil terType 

kSolarizelmageFil terType 

kCol orTi nt Image Fi 1 terType 

kLensFlarelmageFil terType 

kBrightnessContrastlmageFil terType 


=  'blur' 
=  'shrp' 
=  'edge' 
=  'embs' 
=  'genk' 
=  'gain' 
=  'rgbb' 
=  ' hsl b ' 
=  'sync' 
=  'fmns' 
=  'sol r ' 
=  'tint' 
=  '  1 ens  ' 
=  'brco' 


//  Two-source  effects 

kAl phaComposi torTransitionType 

kCrossFadeTransitionType 

kChromaKeyT  ransitionType 

klmplodeTransitionType 

kExpl odeTransitionType 

kGradientTransitionType 

kPushTransitionType 

kSlideTransitionType 

kWipeT ransitionType 

klrisT ransitionType 

kRadialTransitionType 

kMatri xT  ransitionType 

kZoomT  ransitionType 


=  'bind' 
=  ' dsl v  ' 
=  'ckey' 
=  'mplo' 
=  'xplo' 
=  'matt' 
=  'push' 
=  'slid' 
=  'smpt' 
=  'smp2' 
=  'smp3' 
=  'smp4' 
=  'zoom' 


Discussion 

One-source  effects  modify  a  single  image.  Two-source  effects  transition  between 
one  image  and  another. 

See  Also 

For  an  example  of  using  effects  codes,  see  MakelmageDescri  pti  onForEffect  (11-785). 
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Error  Codes 


Identify  errors  generated  while  executing  QuickTime  calls. 


//  General  QuickTime  errors 
couldNotResolveDataRef 
badlmageDescripti on 
badPubl i cMovi eAtom 
cantFi ndHandl er 
cantOpenHandl er 
badComponentType 
noMedi aHandl er 
noDataHandl er 
i nval i dMedi a 
i nval i dT  rack 
i nval i dMovi e 
i nval  i dSampl eTabl e 
i nval i dDataRef 
i nval i dHandl er 
i nval i dDurati on 
i nval i dT i me 

cantPutPubl i cMovi eAtom 

badEdi  t Li  st 

medi aTypesDontMatch 

prog  res sProcAborted 

movi eTool boxUni ni ti al i zed 

noRecordOf App 

wf Fi 1 eNotFound 

cantCreateSi ngl eForkFi 1 e 

i nval i d  Ed i tState 

nonMatchi ngEdi t St ate 

stal eEdi tState 

user Data ItemNotFound 

maxSi zeToGrowTooSmal 1 

badTracklndex 

trackIDNotFound 

trackNotlnMovi e 

timeNotlnTrack 

timeNotlnMedi a 

badEdi tlndex 

i nternal Qui ckTimeError 

cantEnabl eT  rack 

i nval i dRect 

i nval i dSampl eNum 

i nval i dChunkNum 

inval i dSampl eDesc Index 

i nval i dChunkCache 

i nval i dSampl eDescri pti on 

dataNotOpenForRead 


-2000 

-2001 

-2002 

-2003 

-2004 

-2005 

-2006 

-2007 

-2008 

-2009 

-2010 

-2011 

-2012 

-2013 

-2014 

-2015 

-2016 

-2017 

-2018 

-2019 

-2020 

-2020 

-2021 

-2022 

-2023 

-2024 

-2025 

-2026 

-2027 

-2028 

-2029 

-2030 

-2031 

-2032 

-2033 

-2034 

-2035 

-2036 

-2037 

-2038 

-2039 

-2040 

-2041 

-2042 


Inside  QuickTime:  Constants 


IV-2663 


dataNotOpenForWri te 

dataAl readyOpenForWrite 

dataAl readyCl osed 

endOf DataReached 

dataNoDataRef 

noMovi eFound 

i nval i dDataRefContai ner 

badDataRef Index 

noDefaul tDataRef 

coul  dNotllseAnExi  sti  ngSampl  e 

featureUnsupported 

unsupportedAuxi 1 i ary  Import Data 

auxi 1 1 aryExportDataUnavai 1 abl e 

samplesAl readylnMediaErr 

noSourceTreeFoundErr 

sourceNotFoundErr 

movi eTextNotFoundErr 

missingRequi redParameterErr 

i nval idSpriteWorldProperty Err 

i nval i dSpri teProperty Err 

gWorl dsNotSameDepthAndSi zeErr 

i nval i dSpri tel ndexErr 

i nval i dlmagelndexErr 

inval i dSpri telDErr 

//  QuickTime  Music  Architecture  errors 

i nternal ComponentErr 

notlmpl ementedMusi cOSErr 

cantSendToSynthesi zerOSErr 

cantRecei veFromSynthesi zerOSErr 

i 1 1 egal Voi ceAl 1 ocati onOSErr 

i 1 1 egal PartOSErr 

i 1 1 egal Channel OSErr 

i 1 1 egal KnobOSErr 

i 1 1 egal KnobVal ueOSErr 

i 1 1 egal Instrument OSErr 

i 1 1 egal Control  1 erOSErr 

mi di ManagerAbsentOSErr 

synthes i zerNot Respond ingOSErr 

synthesi zerOSErr 

i 1 1 egal NoteChannel OSErr 

noteChannel NotAl 1 ocatedOSErr 

tunePl ayerFul 1 OSErr 

tuneParseOSErr 

noExportProcAvai 1 abl eErr 

vi deoOutputlnUseErr 

//  Windows-specific  errors 
componentDl 1 LoadErr 
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2043 

2044 

2045 

2046 

2047 

2048 

2049 

2050 

2051 

2052 

2053 

2057 

2058 

2059 

2060 
2061 
2062 

2063 

2064 

2065 

2066 

2067 

2068 
2069 


2070 

2071 

2072 

2073 

2074 

2075 

2076 

2077 

2078 

2079 

2080 
2081 
2082 

2083 

2084 

2085 

2086 
2087 

2089 

2090 


2091 


component D1 lEntry NotFoundErr 

= 

-2092 

qtml D1 1 LoadErr 

= 

-2093 

qtml Dll  Entry NotFoundErr 

= 

-2094 

qtml  Uni ni ti al i zed 

= 

-2095 

unsupportedOSErr 

= 

-2096 

unsupported  Process  or  Err 

= 

-2097 

noVideoTracklnMovieErr 

= 

-2054 

noSoundTracklnMovieErr 

= 

-2055 

soundSupportNotAvai 1 abl eErr 

= 

-2056 

//  QT  atom  errors 

cannotFi ndAtomErr 

= 

-2101 

notLeaf AtomErr 

= 

-2102 

atomsNotOf SameTypeErr 

= 

-2103 

atomlndexInvalidErr 

= 

-2104 

dupl i cateAtomTypeAndIDErr 

= 

-2105 

i nval i dAtomErr 

= 

-2106 

i nval i dAtomContai nerErr 

= 

-2107 

i nval i dAtomTypeErr 

= 

-2108 

can not Be  Leaf AtomErr 

= 

-2109 

//  Data  access  errors 

pathTooLongErr 

= 

-2110 

emptyPathErr 

= 

-2111 

noPathMappi ngErr 

= 

-2112 

pathNotVeri f i edErr 

= 

-2113 

unknownFormatErr 

= 

-2114 

wackBadFi 1 eErr 

= 

-2115 

wackForkNotFoundErr 

= 

-2116 

wackBadMeta Data  Err 

= 

-2117 

qf cbNotFoundErr 

= 

-2118 

qf cbNotCreatedErr 

= 

-2119 

AAPNotCreatedErr 

= 

-2120 

AAPNotFoundErr 

= 

-2121 

ASDBadFleaderErr 

= 

-2122 

ASDBadForkErr 

= 

-2123 

ASDEntry NotFoundErr 

= 

-2124 

f i 1 eOffsetTooBi gErr 

= 

-2125 

notAl 1 owedToSaveMovi eErr 

= 

-2126 

qtNetworkAl readyAl 1 ocatedErr 

= 

-2127 

url  Da  t  a  FI  HTTP  Protocol  Err 

= 

-2129 

url  DataFIHTTPNoNetDri  verErr 

= 

-2130 

urlDataHHTTPURLErr 

= 

-2131 

url DataHHTTPRedi rectErr 

= 

-2132 

urlDataFIFTPProtocolErr 

= 

-2133 

url  DataFIFTPShutdownErr 

= 

-2134 

urlDataFIFTPBadUserErr 

= 

-2135 

url  DataFIFTPBadPass  word  Err 

= 

-2136 

urlDataFIFTPServerErr 

= 

-2137 

CON 


Inside  QuickTime:  Constants 


IV-2665 


Constants 


urlDataHFTPDataConnectionErr 

url Da taHFTPNoDi rectory  Err 

urlDataHFTPQuotaErr 

urlDataHFTPPermissionsErr 

urlDataHFTPFilenameErr 

urlDataHFTPNoNetDriverErr 

urlDataHFTPBadNameListErr 

url DataHFTPNeedPasswordErr 

url DataHFTPNoPasswordErr 

urlDataHFTPServerDisconnectedErr 

url DataHFTPURLErr 

notEnoughDataErr 

qtActi onNotHandledErr 

//  Digitizing  errors 

di gi Uni mpErr 

qtParamErr 

matrixErr 

notExactMatrixErr 

noMoreKeyCol orsErr 

notExactSi zeErr 

badDepthErr 

noDMAErr 

badCal 1 OrderErr 

//  Codec  errors 

codecErr 

noCodecErr 

codecUni mpErr 

codecSi zeErr 

codecScreenBuf Err 

codecImageBuf Err 

codecSpool Err 

codecAbortErr 

codecWoul dOffscreenErr 

codecBadDataErr 

codecDataVersErr 

codec  Ext en si onNotFoundErr 

scTypeNotFoundErr 

codecCondi ti onErr 

codecOpenErr 

codecCantWhenErr 

codecCantQueueErr 

codecNothingToBlitErr 

codec NoMemory PI easeWaitErr 

codecDi sabl edErr 

codecNeedToFlushChainErr 

lockPortBitsBadSurfaceErr 

lockPortBitsWi ndowMovedErr 
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=  -2138 
=  -2139 
=  -2140 
=  -2141 
=  -2142 
=  -2143 
=  -2144 
=  -2145 
=  -2146 
=  -2147 
=  -2148 
=  -2149 
=  -2157 


=  -2201 
=  -2202 
-  -2203 
=  -2204 
=  -2205 
=  -2206 
=  -2207 
=  -2208 
=  -2209 


=  -8960 
=  -8961 
=  -8962 
=  -8963 
=  -8964 

-  -8965 
=  -8966 
=  -8967 
=  -8968 
=  -8969 
=  -8970 
=  -8971 
=  -8971 
=  -8972 
=  -8973 

-  -8974 
=  -8975 
=  -8976 
=  -8977 
=  -8978 
=  -8979 
=  -8980 
=  -8981 


1 ockPortBi tsWi ndowResi zed  Err 

= 

-8982 

1 ockPortBi tsWi ndowCl i ppedErr 

= 

-8983 

1 ockPortBi tsBadPort Err 

= 

-8984 

1 ockPortBi tsSurfaceLostErr 

= 

-8985 

codecParameterDi al ogConf i rm 

= 

-8986 

codecNeedAccessKeyErr 

= 

-8987 

codecOffscreenFai 1 edErr 

= 

-8988 

codecDropped Frame Err 

= 

-8989 

di rectXObjectAl readyExi sts 

= 

-8990 

lockPortBitsWrongGDeviceErr 

= 

-8991 

codecOffscreenFai 1 edPl easeRetryErr 

= 

-8992 

//  QuickTime  VR  Errors 

notAQTVRMovi eErr 

= 

-30540 

constraint Reached  Err 

= 

-30541 

call NotSupportedByNodeErr 

= 

-30542 

sel ectorNotSupportedByNodeErr 

= 

-30543 

inval idNodelDErr 

= 

-30544 

i nval i dVi ewStateErr 

= 

-30545 

timeNotlnViewErr 

= 

-30546 

property NotSupportedByNodeErr 

= 

-30547 

setti ngNotSupportedByNodeErr 

= 

-30548 

1 i mi tReachedErr 

= 

-30549 

inval i dNodeFormatErr 

= 

-30550 

inval idHotSpotIDErr 

= 

-30551 

noMemoryNodeFai 1 edlni ti al i ze 

= 

-30552 

streami ngNodeNot Ready Err 

= 

-30553 

qtvr Library LoadErr 

= 

-30554 

qtvrUni ni ti al i zed 

= 

-30555 

noRecordOf App 

A  replica  of  the  movi  eTool  boxllni  ni  ti  al  i  zed  error. 
cantCreateSi ngl eForkFi 1 e 

The  file  to  be  created  already  exists, 
component DI 1  Load  Err 

Windows  error  returned  when  a  component  is  loading, 
component DI 1  Entry NotFoundErr 

Windows  error  returned  when  a  component  is  loading, 
qtml DI 1 LoadErr 

Windows  error  returned  when  the  QuickTime  Media  Layer  is  loading, 
qtml Dll  Entry NotFoundErr 

Windows  error  returned  when  the  QuickTime  Media  Layer  is  loading, 
di gi Uni mpErr 

Digitizer  feature  is  unimplemented. 
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qtParamErr 

Bad  input  parameter  (out  of  range,  for  example). 
matrixErr 

Bad  matrix;  the  digitizer  did  nothing. 
notExactMatri xErr 

Warning  of  a  bad  matrix;  the  digitizer  did  its  best. 
noMoreKeyCol orsErr 

All  the  key  indexes  are  in  use. 
notExactSi zeErr 

Can't  digitize  to  the  exact  size  requested. 
badDepthErr 

Can't  digitize  into  the  requested  pixel  depth. 
noDMAErr 

Can't  do  DMA  digitizing;  that  is,  can't  go  to  the  requested  destination. 
badCal 1 OrderErr 

A  status  call  was  made  before  being  set  up  first. 

Discussion 

The  Movie  Toolbox  provides  two  error  values  to  your  application:  the  current  error 
and  the  sticky  error.  The  current  error  is  the  result  code  from  the  last  Movie  Toolbox 
function;  it  is  updated  each  time  your  application  calls  a  Movie  Toolbox  function. 
The  sticky  error  value  contains  the  first  nonzero  result  code  from  any  Movie 
Toolbox  function  that  you  called  after  having  cleared  the  sticky  error  with 
Cl  earMovi  esSti  ckyError  (1-90). 

See  Also 

For  examples  of  retrieving  error  codes,  see  GetMovi  esError  (1-492)  and 
GetMovi  esSti  ckyError  (1-494). 


File  Types  and  Creators 


Identify  the  formats  of  graphics  files  and  the  applications  that  create  them. 


//  File  types 
ft Adobe Premi ereMovi e 
ftAfterDarkModul e 
ftCl i p3Dgraphi c 
ftCri cketChart 
ftCri cketDrawi ng 
ftDesi gnCADDrawi ng 


1  MooV  ’ 
1 ADgm 1 
1 EZ3D1 
’  CGPC  1 
1 CKDT 1 
' DCAD' 
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ftlmageStudi oGraphi c 

=  'RIFF' 

ftKaleidaGraphGraphic 

=  '  QPCT ' 

ftMacFl owChart 

=  ' FLCH ' 

ftMacSpi nDataSet 

=  '  D2BN ' 

ftMovi ePl ayerMovi e 

=  'MooV' 

ftPixel  Paint 

=  'PX01' 

ftSuper3DDrawi ng 

=  '  3DBX ' 

ftSwi vel 3DDrawi ng 

=  ' SMDL' 

ftVersaCADDrawi ng 

=  '2D  ' 

//  Creator  codes 

si gAdobePremi ere 

=  'PrMr' 

si gAfterDark 

=  ' ADrk' 

si gAl dusSuper3D 

=  '  SP3D ' 

si gAutoCAD 

=  'ACAD' 

si gCl i p3D 

=  '  EZ3E ' 

si gCol orMacCheese 

=  '  CMCA' 

si gCri cketDraw 

=  '  CRDW ' 

si gCri cketGraph 

=  '  CGRF ' 

si gDel tagraphPro 

=  ' DGRH ' 

si gDesi gn2 

=  '  DESG ' 

si gDesi gnCAD 

=  '  ASBC ' 

si gDesi gnStudi o 

=  '  MRJN ' 

si g  D i gDarkroom 

=  'DIDR' 

si gDreams 

=  '  PHNX ' 

si gDynaperspecti ve 

=  'PERS' 

si gGeneri cCADD 

=  '  CAD3 ' 

si gGraphMaster 

=  'GRAM' 

si glmageStudi o 

=  '  FSPE ' 

s  i  g  I  n  f  i  n  i  D 

=  'SI~D' 

si  gKal  ei  daGraph 

=  ' QKPT ' 

s  i  g  Ki  d  P  i  x 

=  '  Ki  d  2  ' 

sigLabVIEW 

=  '  LBVW ' 

si gMacDraft 

=  '  MD20 ' 

si gMacDraw 

=  '  MDRW ' 

si  gMacFl  ow 

=  'MCFL' 

si gMacSpi n 

=  '  D2SP ' 

si gMi ni Cad 

=  '  CDP3 ' 

si gModel Shop 

=  '  MDSP ' 

si  gMovi  ePl  ayer 

=  '  TVOD ' 

si gMovi eRecorder 

=  'mrcr' 

si gOasi s 

=  'TAOA' 

sigOBJECTMASTER 

=  'BROW' 

si gOf oto 

=  ' APLS ' 

si gOmni s5 

=  '  Q  2  $  $  ' 

si gOpti x 

=  ' PIXL' 

si gPhotoMac 

=  '  PMAC ' 

si gPi ctu reCompress or 

=  '  ppxi  ' 

si gPICTVi ewer 

=  '  MDTS ' 
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si gPi xel Pai nt 

=  '  P I X  R ' 

si gScreenPl ay 

=  'SPLY' 

si gSmoothi e 

=  'Smoo' 

si gStudi ol 

=  'ST/1' 

si gStudi o32 

=  ' ST32 ' 

si gStudi 08 

=  'ST/8' 

si gSwi vel 3D 

=  '  SWVL ' 

si gVersaCad 

=  '  VCAD ' 

Discussion 

Constant  names  for  creator  codes  are  written  as  s  i  g  followed  by  the  application 
name.  Constant  names  for  file  types  are  written  as  ft  followed  by  the  document 
type. 

See  Also 

For  an  example  of  using  file  type  and  creator  codes,  see 
Graph  i  cs Import  Expo rtlmageFi  1  e  (1-616). 


Graphics  Transfer  Modes 


Determine  how  images  will  be  transferred. 

//  Boolean  modes 

//  src  modes  are  used  with  bitmaps  and  text; 
//  pat  modes  are  used  with  lines  and  shapes 


srcCopy  =  0 

srcOr  =  1 

srcXor  =  2 

srcBic  =  3 

notSrcCopy  =  4 

notSrcOr  =  5 

notSrcXor  =  6 

notSrcBic  =  7 

patCopy  =  8 

patOr  =  9 

patXor  =  10 

patBic  =  11 

notPatCopy  =  12 

notPatOr  =  13 

notPatXor  =  14 

notPatBic  =  15 

//  Text  dimming 

grayi shTextOr  =  49 

//  Highlighting 

hi  1 i te  =50 
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hi  1 i tetransf ermode 

=  50 

//  Arithmetic  modes 

bl  end 

=  32 

addPi  n 

=  33 

addOver 

=  34 

s  u  b  P  i  n 

=  35 

addMax 

=  37 

adMax 

=  37 

subOver 

=  38 

adMi  n 

=  39 

di therCopy 

=  64 

//  Transparent  mode 

transparent 

=  36 

srcCopy,  patCopy 

If  the  source  is  black,  apply  the  foreground  color  to  the  destination;  if  the  source 
is  white,  apply  the  background  color;  otherwise  apply  weighted  portions  of  the 
foreground  and  background  colors. 
srcOr,  patOr 

If  the  source  is  black,  apply  the  foreground  color  to  the  destination;  if  the  source 
is  white,  do  nothing;  otherwise  apply  weighted  portions  of  the  foreground 
color. 

srcXor,  patXor 

If  the  source  is  black,  invert  the  destination  (this  operation  is  undefined  for  a 
colored  destination).  Otherwise,  do  nothing. 
srcBic,  patBic 

If  the  source  is  black,  apply  the  background  color  to  the  destination.  If  the  source 
is  white,  do  nothing.  Otherwise,  apply  weighted  portions  of  the  background 
color. 

notSrcCopy,  notPatCopy 

If  the  source  is  white,  apply  the  foreground  color  to  the  destination;  if  the 
source  is  black,  apply  the  background  color;  otherwise  apply  weighted  portions 
of  the  foreground  and  background  colors. 

notSrcOr,  notPatOr 

If  the  source  is  white,  apply  the  foreground  color  to  the  destination;  if  the 
source  is  black,  do  nothing;  otherwise  apply  weighted  portions  of  the 
foreground  color. 


CON 


Inside  QuickTime:  Constants 


IV-2671 


Constants 


notSrcXor,  notPatXor 

If  the  source  is  white,  invert  the  destination  (this  operation  is  undefined  for  a 
colored  destination  pixel).  Otherwise,  do  nothing. 
notSrcBic,  notPatBic 

If  the  source  is  white,  apply  the  background  color  to  the  destination.  If  the  source 
is  black,  do  nothing.  Otherwise,  apply  weighted  portions  of  the  background 
color. 

grayi shTextOr 

Dim  the  destination.  If  in  color,  replace  it  with  a  blend  of  the  foreground  and 
background;  if  black-and-white,  replace  it  with  dithered  black  and  white.  This 
mode  is  used  primarily  for  text, 
hilite,  hi  1 i tetransfermode 

Replace  the  background  color  with  the  highlight  color, 
bl  end 

Replace  the  destination  with  a  blend  of  the  source  and  destination  colors.  If  the 
destination  is  a  bitmap,  this  is  the  same  as  srcCopy. 

addPi n 

Replace  the  destination  with  the  sum  of  the  source  and  destination,  up  to  a 
maximum  value.  If  the  destination  is  a  bitmap,  this  is  the  same  as  s  rcBi  c. 
addOver 

Replace  the  destination  with  the  sum  of  the  source  and  destination,  but  if  the 
resulting  red,  green,  or  blue  value  exceeds  65536,  then  subtract  65536  from  it.  If 
the  destination  is  a  bitmap,  this  is  the  same  as  srcXor. 
subPi n 

Replace  the  destination  with  the  difference  between  the  source  and  destination, 
but  not  less  than  a  minimum  value.  If  the  destination  is  a  bitmap,  this  is  the 
same  as  srcOr. 

addMax,  adMax 

Compare  the  source  and  destination,  and  replace  the  destination  with  the 
greater  value  of  each  of  the  red,  green,  and  blue  components.  If  the  destination 
is  a  bitmap,  this  is  the  same  as  srcBi  c. 
subOver 

Replace  the  destination  with  the  difference  between  the  source  and  destination, 
but  if  the  resulting  red,  green,  or  blue  value  is  negative,  then  add  65536  to  it.  If 
the  destination  is  a  bitmap,  this  is  the  same  as  srcXor. 
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adMi  n 

Compare  the  source  and  destination,  and  replace  the  destination  with  the  lesser 
value  of  each  of  the  red,  green,  and  blue  components.  If  the  destination  is  a 
bitmap,  this  is  the  same  as  srcOr. 
di therCopy 

Replace  the  destination  with  a  dither  mix  of  the  source  and  destination, 
transparent 

Replace  the  destination  with  the  source  if  the  source  is  not  equal  to  the 
background. 

See  Also 

For  more  information  about  graphics  transfer  modes,  see  Inside  Macintosh:  Imaging 
With  QnickDraiv  (listed  in  the  bibliography). 


Localization  Codes 


Identify  languages,  scripts,  numbering  systems,  calendar  systems,  and 
geographical  regions. 

//  Language  codes: 


1 angAf ri kaans 

=  141 

// 

smRoman  script 

1 angBreton 

=  142 

// 

smRoman  or  smRoman/Cel  ti  c  script 

1 angAI bani an 

=  36 

// 

smRoman  script 

1 angAmhari c 

=  85 

// 

smEthiopic  script 

1 angArabi c 

=  12 

// 

smArabic  script 

1 angArmeni an 

=  51 

// 

smArmenian  script 

1 angAssamese 

=  68 

// 

smBengali  script 

1 angAymara 

=  134 

// 

smRoman  script 

1 angAzerbai janAr 

=  50 

// 

Azerbaijani  in  smArabic  script 

1 angAzerbai j ani 

=  49 

// 

Azerbaijani  in  smCyrillic  script 

1 angBasque 

=  129 

// 

smRoman  script 

1 angBel orussi an 

=  46 

// 

Synonym  for  1 angByel orussi an 

1  angllzbek 

=  47 

// 

smCyrillic  script 

1 angBengal  i 

=  67 

// 

smBengali  script 

1  angBul gari an 

=  44 

// 

smCyrillic  script 

1 angBurmese 

=  77 

// 

smBurmese  script 

1 angByel orussi an 

=  46 

// 

smCyrillic  script 

1 angCatal an 

=  130 

// 

smRoman  script 

1 angChewa 

=  92 

// 

synonym  for  langNyanja 

1 angCroati an 

=  18 

// 

modified  smRoman/Croati an  script 

1 angCzech 

=  38 

// 

smCentral EuroRoman  script 

1 angDani sh 

=  7 

// 

smRoman  script 

1 angDutch 

=  4 

// 

smRoman  script 

1 angDzongkha 

=  137 

// 

(Bhutan)  smTibetan  script 
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1 angEngl i sh 

=  0 

// 

1 angEsperanto 

=  94 

// 

1 angEstoni an 

=  27 

// 

1 angFaroese 

=  30 

// 

1 angFarsi 

=  31 

// 

langFinnish 

=  13 

// 

1  angFl  emi  sh 

=  34 

// 

1 angFrench 

=  1 

// 

1 angGal i ci an 

=  140 

// 

1 angGeorgi an 

=  52 

// 

1 angGerman 

=  2 

// 

1 angGreek 

=  14 

// 

1 angGreekPoly 

=  148 

// 

1 angGreenl andi c 

=  149 

// 

1 angGuarani 

=  133 

// 

1 angGujarati 

=  69 

// 

1 angHebrew 

=  10 

// 

1 angHi ndi 

=  21 

// 

1 angHungari an 

=  26 

// 

1 anglcel andi c 

=  15 

// 

1 anglndonesi an 

=  81 

// 

1 anglnukti tut 

=  143 

// 

langlrish Gaelic 

=  35 

// 

langlrishGaelicScript 

=  146 

// 

1 angltal i an 

=  3 

// 

1 angJapanese 

=  11 

// 

1 angJavaneseRom 

=  138 

// 

1 angKannada 

=  73 

// 

1 angKashmi ri 

=  61 

// 

1 angKazakh 

=  48 

// 

1 angKhmer 

=  78 

// 

1 angKi nyarwanda 

=  90 

// 

1  angKi  rghi  z 

=  54 

// 

1 angKorean 

=  23 

// 

1 angKurdi sh 

=  60 

// 

1 angLao 

=  79 

// 

1 angLati n 

=  131 

// 

1 angLatvi an 

=  28 

// 

1 angLi thuani an 

=  24 

// 

1 angMacedoni an 

=  43 

// 

1 angMal agasy 

=  93 

// 

1 angMal ayal am 

=  72 

// 

1 angMal ayArabi c 

=  84 

// 

1 angMal ayRoman 

=  83 

// 

1 angMal tese 

=  16 

// 

1  angManxGael i c 

=  145 

// 

1 angMarathi 

=  66 

// 

1 angMol davi an 

=  53 

// 

1 angMongol i an 

=  57 

// 

smRoman  script 

smRoman  script 

smCentral EuroRoman  script 

smRoman/Icel andi c  script 

modified  smArabic/Farsi  script 

smRoman  script 

smRoman  script 

smRoman  script 

smRoman  script 

smGeorgian  script 

smRoman  script 

Greek  script  using  smRoman  script 

smGreek  script 

smRoman  script 

smRoman  script 

smGujarati  script 

smHebrew  script 

smDevanagari  script 

smCentral EuroRoman  script 

modified  smRoman/Icel andi c  script 

smRoman  script 

Inuit  using  smEthiopic  script 

smRoman  or  smRoman/Cel ti c  script 

smRoman/Gael i c  script 

smRoman  script 

smJapanese  script 

Javanese  in  smRoman  script 

smKannada  script 

smArabic  script 

smCyrillic  script 

smKhmer  script 

smRoman  script 

smCyrillic  script 

smKorean  script 

smArabic  script 

smLao  script 

smRoman  script 

smCentral EuroRoman  script 

smCentral EuroRoman  script 

smCyrillic  script 

smRoman  script 

smMalayalam  script 

Malay  in  smArabic  script 

Malay  in  smRoman  script 

smRoman  script 

smRoman  or  smRoman/Cel ti c  script 
smDevanagari  script 
smCyrillic  script 
Mongolian  in  smMongolian  script 
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1 angMongol i anCyr 

=  58 

// 

1 angNepal i 

=  64 

// 

1 angNorwegi an 

=  9 

// 

1 angNyan j  a 

=  92 

// 

1 angOriya 

=  71 

// 

1 angOromo 

=  87 

// 

1 angPashto 

=  59 

// 

1 angPersi an 

=  31 

// 

1 angPol i sh 

=  25 

// 

1 angPortuguese 

=  8 

// 

1 angPun jabi 

=  70 

// 

1 angQuechua 

=  132 

// 

1  a ng Romani  an 

=  37 

// 

1 angRuanda 

=  90 

// 

1 angRundi 

=  91 

// 

1 angRussi an 

=  32 

// 

1 angSami 

=  29 

// 

1 angSanskri t 

=  65 

// 

1 angScotti shGael i c 

=  144 

// 

1 angSerbi an 

=  42 

// 

1 angSi mpChi  nese 

=  33 

// 

1 angSi ndhi 

=  62 

// 

1 angSi nhal ese 

=  76 

// 

1 angSi ovak 

=  39 

// 

1 angSi oveni an 

=  40 

// 

1 angSomal i 

=  88 

// 

1 angSpani sh 

=  6 

// 

1 angSundaneseRom 

=  139 

// 

1 angSwahi 1 i 

=  89 

// 

1 angSwedi sh 

=  5 

// 

1 angTagal og 

=  82 

// 

1 angTaji ki 

=  55 

// 

1 angTami 1 

=  74 

// 

1 angTatar 

=  135 

// 

1 angTel ugu 

=  75 

// 

1 angThai 

=  22 

// 

1 angT i betan 

=  63 

// 

1 angT i gri nya 

=  86 

// 

1 angTongan 

=  147 

// 

1 angT  radChi nese 

=  19 

// 

1 angTurki sh 

=  17 

// 

1 angTurkmen 

=  56 

// 

1 angUi ghur 

=  136 

// 

1  angllkrai  ni  an 

=  45 

// 

1  angllrdu 

=  20 

// 

1 angVi etnamese 

=  80 

// 

1 angWel sh 

=  128 

// 

1 angY i ddi sh 

=  41 

// 

1  angllnspeci  f  i  ed 

=  32767 

Mongolian  in  smCyrillic  script 

smDevanagari  script 

smRoman  script 

smRoman  script 

smOriya  script 

smEthiopic  script 

smArabic  script 

Synonym  for  langFarsi 

smCentral EuroRoman  script 

smRoman  script 

smGurmukhi  script 

smRoman  script 

modified  smRoman/Romani an  script 
synonym  for  1 angKinyarwanda 
smRoman  script 
smCyrillic  script 

language  of  the  Sami  in  Scandanavia 

smDevanagari  script 

smRoman  or  smRoman/Cel ti c  script 

smCyrillic  script 

Mandarin  in  smSimpChi nese  script 

smArabic  script 

smSinhalese  script 

smCentral EuroRoman  script 

modified  smRoman/Croati an  script 

smRoman  script 

smRoman  script 

Sundanese  in  smRoman  script 

smRoman  script 

smRoman  script 

smRoman  script 

smCyrillic  script 

smTamil  script 

smCyrillic  script 

smTelugu  script 

smThai  script 

smTibetan  script 

smEthiopic  script 

smRoman  script 

Mandarin  in  smTradChi nese  script 
modified  smRoman/Turki sh  script 
smCyrillic  script 
smArabic  script 

modified  smCyri 1 1 i c/Ukraini an  script 
smArabic  script 
smVietnamese  script 
modified  smRoman/Cel ti c  script 
smHebrew  script 


CON 


Inside  QuickTime:  Constants 


IV-2675 


Constants 


//  Script  codes 

smArabi c 

=  4 

smArmeni an 

=  24 

smBengal i 

=  13 

smBurmese 

=  19 

smCentral EuroRoman 

=  29 

smCy ri 1 1 i c 

=  7 

smDevanagari 

=  9 

smEthi opi c 

=  28 

smExtArabi c 

=  31 

// 

extended  Arabic 

smGeez 

=  28 

// 

Synonym  for  smEthi opi c 

smGeorgi an 

=  23 

smGreek 

=  6 

smGujarati 

=  11 

smGurmukhi 

=  10 

smHebrew 

=  5 

smJapanese 

=  1 

smKannada 

=  16 

// 

Kannada/Kanarese 

smKhmer 

=  20 

// 

Khmer/Cambodi an 

smKorean 

=  3 

smLao 

=  22 

smMal ayal am 

=  17 

smMongol i an 

=  27 

smOriya 

=  12 

smRoman 

=  0 

smRSymbol 

=  8 

// 

Right-left  symbol 

smSi mpChi nese 

=  25 

// 

Simplified  Chinese 

smSi nhal ese 

=  18 

smTami 1 

=  14 

smTel ugu 

=  15 

smThai 

=  21 

smT i betan 

=  26 

smT  radChi nese 

=  2 

// 

Traditional  Chinese 

smllni  codeScri  pt 

=  0x7E 

// 

Uni  code 

smllni  nterp 

=  32 

// 

Uninterpreted  symbols 

smVi etnamese 

=  30 

//  Calendar  codes 

cal Gregori an 

=  0 

cal Arabi cCi vi 1 

=  1 

calArabicLunar 

=  2 

cal  Japanese 

-  3 

cal Jewi sh 

=  4 

cal Copti c 

=  5 

cal Persi an 

=  6 

//  Integer  format  codes 
intWestern  =  0 
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i  ntArabi c 

= 

1 

i  ntRoman 

= 

2 

i nt Japanese 

= 

3 

i ntEuropean 

= 

4 

//  Region  codes 

verAf ri kaans 

= 

102 

verArabi c 

= 

16 

verArmeni an 

= 

84 

verAustral i a 

= 

15 

verAustri a 

= 

92 

verBengal  i 

= 

60 

verBhutan 

= 

83 

verBrazi 1 

= 

71 

verBreton 

= 

77 

verBri tai n 

= 

2 

verBul gari a 

= 

72 

verByel oRussi an 

= 

61 

verCatal oni a 

= 

73 

verChi na 

= 

52 

verCroati a 

= 

68 

verCyprus 

= 

23 

verCzech 

= 

56 

verDenmark 

= 

9 

verEngCanada 

= 

82 

verEsperanto 

= 

103 

verEstoni a 

= 

44 

verFarEastGeneri  c 

= 

58 

verFaroelsl 

= 

47 

verFi nl and 

= 

17 

verFl  emi  sh 

= 

6 

verFrance 

= 

1 

verFrBel gi um 

= 

98 

verFrCanada 

= 

11 

verFrenchUniversal 

= 

91 

verFrSwi ss 

= 

18 

verGeorgi an 

= 

85 

verGermany 

= 

3 

verGreece 

= 

20 

verGreecePoly 

= 

40 

verGreenl and 

= 

107 

verGrSwi ss 

= 

19 

verGujarati 

= 

94 

verHungary 

= 

43 

verlcel and 

= 

21 

verlndi a  H i ndi 

= 

33 

verlndi aUrdu 

= 

96 

verlnternati onal 

= 

37 

verl ran 

= 

48 
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verlrel and 

= 

50 

verlrishGaelicScript 

= 

81 

verlsrael 

= 

13 

verltat i anSwi ss 

= 

36 

verltaly 

= 

4 

ver Japan 

= 

14 

verKorea 

= 

51 

verLatvi a 

= 

45 

verLi thuani a 

= 

41 

verMacedoni an 

= 

67 

verMagyar 

= 

59 

verMal ta 

= 

22 

verManxGael i c 

= 

76 

verMarathi 

= 

104 

verMul ti 1 i ngual 

= 

74 

verNepal 

= 

106 

verNetherl ands 

= 

5 

verNorway 

= 

12 

verNunavut 

= 

78 

verNynorsk 

= 

101 

verPakl stanUrdu 

= 

34 

verPol and 

= 

42 

verPortugal 

= 

10 

verPunjabi 

= 

95 

verRomani a 

= 

39 

verRussI a 

= 

49 

verSami 

= 

46 

verScotti shGael i c 

= 

75 

verScri ptGeneri  c 

= 

55 

verSerbi an 

= 

65 

verSi ngapore 

= 

100 

verSl ovak 

= 

57 

verSi ovenl an 

= 

66 

verSpai n 

= 

8 

verSpLati nAmeri ca 

= 

86 

verSweden 

= 

7 

verTaiwan 

= 

53 

verThai 1  and 

= 

54 

verT i betan 

= 

105 

verTonga 

= 

88 

verTurkey 

= 

24 

verTurki shModl f 1 ed 

= 

35 

verllkral  ne 

= 

62 

verUS 

= 

0 

verUzbek 

= 

99 

verVi etnam 

= 

97 

verWel sh 

= 

79 
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1 anglrl shGael i c,  verlreland 

Irish  Gaelic  for  Ireland  (without  dot  above). 

1 anglri shGael i cScri pt,  verlri shGael i cScri pt 
Irish  Gaelic  for  Ireland  (using  dot  above). 

1 angSimpChi nese ,  smSimpChi nese ,  verChina 
Chinese  using  simplified  characters. 

1 angTradChi nese ,  smTradChi nese ,  verTaiwan 
Chinese  using  traditional  characters. 
smCentral EuroRoman 

Script  for  Czech,  Slovak,  Polish,  Hungarian,  and  the  Baltic  languages. 
smRSymbol 

Right-left  symbol  for  bidirectional  scripts  (such  as  Arabic  and  Hebrew). 
verFarEastGeneri c 

Generic  Far  East  system  (no  language  or  script). 
verGreece 

Monotonic  modern  Greek. 
verGreecePoly 

Polytonic  ancient  Greek, 
verlnternati onal 

English  for  international  use. 
verMul ti 1 i ngual 

No  language  or  script. 
verScri ptGeneri c 

Generic  script  system  (no  language  or  script). 
verSpai n 

Spanish  for  Spain. 
verSpLati nAmeri  ca 

Spanish  for  Latin  America. 

See  Also 

For  more  information  about  localization  codes,  see  Inside  Macintosh:  Text  (listed  in 
the  bibliography).  For  general  information  about  localization,  see  Guide  to 
Macintosh  Software  Localization  (Addison-Wesley  1992,  ISBN  0-201-60856-1). 
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Movie  Controller  Actions 


Specify  commands  to  a  movie  controller  component. 


//  Action  Value  Parameter,  if  any 

mcActi onActi vate  =3  //no  parameter 

mcActi  onAdj ustCursor  =  65  //  pointer  to  EventRecord 

(WindowPtr  is  in  message  parameter) 
mcActi onAutoPl ay  =  83  //  Fixed,  play  rate 

mcActi onBadgeCl i ck  =  44  //  pointer  to  Boolean. 

(Set  to  false  to  ignore  click.) 

mcActi  onCl  i  ckAndHol  dPoi  nt  =  67  //  point  (local  coordinates). 

return  true  if  point  has  click  &  hold  action 
(e.g.  VR  object  movie  autorotate  spot) 


mcActi onControllerSizeChanged 
mcActi onCustomButtonClick 
mcActi on  Deactivate 
mcActi onDoScri pt 
mcActi onDraw 

mcActi on  Eva  1 uateExpressi on 

mcActi onExecuteAl 1  Ac tionsForQT Event 

mcActi onExecuteOneActi onForQTEvent 

mcActi on  Fetch  Parameter As 

mcActi onForceTi meTabl eUpdate 

mcActi onGetChapterTime 

mcActi onGetCursorBylD 

mcActi on GetCursorSetting Enabled 

mcActi on GetDrag Enabled 

mcActi on Get External  Movie 

mcActi onGetFl ags 

mcActi onGetlndChapter 

mcActi onGetKeysEnabl ed 

mcActi on Get  Loop i ng 

mcActi on Get  Loop Is  Pa  1 i ndrome 

mcActi on Get Next URL 

mcActi on Get PI  ay  Every  Frame 

mcActi onGetPl ay Rate 

mcActi onGetPlaySelection 

mcActi onGetSelectionBegin 

mcActi onGetSelectionDuration 

mcActi onGetTi meSl i derRect 

mcActi onGetUseBadge 

mcActi onGetVol ume 

mcActionGoToTime 

mcActi onldl e 

mcActi onKey 

mcActi onLinkToURL 

mcActi onMo use Down 

mcActi onMovieChanged 


=  26  //  no  parameter 

=  60  //  pointer  to  EventRecord 

=4  //no  parameter 

=  78  //  QTDoScri ptPtr 

=2  //  WindowPtr 

=  73  //  QTEval uateExpressi onPtr 

=  63  //  Resol vedQTEventSpecPtr 

=  64  //  Resol vedQTEventSpecPtr 

=  74  //  QTFetchParameterAsPtr 

=  61  //  no  parametereter 

=  71  //  QTGetChapterTi mePtr 

=  75  //  QTGetCursorBy IDPtr 

=  56  //  pointer  to  Boolean 

=  51  //  pointer  to  Boolean 

=  70  //  QTGetExternal Movi ePtr 

=  39  //  pointer  to  long  (see  below) 

=  80  //  QTChapterlnfoPtr 

=  33  //  pointer  to  Boolean 

=  22  //  pointer  to  Boolean 

=  24  //  pointer  to  Boolean 

=  76  //  Handle  to  URL 

=  41  //  pointer  to  Boolean 

=  42  //  pointer  to  Fixed 

=  35  //  pointer  to  Boolean 

=  53  //  TimeRecord 

=  54  //  TimeRecord 

=  49  //  pointer  to  Rect 

=  37  //  pointer  to  Boolean 

=  15  //  pointer  to  short  integer 

=  12  //  TimeRecord 

=  1  //no  parameter 

=6  //  pointer  to  EventRecord 

=  59  //  Handle  to  URL 

=5  //  pointer  to  EventRecord 

=  77 


IV-2680 


Inside  QuickTime:  Constants 


mcActi onMovi eCl i ck 


=  45  //  pointer  to  event  record. 

(Change  "what"  to  nullEvt  to  kill  click.) 


mcActi onMovi eEdi ted 

= 

50 

// 

no  parameter 

mcActi onPerf ormActi onLi st 

= 

72 

// 

QTAtomSpecPtr 

mcActi onPl ay 

= 

8 

// 

Fixed  play  rate 

mcActi on P re rol 1  And  PI  ay 

= 

55 

// 

Fixed  play  rate 

mcActi onRestartAtTime 

= 

79 

// 

QTResartAtT i mePtr 

mcActi onResume 

= 

47 

// 

no  parameter 

mcActi onSetCol orTabl  e 

= 

58 

// 

CTabHandl e 

mcActi onSetControl 1 erKeysEnabl  ed 

= 

48 

// 

Bool ean 

mcActi onSetControl 1 erTi me  Li  mi ts 

= 

62 

// 

pointer  to  2  time  values 

min/max.  Do  not  send  this  message  to  i 

controller,  use  internally  only 

mcActi onSetCursorSetti ngEnabl ed 

= 

57 

// 

Bool ean 

mcActi onSetDragEnabl ed 

= 

52 

// 

Bool ean 

mcActi onSetFl ags 

= 

38 

// 

pointer  to  long  (see  below 

mcActi onSetGrowBoxBounds 

= 

25 

// 

Rect 

mcActi onSetKeysEnabl ed 

= 

32 

// 

Bool ean 

mcActi onSetLoopi ng 

= 

21 

// 

Bool ean 

mcActi onSetLoopIsPal i ndrome 

= 

23 

// 

Bool ean 

mcActi onSetPl ayEveryFrame 

= 

40 

// 

Bool ean 

mcActi onSetPl aySel ecti on 

= 

34 

// 

Bool ean 

mcActi onSetSel ecti onBegi n 

= 

29 

// 

TimeRecord 

mcActi onSetSel ecti onDurati on 

= 

30 

// 

TimeRecord; 

Acti on 

only  taken  on  set-duration 

mcActi onSetUseBadge 

= 

36 

// 

Bool ean 

mcActi  onSetVol  lime 

= 

14 

// 

short  integer 

mcActi onShowBal 1 oon 

= 

43 

// 

pointer  to  Boolean. 

(set  to  false  to  stop  balloon 

mcActi onShowMessageStri ng 

= 

68 

// 

Stri ngPtr 

mcActi onShowStatusStri ng 

= 

69 

// 

QTStatusStri  ngPtr 

mcActi onStep 

= 

18 

// 

number  of  steps  (short) 

mcActi onSuspend 

= 

46 

// 

no  parameter 

mcActi onUseTrackForTi meTabl e 

= 

66 

// 

pointer  to  (long  trackID; 

Boolean  uselt}.  Do 

not  : 

send 

this  message  to  controller 

mcActionGetFlags  Constants 

mcFlagSuppressMovieFrame 

If  this  flag  is  set  to  1,  the  controller  does  not  display  a  frame  around  the  movie. 
By  default,  this  flag  is  set  to  0. 
mcFlagSuppressStepButtons 

If  this  flag  is  set  to  1,  the  controller  does  not  display  the  step  buttons.  By  default, 
this  flag  is  set  to  0. 
mcFlagSuppressSpeakerButton 

If  this  flag  is  set  to  1,  the  controller  does  not  display  the  speaker  button.  By 
default,  this  flag  is  set  to  0. 
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mcFlagslIseWindowPalette 

If  this  flag  is  set  to  1,  the  movie  controller  does  not  manage  the  window  palette. 
This  ensures  that  a  movie's  colors  are  reproduced  as  accurately  as  possible.  This 
flag  is  particularly  useful  for  movies  with  custom  color  tables.  By  default,  this 
flag  is  set  to  0. 

mcActionSetFlags  Constants 

mcFlagSuppressMovieFrame 

If  this  flag  is  set  to  1,  the  controller  does  not  display  a  frame  around  the  movie. 
By  default,  this  flag  is  set  to  0. 

mcFlagSuppressStepButtons 

If  this  flag  is  set  to  1,  the  controller  does  not  display  the  step  buttons.  By  default, 
this  flag  is  set  to  0. 

mcFlagSuppressSpeakerButton 

If  this  flag  is  set  to  1,  the  controller  does  not  display  the  speaker  button.  By 
default,  this  flag  is  set  to  0. 

See  Also 

See  MCDoAction  (11-801). 


Music  Controllers 


Specify  music  controllers  for  the  QuickTime  Music  Architecture. 


kControl 1 erModul ati onWheel  =  1 

kControl 1 erBreath  =  2 

kControl 1 erFoot  =  4 

kControl 1 erPortamentoTi me  =  5 

kControl 1 erVol ume  =  7 

kControll erBal ance  =  8 

kControl 1 erPan  =  10 

kControll erExpressi on  =  11 

kControl 1 erLeverl  =  16 

kControl 1 erLever2  =  17 

kControll erLever3  =  18 

kControl 1 erLever4  =  19 

kControl 1 erLever5  =  80 

kControl 1 erLever6  =  81 

kControl 1 erLever7  =  82 

kControl 1 erLever8  =  83 

kControl 1 erPi tchBend  =  32 

kControl 1 erAfterTouch  =  33 

kControll erSustai n  =  64 

kControl 1 erSostenuto  =  66 
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kControl lerSoft Pedal 

=  67 

kControl 1 erReverb 

=  91 

kControl 1 erT  remol o 

=  92 

kControl 1 erChorus 

=  93 

kControl 1 erCel este 

=  94 

kControl 1 erPhaser 

=  95 

kControl 1 er Ed i t Part 

=  113 

kControl lerMasterTune 

=  114 

kControl 1 erModul ati onWheel 

Controls  the  modulation  wheel.  A  modulation  wheel  adds  a  periodic  change  to 
the  volume  or  pitch  of  a  sounding  tone,  depending  on  the  modulation  depth 
knobs. 

kControl 1 erBreath 
Controls  breath. 
kControl 1 erFoot 

Controls  the  foot  pedal. 
kControl 1 er Port amentoTi me 

Adjusts  the  slur  between  notes.  Set  the  time  to  0  to  turn  off  portamento;  there  is 
no  separate  control  to  turn  portamento  on  and  off. 
kControl 1 erVol ume 
Controls  volume. 
kControl 1 erBal ance 

Controls  balance  between  channels. 
kControl 1 erPan 

Controls  balance  on  the  QuickTime  music  synthesizer  and  some  others.  Values 
are  256  to  512,  corresponding  to  left  to  right. 
kControl 1 erExpressi on 

Provides  a  second  volume  control. 
kControl 1 erLeverl 

The  kControl  1  erLeverl  through  kControl  1  erLever8  constants  identify 
general-purpose  controllers. 

kControl lerPitchBend 

Bends  the  pitch.  Pitch  bend  is  specified  in  positive  and  negative  semitones,  with 
7  bits  per  fraction. 
kControl 1 erAfterTouch 

Controls  channel  pressure. 
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kControl 1 erSustai n 

Controls  the  sustain  effect.  The  value  is  a  Bool  e an;  positive  for  on,  0  or  negative 
for  off. 

kControl lerSostenuto 
Controls  sostenuto. 
kControl lerSoft Pedal 

Controls  the  soft  pedal. 
kControl 1 erReverb 

Controls  reverberation. 
kControl 1 erT  remol o 
Controls  tremolo. 
kControl 1 erChorus 

Controls  the  amount  of  signal  to  feed  to  the  chorus  special  effect  unit. 
kControl 1 erCel este 

Controls  the  amount  of  signal  to  feed  to  the  celeste  special  effect  unit. 
kControl 1 erPhaser 

Controls  the  amount  of  signal  to  feed  to  the  phaser  special  effect  unit. 
kControl lerEditPart 

Sets  the  part  number  for  which  editing  is  occurring,  for  synthesizers  that  can 
edit  only  one  part. 
kControl lerMasterTune 

Offsets  the  pitch  of  the  entire  synthesizer. 

Discussion 

The  controller  numbers  used  by  QuickTime  are  mostly  identical  to  the  standard 
MIDI  controller  numbers.  These  are  signed  8.8  values.  The  full  range,  therefore,  is 
-128.00  to  127+127/128  (or  0x8000  to  0x7FFF).  All  controls  default  to  zero  except  for 
volume  and  pan. 

Pitch  bend  is  specified  in  fractional  semitones,  which  eliminates  the  restrictions  of  a 
pitch  bend  range.  You  can  bend  as  far  as  you  want,  any  time  you  want. 

The  last  16  controllers  (113  through  128)  are  global  controllers.  Global  controllers 
respond  when  the  part  number  is  given  as  0,  indicating  the  entire  synthesizer. 

See  Also 

See  Musi cGetPartControl  1  er  (II — 1001). 
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Parameter  Behaviors 


Specify  the  user  interface  behavior  of  a  parameter. 


kParameterltemEdi tText 
kParameterltemEdi tLong 
kParameterltemEdi t  F i xed 
kParameterltemEdi tDoubl e 
kParameterltemPopUp 
kParameterltemRadi oCl uster 
kParameterltemCheckBox 
kParameterltemControl 
kParameterltemLi ne 
kParameterltemCol orPi cker 
kParameterltemGroupDi vider 
kParameterltemStati cText 
kParameterltemDraglmage 


=  'edit' 
=  ' 1 ong ' 
=  'fixd' 
=  'doub' 
=  'popu' 
=  ' radi  ' 
=  'chex' 
=  ' cntl  ' 
=  'line' 
=  'pick' 
=  '  d  i  v  i  ' 
=  'stat' 
=  'imag' 


kParameterltemEdi tText 
Edit  box  for  text. 
kParameterltemEdi tLong 

Edit  box  for  long  numbers. 


kParameterltemEdi t Fixed 

Edit  box  for  fixed  point  numbers. 


kParameterltemEdi tDoubl e 

Edit  box  for  double  numbers. 


kParameterltemPopUp 

Pop-up  menu  value  for  enumerated  types. 
kParameterltemRadi oCl uster 

Radio  button  cluster  for  enumerated  types. 
kParameterltemCheckBox 

Checkbox  for  Bool  ean  types. 
kParameterltemControl 

Item  controlled  by  a  standard  control  of  some  type. 
kParameterltemLi ne 
Line  user  item. 


kParameterltemCol orPi cker 
Color  swatch  &  picker. 
kParameterltemGroupDi vider 

Start  of  a  new  group  of  items. 
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kParameterltemStati cText 

Display  "parameter  name"  as  static  text. 
kParameterltemDraglmage 

Allow  image  display,  along  with  drag  and  drop. 

See  Also 

See  ParameterDataBehavior  (IV-2328). 


Pixel  Formats 


Defines  pixel  arrangements  in  images. 


kl6LE555Pixel Format 

= 

' L555 1 

// 

16  bi  t 

LE  RGB  555  (PC) 

kl6LE5551Pi xel Format 

= 

'5551' 

// 

16  bi  t 

LE  RGB  5551 

kl6BE565Pixel Format 

= 

' B565 ' 

// 

16  bi  t 

BE  RGB  565 

kl6LE565Pixel Format 

= 

' L565 ' 

// 

16  bi  t 

LE  RGB  565 

k24BGRPi xel Format 

= 

' 24BG ' 

// 

24  bit 

BGR 

k32BGRAPixel Format 

= 

' BGRA ' 

// 

32  bit 

BGRA  (Matrox) 

k32ABGRPixel Format 

= 

' ABGR' 

// 

32  bit 

ABGR 

k32RGBAPixel Format 

= 

' RGBA ' 

// 

32  bit 

RGBA 

kYUVSPi xel Format 

= 

'yuvs ' 

// 

YUV  4:2 

:2  byte  ordering 

16- 

kYUVUPi xel Format 

= 

'yuvu' 

// 

YUV  4:2 

:2  byte  ordering 

16- 

kYVU9Pi xel Format 

= 

'  YVU9 ' 

// 

YVU9  Planar  9 

kYUV411Pixel Format 

= 

' Y411 ' 

// 

YUV  4:1 

:1  Interleaved  16 

kYVYU422Pi xel Format 

= 

'  YVYU ' 

// 

YVYU  4: 

2:2  byte  ordering 

16 

kUYVY422Pi xel Format 

= 

'  UYVY  ' 

// 

UYVY  4: 

2:2  byte  ordering 

16 

kYUV211Pixel Format 

= 

'  Y211 ' 

// 

YUV  2:1 

:1  Packed  8 

See  Also 

See  the  Pi  xMap  (IV-2332)  structure. 


QTMA  Events 


Designate  event  subtypes  for  the  QuickTime  Music  Architecture. 


kGeneral EventNoteRequest  =  1 

kGeneral EventPartKey  =  4 

kGeneral EventTuneDi fference  =  5 

kGeneral EventAtomi clnstrument  =  6 

kGeneral EventKnob  =  7 

kGeneral EventMIDIChannel  =  8 

kGeneral EventPartChange  =  9 

kGeneral EventNoOp  =  10 

kGeneral EventUsedNotes  =  11 
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kGeneral EventPartMix  =  12 

kMarkerEventEnd  =  0 

kMarkerEventBeat  =  1 

kMarkerEventTempo  =  2 


kGeneral EventNoteRequest 

Encapsulates  a  NoteRequest  (IV-2323)  structure. 
kGeneral EventTuneDi fference 

Contains  a  standard  sequence,  with  end  marker,  for  the  tune  difference  of  a 
sequence  piece. 

kGeneral EventAtomi clnstrument 

Encapsulates  an  Atomi  clnstrument  record. 
kGeneral EventKnob 

Pairs  of  knoblD/knobVal  ue  values;  smallest  event  is  4  long  integers. 
kGeneral EventMIDIChannel 

Used  in  tune  header;  one  long  word  identifies  the  MIDI  channel  it  originally 
came  from. 

kGeneral EventPartChange 

Used  in  tune  sequence;  one  long  word  identifies  the  tune  part  that  can  now  take 
over  this  part's  note  channel,  similar  to  a  program  change. 
kGeneral EventNoOp 

Guaranteed  to  do  nothing  and  be  ignored. 
kGeneral EventUsedNotes 

Four  long  words  specifying  which  MIDI  notes  are  actually  used;  formatted 
0..127  MSB  to  LSB. 
kGeneral EventPartMix 

Three  long  words:  Fixed  volume,  long  balance,  long  flags. 
kMarkerEventEnd 

Value  of  0  means  stop,  value  other  than  0  means  ignore. 
kMarkerEventBeat 

Value  0  is  a  single  beat;  anything  else  is  65536ths-of-a-beat  (quarter  note). 
kMarkerEventTempo 

Value  same  as  beat  marker,  but  indicates  that  a  tempo  event  should  be 
computed  (based  on  where  the  next  beat  or  tempo  marker  is)  and  emitted  upon 
export. 

Version  Notes 

Events  of  type  kGeneral  EventTuneDi  fference,  kGeneral  EventPartChange,  and 
kGeneral  EventNoOp  halt  QuickTime  2.0  music  playing. 
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See  Also 

See  the  TuneSetHeader  (III— 1967)  function. 


QTVR  Cursors 

Define  cursors  that  may  appear  in  QuickTime  Virtual  Reality. 

-17000  Pointer  interface  cursor. 

-17483  Mouse  down,  cursor  top  right  of  joystick  center. 

-17484  Mouse  down,  cursor  top  left  of  joystick  center. 

-17485  Mouse  down,  cursor  top  of  joystick  center. 

-17486  Mouse  down,  cursor  bottom  right  of  joystick  center. 

-17487  Mouse  down,  cursor  bottom  left  of  joystick  center. 

-17488  Mouse  down,  cursor  bottom  of  joystick  center. 

-17489  Mouse  down,  cursor  right  of  joystick  center. 

-17490  Mouse  down,  cursor  left  of  joystick  center. 

-17491  Mouse  down,  joystick  center  cursor. 

-17492  Mouse  up,  cursor  top  right  of  joystick  center. 

-17493  Mouse  up,  cursor  top  left  of  joystick  center. 

-17494  Mouse  up,  cursor  top  of  joystick  center. 

-17495  Mouse  up,  cursor  bottom  right  of  joystick  center. 

-17496  Mouse  up,  cursor  bottom  left  of  joystick  center. 

-17497  Mouse  up,  cursor  bottom  of  joystick  center. 

-17498  Mouse  up,  cursor  right  of  joystick  center. 

-17499  Mouse  up,  cursor  left  of  joystick  center. 

-17500  Mouse  up,  joystick  center  cursor. 

-17961  Inside  right  border  spinning  cursor,  both  mouse  up  and  mouse  down, 
when  tilt  angle  is  between  -90'  and  -78';  object  cannot  turn  right. 
-17962  Inside  left  border  spinning  cursor,  both  mouse  up  and  mouse  down, 
when  tilt  angle  is  between  -90'  and  -78';  object  cannot  turn  left. 
-17963  Inside  right  border  spinning  cursor,  both  mouse  up  and  mouse  down, 
when  tilt  angle  is  between  -78'  and  -56';  object  cannot  turn  right. 
-17964  Inside  left  border  spinning  cursor,  both  mouse  up  and  mouse  down, 
when  tilt  angle  is  between  -78‘  and  -56';  object  cannot  turn  left. 
-17965  Inside  right  border  spinning  cursor,  both  mouse  up  and  mouse  down, 
when  tilt  angle  is  between  -56'  and  -34';  object  cannot  turn  right. 
-17966  Inside  left  border  spinning  cursor,  both  mouse  up  and  mouse  down, 
when  tilt  angle  is  between  -56‘  and  -34';  object  cannot  turn  left. 
-17967  Inside  right  border  spinning  cursor,  both  mouse  up  and  mouse  down, 
when  tilt  angle  is  between  -34'  and  -11';  object  cannot  turn  right. 
-17968  Inside  left  border  spinning  cursor,  both  mouse  up  and  mouse  down, 
when  tilt  angle  is  between  -34'  and  -11';  object  cannot  turn  left. 
-17969  Inside  right  border  spinning  cursor,  both  mouse  up  and  mouse  down, 
when  tilt  angle  is  between  -11'  and  11';  object  cannot  turn  right. 
-17970  Inside  left  border  spinning  cursor,  both  mouse  up  and  mouse  down, 
when  tilt  angle  is  between  -11'  and  11';  object  cannot  turn  left. 
-17971  Inside  right  border  spinning  cursor,  both  mouse  up  and  mouse  down. 
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when  tilt  angle  is  between  11'  and  34';  object  cannot  turn  right. 

-17972  Inside  left  border  spinning  cursor,  both  mouse  up  and  mouse  down, 
when  tilt  angle  is  between  11'  and  34';  object  cannot  turn  left. 

-17973  Inside  right  border  spinning  cursor,  both  mouse  up  and  mouse  down, 
when  tilt  angle  is  between  34'  and  56';  object  cannot  turn  right. 

-17974  Inside  left  border  spinning  cursor,  both  mouse  up  and  mouse  down, 
when  tilt  angle  is  between  34'  and  56';  object  cannot  turn  left. 

-17975  Inside  right  border  spinning  cursor,  both  mouse  up  and  mouse  down, 
when  tilt  angle  is  between  56'  and  78';  object  cannot  turn  right. 

-17976  Inside  left  border  spinning  cursor,  both  mouse  up  and  mouse  down, 
when  tilt  angle  is  between  56'  and  78';  object  cannot  turn  left. 

-17977  Inside  right  border  spinning  cursor,  both  mouse  up  and  mouse  down, 
when  tilt  angle  is  between  78'  and  90';  object  cannot  turn  right. 

-17978  Inside  left  border  spinning  cursor,  both  mouse  up  and  mouse  down, 
when  tilt  angle  is  between  78'  and  90';  object  cannot  turn  left. 

-17979  Inside  bottom  border  spinning  cursor,  both  mouse  up  and  mouse  down; 
object  cannot  turn  down. 

-17980  Inside  top  border  spinning  cursor,  both  mouse  up  and  mouse  down; 
object  cannot  turn  up. 


-17981 

Inside  right  border 
when  tilt  angle  is 

spinning  cursor, 
between  -90°  and 

both 

-78' 

mouse 

up 

and 

mouse 

down , 

-17982 

Inside  left  border 
when  tilt  angle  is 

spinning  cursor, 
between  -90°  and 

both 

-78' 

mouse 

up 

and 

mouse 

down , 

-17983 

Inside  right  border 
when  tilt  angle  is 

spinning  cursor, 
between  -78°  and 

both 

-56' 

mouse 

up 

and 

mouse 

down , 

-17984 

Inside  left  border 
when  tilt  angle  is 

spinning  cursor, 
between  -78°  and 

both 

-56' 

mouse 

up 

and 

mouse 

down , 

-17985 

Inside  right  border 
when  tilt  angle  is 

spinning  cursor, 
between  -56°  and 

both 

-34' 

mouse 

up 

and 

mouse 

down , 

-17986 

Inside  left  border 
when  tilt  angle  is 

spinning  cursor, 
between  -56°  and 

both 

-34' 

mouse 

up 

and 

mouse 

down , 

-17987 

Inside  right  border 
when  tilt  angle  is 

spinning  cursor, 
between  -34°  and 

both 

-11' 

mouse 

up 

and 

mouse 

down , 

-17988 

Inside  left  border 
when  tilt  angle  is 

spinning  cursor, 
between  -34°  and 

both 

-11' 

mouse 

up 

and 

mouse 

down , 

-17989 

Inside  right  border 
when  tilt  angle  is 

spinning  cursor, 
between  -11°  and 

both 
11' . 

mouse 

up 

and 

mouse 

down , 

-17990 

Inside  left  border 
when  tilt  angle  is 

spinning  cursor, 
between  -11°  and 

both 
11' . 

mouse 

up 

and 

mouse 

down , 

-17991 

Inside  right  border 
when  tilt  angle  is 

spinning  cursor, 
between  11°  and 

both 
34'  . 

mouse 

up 

and 

mouse 

down , 

-17992 

Inside  left  border 
when  tilt  angle  is 

spinning  cursor, 
between  11°  and 

both 
34'  . 

mouse 

up 

and 

mouse 

down , 

-17993 

Inside  right  border 
when  tilt  angle  is 

spinning  cursor, 
between  34°  and 

both 
56' . 

mouse 

up 

and 

mouse 

down , 

-17994 

Inside  left  border 
when  tilt  angle  is 

spinning  cursor, 
between  34°  and 

both 
56' . 

mouse 

up 

and 

mouse 

down , 

-17995 

Inside  right  border 
when  tilt  angle  is 

spinning  cursor, 
between  56°  and 

both 
78' . 

mouse 

up 

and 

mouse 

down , 
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-17996  Inside  left  border  spinning  cursor,  both  mouse  up  and  mouse  down, 
when  tilt  angle  is  between  56“  and  78“ . 

-17997  Inside  right  border  spinning  cursor,  both  mouse  up  and  mouse  down, 
when  tilt  angle  is  between  78“  and  90‘. 

-17998  Inside  left  border  spinning  cursor,  both  mouse  up  and  mouse  down, 
when  tilt  angle  is  between  78“  and  90‘. 

-17999  Inside  bottom  border  spinning  cursor,  both  mouse  up  and  mouse  down. 
-18000  Inside  top  border  spinning  cursor,  both  mouse  up  and  mouse  down. 

-18499  Mouse-down  cursor  when  over  the  central  part  of  the  movie. 

-18500  Mouse-up  cursor  when  over  the  central  part  of  the  movie. 

-18975  Pan  up-right  cursor,  with  both  panning  up  and  panning  right 

constrai ned . 

-18976  Pan  up-right  cursor,  with  panning  right  constrained. 

-18977  Pan  up-right  cursor,  with  panning  up  constrained. 

-18978  Pan  up-right  cursor. 

-18979  Pan  up-left  cursor,  with  both  panning  up  and  panning  left 
constrai ned . 

-18980  Pan  up-left  cursor,  with  panning  left  constrained. 

-18981  Pan  up-left  cursor,  with  panning  up  constrained. 

-18982  Pan  up-left  cursor. 

-18983  Pan  up  cursor,  with  panning  constrained. 

-18984  Pan  up  cursor. 

-18985  Pan  down-right  cursor,  with  both  panning  down  and  panning  right 
constrai ned . 

-18986  Pan  down-right  cursor,  with  panning  right  constrained. 

-18987  Pan  down-right  cursor,  with  panning  down  constrained. 

-18988  Pan  down-right  cursor. 

-18989  Pan  down-left  cursor,  with  both  panning  down  and  panning  left 
constrai ned . 

-18990  Pan  down-left  cursor,  with  panning  left  constrained. 

-18991  Pan  down-left  cursor,  with  panning  down  constrained. 

-18992  Pan  down-left  cursor. 

-18993  Pan  down  cursor,  with  panning  constrained. 

-18994  Pan  down  cursor. 

-18995  Pan  right  cursor,  with  panning  constrained. 

-18996  Pan  right  cursor. 

-18997  Pan  left  cursor,  with  panning  constrained. 

-18998  Pan  left  cursor. 

-18999  Mouse  centered,  waiting  to  pan  or  tilt  cursor. 

-19000  Panning  interface  mouse-up  cursor. 

-31494  Translate  on,  but  unable  to  translate  cursor. 

-31495  Translate  on  cursor. 

-31496  Zooming  out  cursor,  with  zooming  constrained. 

-31497  Zooming  in  cursor,  with  zooming  constrained. 

-31498  Conflicting  zoom  keys  cursor. 

-31499  Zooming  out  cursor. 

-31500  Zooming  in  cursor. 

-32000  Mouse  over  link  ('link')  hot  spot  cursor. 

-32192  Mouse-up  cursor  while  URL  (  '  u  r 1  ')  hot  spot  is  executing 
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-32193  Mouse  down  on  URL  ('url  ')  hot  spot  cursor 

-32194  Mouse  over  URL  ('url  ')  hot  spot  cursor 

-32195  Mouse-up  cursor  while  undefined  object  hot  spot  (any  hot  spot 
of  a  type  not  covered  by  other  hot  spot  cursors)  is  executing. 

-32196  Mouse  down  on  undefined  object,  that  is,  any  hot  spot  of  a  type 
not  covered  by  other  hot  spot  cursors. 

-32197  Mouse  over  undefined  object,  that  is,  any  hot  spot  of  a  type  not 
covered  by  other  hot  spot  cursors. 

-32198  Mouse-up  cursor  while  link  ('link')  hot  spot  is  executing. 

-32199  Mouse  down  on  link  ('link')  hot  spot  cursor. 


See  Also 

See  QTVRCursorRecord  (IV-2395).  For  pictures  of  the  cursors,  see  Appendix  A  of 
Programming  with  QuickTime  VR  (listed  in  the  bibliography). 


Sound  Commands 


Commands  for  SndDoCommand  (III— 1831)  and  SndDoImmedi  ate  (III— 1832). 

nul 1 Cmd  =  0 

quietCmd  =  3 

f 1 ushCmd  =  4 

relnitCmd  =  5 


wai tCmd 

=  10 

pauseCmd 

=  11 

resumeCmd 

=  12 

cal  1 BackCmd 

=  13 

syncCmd 

=  14 

avai 1 abl eCmd 

=  24 

versi onCmd 

=  25 

vol umeCmd 

=  46, 

// 

sound 

manager 

3.0  or  later  only 

getVol umeCmd 

=  47, 

it 

sound 

manager 

3.0  or  later  only 

cl ockComponentCmd 

=  50, 

// 

sound 

manager 

3.2.1  or  later  only 

getCl ockComponentCmd 

=  51, 

// 

sound 

manager 

3.2.1  or  later  only 

schedul edSoundCmd 

=  52, 

// 

sound 

manager 

3.3  or  later  only 

1 i nkSound Components Cmd 

=  53, 

// 

sound 

manager 

3.3  or  later  only 

soundCmd 

=  80 

buf ferCmd 

=  81 

rateMul ti pi i erCmd 

=  86 

getRateMul ti pi i erCmd 

=  87 

See  Also 

See  the  SndCommand  (IV-2441)  structure  and  the  SndDoCommand  (III— 1831)  and 
SndDoImmedi  ate  (III— 1832)  functions. 
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Sound  Device  Features 


Indicate  the  operating  features  of  a  sound  device. 


k8Bi tRawIn 

= 

(1  «  0) 

k8Bi tTwosIn 

= 

(1  «  1) 

k 1 6  B i tin 

= 

(1  «  2) 

kStereoIn 

= 

(1  «  3) 

k8Bi tRawOut 

= 

(1  «  8) 

k8Bi tTwosOut 

= 

(1  «  9) 

k 1 6  B i tOut 

= 

(1  «  10) 

kStereoOut 

= 

(1  «  11) 

kReverse 

= 

(1L  «  16) 

kRateConvert 

= 

(1L  «  17) 

kCreateSoundSource 

= 

(1L  «  18) 

kVMAwareness 

= 

(1L  «  21) 

kHi ghQual i ty 

= 

(1L  «  22) 

kNonReal T i me 

= 

(1L  «  23) 

See  Also 

See  Audioinfo  (IV-2160). 


Sound  Formats 


Specify  the  formats  of  digitized  sound. 


kSound Not Compressed 
k8Bi tOffsetBi nary  Format 
kl6Bi tBi gEndi an  Format 
kl6Bi tLi ttl eEndi an  Format 
k FI  oat32Format 
kFl oat64Format 
k24Bi tFormat 
k32Bi tFormat 
kMACE3Compressi on 
kMACE6Compressi on 
kCDXA4Compressi on 
kCDXA2Compressi on 
kIMACompressi on 
kULawCompressi on 
kALawCompressi on 
kMi c r os of tADPCM Format 
kDVI Intel  IMA Format 
kDVAudi oFormat 
kQDesi gn Comp  res si  on 
kQUALCOMMCompressi on 


=  'NONE' ) 

=  '  raw  ' ) 

=  ' twos  '  ) 

=  ' sowt '  ) 

=  '  f 1 32 ' ) 

=  ' f 1 64 '  ) 

=  '  i  n  2  4 '  ) 

=  '  i n32 ' ) 

=  ' MAC3  '  ) 

=  ' MAC6  '  ) 

=  '  cdx4 ' ) 

=  '  cdx2 ' ) 

=  '  i ma4 ' ) 

=  '  ul  aw '  ) 

=  ' al aw ' ) 

=  0x6D730002 
=  0x6D730011 
=  '  dvca  '  ) 

=  ' QDMC  '  ) 

=  ' Qcl p ' ) 
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k8Bi tOffsetBi naryFormat 
kl6Bi tBi gEndi an  Format 
k 1 6  B  i  t  LI ttl eEndi an  Format 
0x6D730055 

See  Also 

See  CmpSoundHeader  (IV-2176). 


kOffsetBi nary 
kTwosCompl ement 
kLi  ttl eEndi an  Format 
kM P EG Layer3 Format 


Sound  Information  Selectors 


Specify  information  to  be  returned  about  the  user's  sound  configuration. 


si  Acti veChannel s 

= 

' chac ' 

si  Acti veLevel s 

= 

' 1  mac ' 

si  AGCOnOf f 

= 

'age  ' 

si Async 

= 

' asyn ' 

si AVDi spl ayBehavi or 

= 

' avdb ' 

si  Channel Avai 1 abl e 

= 

' chav ' 

si  Compressi onAvai 1 abl e 

= 

'  cmav ' 

si  Compressi onChannels 

= 

'  epet ' 

si  Compressi on  Fact or 

= 

' cmf a ' 

si Compressi onHeader 

= 

'  cmhd ' 

si Compressi onNames 

= 

' cnam' 

si Compressi on  Pa  rams 

= 

'evaw' 

si Compressi onSampl eRate 

= 

'  cprt ' 

si Compressi onType 

= 

'  comp ' 

si  Conti nuous 

= 

'  cont ' 

si  Decomp res  si  on  Pa  rams 

= 

'wave' 

si  Devi ceBuffer Info 

= 

'  d  b  i  n  ' 

si  Devi ceConnected 

= 

' dcon ' 

si  Devi celcon 

= 

' i con ' 

si  Devi ceName 

= 

'  name ' 

si EQSpectrumBands 

= 

' eqsb ' 

si EQSpectrumLevel s 

= 

' eql v ' 

si EQSpectrumOnOf f 

= 

' eql o ' 

si EQToneControl Gain 

= 

'  eqtg ' 

si EQToneControl OnOff 

= 

'  eqtc ' 

si HardwareBal ance 

= 

' hbal  ' 

si HardwareBal anceSteps 

= 

'  hbl  s ' 

si HardwareBass 

= 

'  hbas ' 

si HardwareBass Steps 

= 

'  hbst ' 

si HardwareBusy 

= 

'  hwbs ' 

si HardwareFormat 

= 

' hwfm' 

si HardwareMute 

= 

'  hmut ' 

si HardwareT  rebl e 

= 

' htrb ' 

si HardwareT rebl eSteps 

= 

'  hwts ' 

si HardwareVol ume 

= 

'  hvol  ' 

//  active  channels 
//  active  meter  levels 
//  automatic  gain  control  state 
//  asynchronous  capability 

//  number  of  channels  available 
//  compression  types  available 
//  compressor's  number  of  channels 
//  current  compression  factor 
//  return  compression  header 
//  compression  type  names  avail 
//  compression  parameters 
//  compressor's  sample  rate 
//  current  compression  type 
//  continous  recording 
//  decompression  parameters 
//  size  of  interrupt  buffer 

//  input  device  conn  status 

//  input  device  icon 

//  input  device  name 

//  number  of  spectrum  bands 
//  get  spectrum  meter  levels 
//  turn  on/off  spect  mtr  levels 
//  set  the  bass  and  treble  gain 
//  turn  on  equalizer  attenuation 
//  balance  setting  of  hardware 
//  num  balance  steps  for  hardware 
//  bass  level  of  hardware 
//  num  bass  steps  for  hardware 
//  sound  hardware  is  in  use 
//  get  hardware  format 
//  mute  state  of  all  hardware 
//  treble  level  of  hardware 
//  num  treble  steps  for  hardware 
//  volume  level  of  hardware 
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si HardwareVol umeSteps 

= 

' hstp' 

si HeadphoneMute 

= 

' pmut ' 

si HeadphoneVol ume 

= 

' pvol  ' 

siHeadphoneVol umeSteps 

= 

' hdst ' 

si InputAvai 1 abl e 

= 

'  i  n  a  v  ' 

si InputGai n 

= 

'  gain ' 

si InputSource 

= 

'  sour ' 

silnputSourceNames 

= 

'  snam ' 

si  Level MeterOnOff 

= 

'  1  met ' 

si ModemGai n 

= 

' mgai  ' 

si Moni torAvai 1 abl e 

= 

' mnav ' 

si Moni torSource 

= 

' mons ' 

si NumberChannel  s 

= 

'  chan ' 

si Opti onsDi al og 

= 

'  optd ' 

siOSTypelnputSource 

= 

'  i npt ' 

si  OSType InputAvai 1 abl e 

= 

'  i  n  a  v  ' 

si  PI ayThruOnOff 

= 

'pith' 

si  Post Mi xerSoundComponent 

= 

' psmx ' 

si PreMi xerSoundComponent 

= 

' prmx ' 

si Qual i ty 

= 

' qual  ' 

si RateMul ti pi i er 

= 

' rmul  ' 

si Recordi ngQual i ty 

= 

' qual  ' 

si Sampl eRate 

= 

' srat ' 

si  Samp 1 eRateAvai 1 abl e 

= 

' srav ' 

si Sampl eSi ze 

= 

'  ssi z ' 

si  Sampl eSi zeAvai 1 abl e 

= 

'  ssav ' 

si SetupCDAudi o 

= 

'  sued ' 

si  SetupModemAudi o 

= 

'  sumd ' 

si  SI  ope And  Intercept 

= 

'flap' 

si SoundCl ock 

= 

' scl k ' 

siUseThisSoundClock 

= 

'  scl c ' 

si SpeakerMute 

= 

' smut ' 

si SpeakerVol ume 

= 

' svol  ' 

si SSpCPULoadLi mi t 

= 

'  3dl  1  ' 

si SSpLocal i zati on 

= 

' 3d i f ' 

si SSpSpeakerSetup 

= 

' 3dst ' 

si StereoInputGai n 

= 

' sgai  ' 

si SubwooferMute 

= 

' bmut ' 

si  Twos Comp 1 ementOnOff 

= 

' twos ' 

si Vol ume 

= 

' vol u ' 

si VoxRecordlnfo 

= 

'  voxr ' 

si VoxStopInfo 

= 

' voxs ' 

si Wi deStereo 

= 

'wide' 

//  num  volume  steps  for  hardware 

//  mute  state  of  headphones 

//  volume  level  of  headphones 

//  num  volume  steps  for  headphones 

//  input  sources  available 

//  input  gain 

//  input  source  selector 

//  input  source  names 

//  level  meter  state 

//  modem  input  gain 


//  current  number  of  channels 
//  display  options  dialog 
//  input  source  by  OSType 
//  list  of  input  source  OSTypes 
//  playthrough  state 
//  install  post-mixer  effect 
//  install  pre-mixer  effect 
//  quality  setting 
//  throttle  rate  setting 
//  recording  quality 
//  current  sample  rate 
//  sample  rates  available 
//  current  sample  size 
//  sample  sizes  available 
//  set  up  sound  hardware  for  CD 
//  set  up  sound  hardware  for  modem 
//  float-point  vars  for  conversion 

//  tell  mixer  to  use  sound  clock 
//  mute  state  of  built-in  speaker 
//  volume  of  built-in  speaker 


//  stereo  input  gain 
//  mute  state  of  sub-woofer 
//  two's  complement  state 
//  volume  level  of  source 
//  VOX  record  parameters 
//  VOX  stop  parameters 
//  wide  stereo  setting 


See  Also 

For  an  example  of  using  sound  information  selectors,  see  GetSoundOutputlnfo 
(1-511). 
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Sound  Sample  Rates 


Encode  the  rates  at  which  sound  data  is  sampled. 


rate48khz 

=  ( 1 ong )0xBB800000 , 

// 

48000.00000 

i  n 

fixed -poi nt 

rate44khz 

=  ( 1 ong )0xAC440000 , 

// 

44100.00000 

i  n 

fixed -poi nt 

rate32khz 

=  Ox7DOOOOOO, 

// 

32000.00000 

i  n 

fixed -poi nt 

rate22050hz 

=  0x56220000, 

// 

22050.00000 

i  n 

fixed -poi nt 

rate22khz 

=  0x56EE8BA3, 

// 

22254.54545 

i  n 

fixed -poi nt 

ratel6khz 

=  0x3E800000, 

// 

16000.00000 

i  n 

fixed -poi nt 

ratellkhz 

=  0x2B7745Dl, 

// 

11127.27273 

i  n 

fixed -poi nt 

ratell025hz 

=  0x2Bl 10000 , 

// 

11025.00000 

i  n 

fixed -poi nt 

rate8khz 

=  0x1 F400000 

// 

8000.00000 

i  n 

fixed -poi nt 

Discussion 

Sample  rate  constants  are  declared  as  a  Fixed  data  type,  but  the  most  significant  bit 
is  not  treated  as  a  sign  bit;  instead,  it  is  interpreted  as  having  the  value  32,768. 

See  Also 

See  CmpSoundHeader  (IV-2176). 


Streaming  Transport  Atoms 


Identify  transport  atom  types  for  QuickTime  streaming. 


kQTST  ransAndProxyAtomType 
kQTSConnecti onPrefsVersi  on 
kQTST  ransportPref sAtomType 
kQTSConnecti onAtomType 
kQTSUDPT  ransportType 
kQTSHTTPT  ransportType 
kQTSTCPT  ransportType 
kQTSProxyP ref sAtomType 
kQTSHTTPProxyPref sType 
kQTSRTSPProxyPref sType 
kQTSSOCKSProxyP ref sType 
kQTSDont Proxy Pref sAtomType 
kQTSDont Proxy Da t a Type 

See  Also 

See  QTSTransportPref  (IV-2388). 


' strp ' 

// 

transport/proxy  prefs 

root  atom 

' vers ' 

// 

prefs  format  version 

' trns ' 

// 

tranport  prefs  root  atom 

'  conn ' 

// 

connection  prefs  atom 

type 

'  udp  ' 

// 

udp  transport  prefs 

' http ' 

// 

http  transport  prefs 

'  tcp  ' 

// 

tcp  transport  prefs 

'  prxy ' 

// 

proxy  prefs  root  atom 

' http ' 

// 

http  proxy  settings 

' rtsp ' 

// 

rtsp  proxy  settings 

'  scks ' 

// 

socks  proxy  settings 

'  nopr ' 

// 

no-proxy  prefs  root  atom 

'data ' 

// 

no  proxy  settings 
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User  Data  Identifiers 


Identify  user  data  fields  in  a  movie. 

kllserDataMovieControllerType 

=  ' ctyp ' 

kUserDataName 

=  'name' 

kUse r Da taText Author 

=  '©aut' 

kUserDataTextComment 

=  ’©cmt' 

kllserDataTextCopyri  ght 

=  '©cpy ' 

kUserDataTextCreati on  Date 

=  '©day' 

kUse r Da taText Descri pti on 

=  '©des' 

kUserDataTextDi rector 

=  '©dir' 

kUser Da taText Di scl ai mer 

=  '©dis' 

kUse r Da taText Ful 1  Name 

=  '©nam' 

kUserDataTextHostComputer 

=  '©hst' 

kUserDataTextlnformati on 

=  '©inf' 

kUser Da taText Keywords 

=  '©key' 

kllserDataTextMake 

=  '©mak' 

kllserDataTextModel 

=  '©mod' 

kUserDataTextOri ginal Format 

=  '©fmt' 

kUserDataTextOri ginal Source 

=  '©src' 

kUser Da taText Performers 

=  '©prf' 

kUser Da taText Producer 

=  '©prd' 

kUser Da taText Product 

=  ’©PRD' 

kUserDataTextSoftware 

=  '©swr' 

kUserDataTextSpeci al PI aybackRequi remen ts 

=  '©req' 

kUserDataTextWarni ng 

=  '©wrn' 

kUserDataTextWri ter 

=  '©wrt' 

kUse r Da taText Edi t Da tel 

=  '©edl' 

kUser Da taTextChapter 

=  '©chp' 

See  Also 


For  an  example  of  passing  user  data  types,  see  GetUserData  (1-547). 


Video  Digitizer  Capabilities 


Flags  that  indicate  the  input  and  output  capabilities  of  a  video  digitizer. 
//  Input  capabilities 


di  gi  InDoesNTSC  =1L«0 

di gi InDoesPAL  =1 L<< 1 

digilnDoesSECAM  -1L«2 

digi InDoesGenLock  =1L<<7 

di gi InDoesComposi te  =1L<<8 

di gi InDoesSVi deo  =1L<<9 

di gi InDoesComponent  =1 L<< 1 0 


IV-2696 


Inside  QuickTime:  Constants 


digi  InVTFCBroadcast 

=1  L«1 1 

di gi InDoesCol or 

=1 L<< 1 2 

di gi InDoesBW 

=1  L«13 

di gi InSi gnal Lock 

=1L«31 

//  Output  capabilities 

di gi OutDoesl 

=1L«0 

di gi 0utDoes2 

=1L«1 

di gi 0utDoes4 

=1  L«2 

di gi 0utDoes8 

-1L«3 

di gi 0utDoesl6 

=1L«4 

di gi 0utDoes32 

=1 L<<5 

di gi OutDoesDi ther 

=1  L«6 

di gi OutDoesStretch 

=1L«7 

di gi OutDoesShri nk 

=1L«8 

di gi OutDoesMask 

=1L«9 

di  gi  OutDoesDoubl e 

=1 L<< 1 1 

di gi OutDoesQuad 

=1 L<< 1 2 

digi Out Does Quarter 

=1  L«13 

di gi OutDoesSi xteenth 

=1 L<  < 1 4 

di gi OutDoesRotate 

=1 L<< 1 5 

di gi OutDoesHori z  F 1  ip 

=1  L«16 

di gi OutDoesVertFl  i p 

=1 L<< 1 7 

di gi OutDoesSkew 

=1 L<  < 1 8 

di gi OutDoesBl end 

=1 L<< 1 9 

di gi OutDoesWarp 

=1  L«20 

di gi OutDoesHW_DMA 

=1 L<<2 1 

digiOutDoesHWPl ayThru 

=1L«22 

di gi OutDoes I LUT 

=1L«23 

di gi OutDoesKeyCol or 

=1  L«24 

digi OutDoesAsyncGrabs 

=1 L<  <  2  5 

digiOutDoesUnreadabl eScreenBi ts 

=1L«26 

digi Out Does Compress 

=1  L«27 

digi  Out Does Compress Only 

=1L«28 

digiOutDoesPl ayThruDuri ngCompress 

=1L«29 

di gi OutDoesCompressParti al 1 y Vi  si bl e 

=1L«30 

digi Out Does  Not Need Copy Of Compress  Data 

=1  L«31 

di gi InDoesNTSC 

The  video  digitizer  supports  National  Television  System  Committee  (NTSC) 
format  input  video  signals.  This  flag  is  set  to  1  if  the  digitizer  component 
supports  NTSC  video, 
di gi InDoesPAL 

The  video  digitizer  component  supports  Phase  Alternation  Line  (PAL)  format 
input  video  signals.  This  flag  is  set  to  1  if  the  digitizer  component  supports  PAL 
video. 
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di gi InDoesSECAM 

The  video  digitizer  component  supports  Systeme  Electronique  Couleur  avec 
Memoire  (SEC AM)  format  input  video  signals.  This  flag  is  set  to  1  if  the 
digitizer  component  supports  SECAM  video, 
di gi InDoesGenLock 

The  video  digitizer  component  supports  genlock;  that  is,  the  digitizer  can 
derive  its  timing  from  an  external  time  base.  This  flag  is  set  to  1  if  the  digitizer 
component  supports  genlock. 

di gi In Does Compos i te 

The  video  digitizer  component  supports  composite  input  video.  This  flag  is  set 
to  1  if  the  digitizer  component  supports  composite  input, 
di gi tlnDoesSVi deo 

The  video  digitizer  component  supports  s-video  input  video.  This  flag  is  set  to 
1  if  the  digitizer  component  supports  s-video  input, 
di gi In  Does Component 

The  video  digitizer  component  supports  RGB  input  video.  This  flag  is  set  to  1  if 
the  digitizer  component  supports  RGB  input. 

di gi InVTR_Broadcast 

The  video  digitizer  component  can  distinguish  between  an  input  signal  that 
emanates  from  a  videotape  player  and  a  broadcast  signal.  This  flag  is  set  to  1  if 
the  digitizer  component  can  differentiate  between  the  two  different  signal 
types. 

di gi InDoesCol or 

The  video  digitizer  component  supports  color  input.  This  flag  is  set  to  1  if  the 
digitizer  component  can  accept  color  input, 
di gi InDoesBW 

The  video  digitizer  component  supports  grayscale  input.  This  flag  is  set  to  1  if 
the  digitizer  component  can  accept  grayscale  input. 

di gi InSi gnal Lock 

The  video  digitizer  component  is  locked  onto  the  input  signal.  If  this  flag  is  set 
to  1,  the  digitizer  component  detects  either  vertical  or  horizontal  signal  lock, 
di gi OutDoesl 

The  video  digitizer  component  can  work  with  pixel  maps  that  contain  1-bit 
pixels.  If  this  flag  is  set  to  1,  then  the  digitizer  component  can  write  images  that 
contain  1-bit  pixels.  If  this  flag  is  set  to  0,  then  the  digitizer  component  cannot 
handle  such  images. 
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di gi 0utDoes2 

The  video  digitizer  component  can  work  with  pixel  maps  that  contain  2-bit 
pixels.  If  this  flag  is  set  to  1,  then  the  digitizer  component  can  write  images  that 
contain  2-bit  pixels.  If  this  flag  is  set  to  0,  then  the  digitizer  component  cannot 
handle  such  images, 
di gi 0utDoes4 

The  video  digitizer  component  can  work  with  pixel  maps  that  contain  4-bit 
pixels.  If  this  flag  is  set  to  1,  then  the  digitizer  component  can  write  images  that 
contain  4-bit  pixels.  If  this  flag  is  set  to  0,  then  the  digitizer  component  cannot 
handle  such  images. 

di gi 0utDoes8 

The  video  digitizer  component  can  work  with  pixel  maps  that  contain  8-bit 
pixels.  If  this  flag  is  set  to  1,  then  the  digitizer  component  can  write  images  that 
contain  8-bit  pixels.  If  this  flag  is  set  to  0,  then  the  digitizer  component  cannot 
handle  such  images, 
di gi 0utDoesl6 

The  video  digitizer  component  can  work  with  pixel  maps  that  contain  16-bit 
pixels.  If  this  flag  is  set  to  1,  then  the  digitizer  component  can  write  images  that 
contain  16-bit  pixels.  If  this  flag  is  set  to  0,  then  the  digitizer  component  cannot 
handle  such  images, 
di gi 0utDoes32 

The  video  digitizer  component  can  work  with  pixel  maps  that  contain  32-bit 
pixels.  If  this  flag  is  set  to  1,  then  the  digitizer  component  can  write  images  that 
contain  32-bit  pixels.  If  this  flag  is  set  to  0,  then  the  digitizer  component  cannot 
handle  such  images. 

di gi OutDoesDi ther 

The  video  digitizer  component  supports  dithering.  If  this  flag  is  set  to  1,  the 
component  supports  dithering  of  colors.  If  this  flag  is  set  to  0,  the  digitizer 
component  does  not  support  dithering, 
di gi OutDoesStretch 

The  video  digitizer  component  can  stretch  images  to  arbitrary  sizes.  If  this  flag 
is  set  to  1,  the  digitizer  component  can  stretch  images.  If  this  flag  is  set  to  0,  the 
digitizer  component  does  not  support  stretching, 
di gi OutDoesShri nk 

The  video  digitizer  component  can  shrink  images  to  arbitrary  sizes.  If  this  flag 
is  set  to  1,  the  digitizer  component  can  shrink  images.  If  this  flag  is  set  to  0,  the 
digitizer  component  does  not  support  shrinking. 
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di gi OutDoesMask 

The  video  digitizer  component  can  handle  clipping  regions.  If  this  flag  is  set  to 
1,  the  digitizer  component  can  mask  to  an  arbitrary  clipping  region.  If  this  flag 
is  set  to  0,  the  digitizer  component  does  not  support  clipping  regions. 

di  gi OutDoesDoubl e 

The  video  digitizer  component  supports  stretching  to  quadruple  size  when 
displaying  the  output  video.  The  parameters  for  the  stretch  operation  are 
specified  in  the  matrix  structure  for  the  request;  the  component  modifies  the 
scaling  attributes  of  the  matrix  (see  the  chapter  "Movie  Toolbox"  in  Inside 
Macintosh:  QuickTime  for  information  about  transformation  matrices).  If  this 
flag  is  set  to  1,  the  digitizer  component  can  stretch  an  image  to  exactly  four 
times  its  original  size,  up  to  the  maximum  size  specified  by  the  maxDestHeight 
and  maxDestWi  dth  fields  in  the  digitizer  information  structure.  If  this  flag  is  set 
to  0,  the  digitizer  component  does  not  support  stretching  to  quadruple  size. 

di gi OutDoesQuad 

The  video  digitizer  component  supports  stretching  an  image  to  16  times  its 
original  size  when  displaying  the  output  video.  The  parameters  for  the  stretch 
operation  are  specified  in  the  matrix  structure  for  the  request;  the  component 
modifies  the  scaling  attributes  of  the  matrix  (see  the  chapter  "Movie  Toolbox" 
in  Inside  Macintosh:  QuickTime  for  information  about  transformation 
matrices).  If  this  flag  is  set  to  1,  the  digitizer  component  can  stretch  an  image  to 
exactly  16  times  its  original  size,  up  to  the  maximum  size  specified  by  the 
maxDestHei  ght  and  maxDestWi  dth  fields  in  the  digitizer  information  structure.  If 
this  flag  is  set  to  0,  the  digitizer  component  does  not  support  this  capability. 

digiOutDoesQuarter 

The  video  digitizer  component  can  shrink  an  image  to  one-quarter  of  its 
original  size  when  displaying  the  output  video.  The  parameters  for  the  shrink 
operation  are  specified  in  the  matrix  structure  for  the  request;  the  component 
modifies  the  scaling  attributes  of  the  matrix  (see  the  chapter  "Movie  Toolbox" 
in  Inside  Macintosh:  QuickTime  for  information  about  transformation 
matrices).  If  this  flag  is  set  to  1,  the  digitizer  component  can  shrink  an  image  to 
exactly  one-quarter  of  its  original  size,  down  to  the  minimum  size  specified  by 
the  minDestHeight  and  minDestWidth  fields  in  the  digitizer  information 
structure.  If  this  flag  is  set  to  0,  the  digitizer  component  does  not  support  this 
capability. 

di gi Out Does Sixteenth 

The  video  digitizer  component  can  shrink  an  image  to  1/16  of  its  original  size 
when  displaying  the  output  video.  The  parameters  for  the  shrink  operation  are 
specified  in  the  matrix  structure  for  the  request;  the  digitizer  component 
modifies  the  scaling  attributes  of  the  matrix  (see  the  chapter  "Movie  Toolbox" 
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in  Inside  Macintosh:  QuickTime  for  information  about  transformation 
matrices).  If  this  flag  is  set  to  1,  the  digitizer  component  can  shrink  an  image  to 
exactly  1  / 16  of  its  original  size,  down  to  the  minimum  size  specified  by  the 
mi  nDestHei  ght  and  mi  nDestWi  dth  fields  in  the  digitizer  information  structure.  If 
this  flag  is  set  to  0,  the  digitizer  component  does  not  support  this  capability. 

di gi OutDoesRotate 

The  video  digitizer  component  can  rotate  an  image  when  displaying  the  output 
video.  The  parameters  for  the  rotation  are  specified  in  the  matrix  structure  for 
an  operation.  If  this  flag  is  set  to  1,  the  digitizer  component  can  rotate  the  image. 
If  this  flag  is  set  to  0,  the  digitizer  component  cannot  rotate  the  resulting  image. 

di gi OutDoesHori z  F 1  ip 

The  video  digitizer  component  can  flip  an  image  horizontally  when  displaying 
the  output  video.  The  parameters  for  the  horizontal  flip  are  specified  in  the 
matrix  structure  for  an  operation.  If  this  flag  is  set  to  1,  the  digitizer  component 
can  flip  the  image.  If  this  flag  is  set  to  0,  the  digitizer  component  cannot  flip  the 
resulting  image, 
di gi OutDoesVertFl i p 

The  video  digitizer  component  can  flip  an  image  vertically  when  displaying  the 
output  video.  The  parameters  for  the  vertical  flip  are  specified  in  the  matrix 
structure  for  an  operation.  If  this  flag  is  set  to  1,  the  digitizer  component  can  flip 
the  image.  If  this  flag  is  set  to  0,  the  digitizer  component  cannot  flip  the 
resulting  image. 

di gi OutDoesSkew 

The  video  digitizer  component  can  skew  an  image  when  displaying  the  output 
video.  Skewing  an  image  distorts  it  linearly  along  only  a  single  axis;  for 
example,  drawing  a  rectangular  image  into  a  parallelogram-shaped  region.  The 
parameters  for  the  skew  operation  are  specified  in  the  matrix  structure  for  the 
request.  If  this  flag  is  set  to  1,  the  digitizer  component  can  skew  an  image.  If  this 
flag  is  set  to  0,  the  digitizer  component  does  not  support  this  capability. 

di gi OutDoesBl end 

The  video  digitizer  component  can  blend  the  resulting  image  with  a  matte 
when  displaying  the  output  video.  The  matte  is  provided  by  the  application  by 
defining  either  an  alpha  channel  or  a  mask  plane.  If  this  flag  is  set  to  1,  the 
digitizer  component  can  blend.  If  this  flag  is  set  to  0,  the  digitizer  component 
does  not  support  this  capability, 
di gi OutDoesWarp 

The  video  digitizer  component  can  warp  an  image  when  displaying  the  output 
video.  Warping  an  image  distorts  it  along  one  or  more  axes,  perhaps 
nonlinearly,  in  effect  "bending"  the  result  region.  The  parameters  for  the  warp 
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operation  are  specified  in  the  matrix  structure  for  the  request.  If  this  flag  is  set 
to  1,  the  digitizer  component  can  warp  an  image.  If  this  flag  is  set  to  0,  the 
digitizer  component  does  not  support  this  capability. 

di gi OutDoesDMA 

The  video  digitizer  component  can  write  to  any  screen  or  to  offscreen  memory. 
If  this  flag  is  set  to  1,  the  digitizer  component  can  use  DMA  to  write  to  any 
screen  or  memory  location. 

di gi OutDoesHWPl ayThru 

The  video  digitizer  component  does  not  need  idle  time  in  order  to  display  its 
video.  If  this  flag  is  set  to  1,  your  application  does  not  need  to  grant  processor 
time  to  the  digitizer  component  at  normal  display  speeds, 
di gi OutDoes I LUT 

The  video  digitizer  component  supports  inverse  lookup  tables  for  indexed 
color  modes.  If  this  flag  is  set  to  1,  the  digitizer  component  uses  inverse  lookup 
tables  when  appropriate. 

di gi Out Does  Key Col  or 

The  video  digitizer  component  supports  clipping  by  means  of  key  colors.  If  this 
flag  is  set  to  1,  the  digitizer  component  can  clip  to  a  region  defined  by  a  key 
color. 

di gi Out Does AsyncGrabs 

The  video  digitizer  component  can  operate  asynchronously.  If  this  flag  is  set  to 
1,  your  application  can  use  the  VDSetupBuffers  and  VDGrabOneFrameAsync 
functions  (described  on  page  0-669  and  page  0-671,  respectively). 
digiOutDoesUnreadableScreenBits 

The  video  digitizer  may  place  pixels  on  the  screen  that  cannot  be  used  when 
compressing  images. 

di gi OutDoesCompress 

The  video  digitizer  component  supports  compressed  source  devices.  These 
devices  provide  compressed  data  directly,  without  having  to  use  the  Image 
Compression  Manager.  See  "Controlling  Compressed  Source  Devices" 
beginning  on  page  0-657  for  more  information  about  the  functions  that 
applications  can  use  to  work  with  compressed  source  devices. 

digi OutDoesCompressOnly 

The  video  digitizer  component  only  provides  compressed  image  data;  the 
component  cannot  provide  displayable  data.  This  flag  only  applies  to  digitizers 
that  support  compressed  source  devices. 
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digiOutDoesPl ayThruDuri ngCompress 

The  video  digitizer  component  can  draw  images  on  the  screen  at  the  same  time 
that  it  is  delivering  compressed  image  data.  This  flag  only  applies  to  digitizers 
that  support  compressed  source  devices, 
di gi Out Does  Not Need Copy Of Compress  Data 

The  sequence  grabber  does  not  make  any  copies  of  compressed  data  coming 
from  a  video  digitizer  during  recording.  This  allows  specific  hardware  to 
perform  direct  disk  I/O  without  the  need  of  a  custom  data  handler. 

Discussion 

Video  digitizer  components  report  both  their  capabilities  and  their  current  status  by 
returning  a  flags  field  that  contains  1  bit  for  each  of  the  capability  flags.  When 
reporting  input  status,  for  example,  a  video  digitizer  component  sets  the 
digilnDoesGenLock  flag  to  1  whenever  the  digitizer  component  is  deriving  its  time 
signal  from  the  input  video.  When  reporting  its  input  capabilities,  the  digitizer 
component  sets  this  flag  to  1  to  indicate  that  it  can  derive  its  timing  from  the  input 
video. 


See  Also 

See  VDGetCurrentFl  ags  (III — 1996),  VDGetDi  gi  ti  zerlnfo  (III — 1998). 
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Volume  V 

Programming  Summary  and  Indexes 


PREFACE  TO  VOLUME  V 

About  Volume  V 


Volume  V  of  Inside  QuickTime:  API  Reference  is  designed  to  help  you  access  and 
understand  the  information  contained  in  Volumes  I  through  IV.  This  volume 
contains  the  following  sections: 

■  A  programming  summary,  in  which  the  main  QuickTime  functions  and  data 
structures  are  grouped  and  explained  in  terms  of  programming  tasks. 

■  An  index  of  data  types  that  locates  the  documentation  for  each  of 
QuickTime's  structures,  declared  types,  atom  types,  and  callback  pointers. 

■  An  index  of  constants  that  locates  each  of  QuickTime's  enumerated 
constants,  including  atom  codes. 

■  A  list  of  functions  sorted  in  the  order  in  which  their  prototypes  appear  in  the 
QuickTime  header  files. 

■  A  bibliography  that  lists  other  books  and  websites  containing  information 
about  QuickTime  programming. 

■  A  glossary  of  QuickTime-specific  technical  terms  used  in  this  reference. 

■  A  history  of  changes  to  the  QuickTime  API  and  its  documentation,  starting 
with  the  first  publication  of  this  reference. 

The  API  Reference  as  a  whole  is  designed  to  let  you  absorb  the  same  information 
from  multiple  viewpoints,  using  several  media.  To  begin  a  coding  task,  for 
example,  you  might  start  with  the  programming  summary  in  this  volume.  You 
could  skim  it  in  paper  or  PDF  to  get  a  feel  for  the  kinds  of  functions  that 
QuickTime  provides  for  your  task,  and  to  see  how  they  interrelate.  Then  you 
could  switch  to  the  online  documentation  of  specific  functions  and  data 
structures,  clicking  back  and  forth  between  detailed  information  and  the 
programming  summary.  Any  time  you  encountered  an  unfamiliar  constant  or 
data  type,  you  could  look  it  up  in  one  of  the  indexes. 

When  using  this  five-volume  work,  however,  remember  that  it  is  a  reference;  its 
primary  purpose  is  to  help  you  find  information  that  you  already  know  you 
need.  For  a  more  general  understanding  of  QuickTime's  capabilities  and  the 
structure  of  QuickTime  code,  consult  the  programming  guides  in  the 
QuickTime  Developer  Series  and  QuickTime  Technical  Library.  These  books  are 
listed  in  the  bibliography  that  starts  on  page  V-2911. 
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Using  Movie  Toolbox  Data  Structures 


Most  QuickTime  Movie  Toolbox  data  structures  are  private.  Your  application  never 
modifies  the  contents  of  these  structures  directly.  Rather,  the  Movie  Toolbox 
provides  a  number  of  functions  that  allow  you  to  work  with  them. 


Movie  Identifiers 


You  identify  various  data  structures  to  the  Movie  Toolbox  by  means  of  data  types 
that  are  supplied  by  Movie  Toolbox  functions. 
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Data  Types 

Medi  a 

Specifies  the  media  for  an  operation.  Your  application  obtains  a  media 
identifier  from  such  Movie  Toolbox  functions  as  NewT rackMedi  a  (11-1120)  and 
GetTrackMedi  a  (1-535). 

Movi  e 

Specifies  the  movie  for  an  operation.  Your  application  obtains  a  movie 
identifier  from  such  functions  as  NewMovi  e  (11-1069),  NewMovi  eFromFi  1  e  (11-1080), 
and  NewMovi  eFromHandl  e  (11-1084). 

Movi eEdi tState 

Specifies  the  movie  edit  state  for  an  operation.  Your  application  obtains  a  movie 
edit  state  identifier  when  you  create  the  edit  state  by  calling  NewMovi  eEdi  tState 
(11-1073). 

QTCal 1  Back 

Specifies  the  callback  for  an  operation.  You  obtain  a  callback  identifier  from 
NewCal  1  Back  (11-1053). 

TimeBase 

Specifies  the  time  base  for  an  operation.  Your  application  obtains  a  time  base 
identifier  from  NewTimeBase  (11-1119)  or  GetMovi eTimeBase  (1-496). 

T  rack 

Specifies  the  track  for  an  operation.  Your  application  obtains  a  track  identifier 
from  such  Movie  Toolbox  functions  as  NewMovi  eT rack  (11-1092)  and 
GetMovi  eT  rack  (1-497). 
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T  rackEdi tState 

Specifies  the  track  edit  state  for  an  operation.  Your  application  obtains  a  track 
edit  state  identifier  when  you  create  the  edit  state  by  calling  NewT rackEdi  tState 
(11-1119). 

UserData 

Specifies  the  user  data  list  for  an  operation.  You  obtain  a  user  data  list  identifier 
by  calling  GetMovi  eUserData  (I — 499),  GetT rackUserData  (1-546),  or 
GetMedi  allserData  (1-456). 


The  Time  Structure 

The  Movie  Toolbox  provides  a  number  of  functions  that  allow  you  to  work  with 
time  specifications.  Many  of  these  functions  require  that  you  place  a  time 
specification  in  a  data  structure  called  a  time  structure.  The  time  structure  allows 
you  to  fully  describe  a  time  specification. 

The  data  structure  listed  below  defines  the  format  of  a  time  structure. 

Data  Structures 

TimeRecord  (TV-2486) 

Contains  a  time  value  with  its  scale  and  time  base. 


The  Fixed-Point  and  Fixed-Rectangle  Structures 

The  Movie  Toolbox  matrix  functions  provide  two  mechanisms  for  specifying  points 
and  rectangles.  Some  of  the  functions  work  with  standard  QuickDraw  points  and 
rectangles,  which  use  integer  values  to  identify  coordinates.  Others,  such  as 
T ransformFi  xedRect  (III— 1952),  work  with  points  and  rectangles  whose  coordinates 
are  expressed  as  fixed-point  numbers.  By  using  fixed-point  numbers  in  these  points 
and  rectangles,  the  Movie  Toolbox  can  support  a  greater  degree  of  precision  when 
defining  graphic  objects. 

The  Fi xedPoi  nt  (IV-2258)  data  type  defines  a  fixed  point.  The  Fi xedRect  (IV-2260) 
data  type  defines  a  fixed  rectangle.  Note  that  both  of  these  structures  define  the  x 
coordinate  before  the  y  coordinate.  In  this  they  differ  from  standard  QuickDraw 
structures. 
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FixedPoint  (TV-2258) 

Defines  the  position  of  a  geometric  point  in  fixed-point  numbers. 
FixedRect  (IV-2260) 

Defines  the  size  and  location  of  a  rectangle  in  fixed-point  numbers. 


The  Sound  Description  Structure 

A  sound  description  structure  contains  information  that  defines  the  characteristics 
of  one  or  more  sound  samples.  Data  in  the  sound  description  structure  indicates  the 
type  of  compression  that  was  used,  the  sample  size,  the  rate  at  which  samples  were 
obtained,  and  so  on.  Sound  media  handlers  use  the  information  in  the  sound 
description  structure  when  they  process  the  sound  samples. 

Sound  media  handlers  use  the  information  in  the  sound  description  structure  when 
they  process  the  sound  samples. 

Data  Structures 

SoundDescri  pti  on  (IV-2449) 

Describes  the  format  of  a  collection  of  audio  samples. 

See  Also 

See  "Sound  Media  Handler  Functions"  (V-2755)  for  more  information  about  sound 
media  handlers.  See  "Image  Compression  Data  Structures"  (V-2786)  for  a 
description  of  the  image  description  structure,  which  contains  information  that 
defines  the  characteristics  of  an  image. 
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Getting  and  Playing  Movies 


The  Movie  Toolbox  provides  a  number  of  functions  that  allow  applications  to  get 
and  play  movies.  There  are  also  a  number  of  functions  that  allow  you  to  create  new 
movies. 
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Initializing  the  Movie  Toolbox 

The  Movie  Toolbox  maintains  state  information  for  every  application  that  is 
currently  using  the  toolbox.  The  toolbox  uses  this  information  to  keep  track  of  the 
application's  movies. 

Before  calling  any  other  Movie  Toolbox  functions,  your  application  must  establish 
this  working  environment  by  calling  EnterMovi  es  (1-337).  When  your  application  is 
finished  with  the  Movie  Toolbox,  you  can  release  this  storage  by  calling  Exi  tMovi  es 
(1-340). 


Functions 

EnterMovi  es  (1-337) 

Initializes  the  Movie  Toolbox  and  creates  a  private  storage  area  for  your 
application. 

Exi  tMovi  es  (1-340) 

Automatically  called  when  an  application  quits. 


Error  Functions 


The  Movie  Toolbox  provides  a  number  of  functions  that  allow  your  application  to 
examine  result  codes  generated  by  toolbox  functions.  In  addition,  the  Movie 
Toolbox  allows  your  application  to  provide  a  function  that  performs  custom  error 
notification. 

In  addition  to  returning  errors  as  function  results,  the  Movie  Toolbox  functions 
return  error  indications  to  calling  applications  by  setting  one  of  two  values  that  are 
private  to  the  Movie  Toolbox:  a  current  error  value  or  a  sticky  error  value. 

The  current  error  value  contains  the  result  code  from  the  last  Movie  Toolbox 
function.  The  toolbox  updates  the  current  error  value  each  time  your  application 
calls  a  Movie  Toolbox  function.  Your  application  may  call  Get  Mo  vies  Error  (1-492)  to 
obtain  the  current  error  value  after  calling  any  Movie  Toolbox  function.  Many 
Movie  Toolbox  functions  do  not  return  an  error  as  a  function  result;  you  must  use 
Ge tMovi  es  Error  (1-492)  to  obtain  the  result  code.  Even  if  a  function  explicitly  returns 
an  error  as  a  function  result,  that  result  is  also  available  using  GetMoviesError 
(I — 492). 

The  Movie  Toolbox  saves  a  result  code  in  the  sticky  error  value.  Your  application 
clears  the  sticky  error  value  by  calling  Cl  earMovi  esSti  cky Error  (1-90).  The  Movie 
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Toolbox  then  places  the  first  nonzero  result  code  from  any  toolbox  function  used  by 
your  application  into  the  sticky  error  value.  The  Movie  Toolbox  does  not  replace  the 
value  in  the  sticky  error  value  until  your  application  clears  the  value  again.  Your 
application  uses  GetMovi  esSticky  Error  (1-494)  to  obtain  the  result  code  stored  in  the 
sticky  error  value.  In  this  manner,  you  can  preserve  and  retrieve  important  result 
code  information. 

Your  application  can  use  SetMovi esErrorProc  (III— 1633)  to  designate  an  error 
function.  The  Movie  Toolbox  calls  this  error  function  each  time  there  is  an  error. 


Functions 

GetMoviesError  (1-492) 

Returns  the  contents  of  the  current  error  value  and  resets  the  current  error 
value  to  0. 

GetMovi  esSti  ckyError  (I — 494) 

Returns  the  contents  of  the  sticky  error  value. 

Cl  earMovi  esSti  ckyError  (1-90) 

Clears  the  sticky  error  value. 

SetMoviesErrorProc  (III — 1 633) 

Performs  custom  error  notification. 

Callbacks 

MoviesErrorProc  (III — 2 109) 

An  error-notification  function,  called  each  time  the  current  error  value  is  to  be 
set  to  a  nonzero  value. 


Movie  Functions 


The  Movie  Toolbox  provides  a  set  of  functions  that  allow  your  application  to  create, 
access,  and  convert  movie  files.  Movie  files  contain  data  for  QuickTime  movies.  You 
can  also  use  the  Movie  Toolbox  to  load  movies  into  memory,  in  preparation  for 
working  with  the  movie.  These  functions  differ  based  on  where  the  movie  is  stored. 

Before  your  application  can  play  a  movie,  you  must  first  open  the  file  that  contains 
the  movie.  Your  application  can  use  OpenMovi  eFi  1  e  (11-1133)  to  open  a  movie  file. 
Once  you  are  done  with  the  file,  your  application  releases  the  file  by  calling 
Cl  oseMovi  eFi  1  e  (1-102).  Your  application  can  create  and  open  a  new  movie  file  by 
calling  CreateMovi  eFi  1  e  (1-145).  Your  application  can  delete  a  movie  file  by  calling 
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Del  eteMovi  eFi  1  e  (1-249). 

You  can  use  NewMovi  e  (11-1069)  to  create  a  new  empty  movie.  If  your  application  is 
loading  a  movie  from  an  existing  file,  use  either  NewMovi  eFromFi  1  e  (11-1080)  or 
NewMovi  eFromDataFork  (11-1075).  NewMovi  eFromFi  1  e  works  with  the  file  reference 
number  you  obtain  from  OpenMovi  eFi  1  e  (11-1133).  NewMovi eFromDataFork  (11-1075) 
works  with  movies  stored  in  your  document  file's  data  fork.  Your  application  can 
then  use  the  functions  described  in  "Saving  Movies"  (V-2715)  to  load  and  store 
movies. 

You  can  use  ConvertFileToMovieFile  (1-129)  to  specify  an  input  file  and  convert  it  to 
a  movie  file.  ConvertMovi  eToFi  1  e  (1-134)  takes  a  specified  movie  (or  a  single  track 
within  that  movie)  and  converts  it  into  an  output  file. 

Once  you  are  finished  working  with  a  movie,  you  should  release  the  resources  used 
by  the  movie  by  calling  Di  sposeMovi  e  (1-268). 


Functions 

NewMovi  eFromFi  1  e  (11-1080) 

Creates  a  new  movie  from  certain  file  types  that  do  not  contain  movie  resources 
(AIFF,  MPEG,  etc). 

NewMovi  eFromHandl  e  (11-1084) 

Creates  a  movie  in  memory  from  a  movie  resource  or  a  handle  you  obtained 
from  PutMovielntoHandl  e  (11-1151). 

NewMovi  e  (11-1069) 

Creates  a  new  movie  in  memory. 

NewMovi  eFromUserProc  (11-1087) 

Creates  a  movie  from  data  that  you  provide. 

NewMovi  eFromDataRef  (11-1078) 

Creates  a  movie  from  any  device  with  a  corresponding  data  handler. 
ConvertFileToMovieFile  (1-129) 

Converts  a  file  to  a  movie  file  and  supports  a  user  settings  dialog  box  for  import 
operations. 

ConvertMovi  eToFi  1  e  (1-134) 

Takes  a  specified  movie  (or  a  single  track  within  that  movie)  and  converts  it  into 
a  specified  file  and  type,  supporting  a  Save  As  dialog  box. 
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Di  sposeMovi  e  (1-268) 

Frees  any  memory  being  used  by  a  movie,  including  the  memory  used  by  the 
movie's  tracks  and  media  structures. 

CreateMovi eFi  1  e  (1-145) 

Creates  a  movie  file,  creates  an  empty  movie  which  references  the  file,  and 
opens  the  movie  file  with  write  permission. 

OpenMovI eFi  1  e  (11-1133) 

Opens  a  specified  movie  file. 

Cl  oseMovi  eFi  1  e  (1-102) 

Closes  an  open  movie  file. 

Del  eteMovi  eFi  1  e  (1-249) 

Deletes  a  movie  file. 
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Saving  Movies 

The  Movie  Toolbox  provides  a  set  of  high-level  functions  for  storing  movies  within 
files.  These  files  have  a  file  type  of  ’  MooV  ’  and  a  resource  type  of  ’  moov  ’  Your 
application  can  gain  access  to  existing  movies  with  either  NewMovi  eFromFi  1  e 
(11-1080)  or  NewMovi  eFromData  Fork  (11-1075).  Once  you  have  loaded  the  movie,  your 
application  uses  the  functions  described  below  to  save  any  changes  you  have  made 
to  the  movie. 

You  can  use  AddMovi  eResource  (1-36)  to  add  a  new  movie  resource  to  a  movie  file. 
Your  application  can  use  this  function  to  save  a  movie  that  it  created  using  the 
functions  described  in  "Editing  Movies"  (V-2746).  You  can  use  the 
UpdateMovi  eResource  (III— 1983)  function  to  replace  an  existing  movie  resource  in  a 
movie  file.  You  can  remove  a  movie  resource  by  calling  the  RemoveMovi  eResource 
(III— 1458)  function. 

The  movie  resources  that  your  application  creates  with  AddMovi  eResource  (1-36)  and 
UpdateMovi  eResource  (III— 1983)  may  contain  references  to  movie  data.  These 
references  identify  the  data  that  constitute  the  movie.  However,  the  movie  data  can 
be  stored  outside  of  the  movie  file.  If  you  want  to  create  a  movie  file  that  contains 
all  of  its  movie  data,  use  FI  attenMovi  e  (1-372)  or  FI  attenMovi  eData  (1-374).  These 
functions  can  also  be  used  to  store  the  movie  data  in  the  movie  file's  data  fork,  or  to 
interleave  the  media  data  to  optimize  performance. 

PutMovielntoHandle  (11-1151)  places  a  QuickTime  movie  into  a  handle.  You  can  then 
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convert  the  movie  into  specialized  data  formats. 


HasMovi  eChanged  (1-666)  and  Cl  earMovi  eChanged  (1-89)  allow  your  application  to 
work  with  the  movie  changed  flag  that  is  maintained  by  the  Movie  Toolbox.  You 
can  use  this  flag  to  determine  whether  a  movie  has  been  changed. 

The  movie  changed  flag  indicates  whether  you  have  changed  the  movie.  Such 
actions  as  editing  the  movie,  adding  samples  to  a  media,  or  changing  a  data 
reference  cause  the  flag  to  indicate  that  the  movie  has  changed.  There  are  several 
operations  that  the  movie  changed  flag  does  not  reflect,  including  changing  the 
volume,  rate,  or  time  settings  for  the  movie.  These  settings  change  frequently  when 
a  movie  is  played.  Your  application  must  monitor  these  settings  itself. 

The  Movie  Toolbox  also  supplies  functions  for  storing  and  retrieving  movies  that 
are  stored  in  the  data  fork  of  a  file.  These  functions  provide  robust  data  reference 
resolution  and  improve  low  memory  performance.  NewMovi  eFromData  Fork  (11-1075) 
enables  you  to  retrieve  a  movie  that  is  stored  anywhere  in  the  data  fork  of  a  file.  You 
can  use  PutMovielntoDataFork  (II— 1 1 50)  to  store  an  atom  version  of  a  specified  movie 
in  the  data  fork  of  a  file. 


Functions 

HasMovi  eChanged  (1-666) 

Determines  whether  a  movie  has  changed  and  needs  to  be  saved. 

Cl  earMovi  eChanged  (1-89) 

Sets  the  movie  changed  flag  to  indicate  that  the  movie  has  not  been  changed. 
AddMovi eResource  (1-36) 

Adds  a  movie  resource  to  a  specified  resource  file. 

UpdateMovi  eResource  (III — 1 983) 

Replaces  the  contents  of  a  movie  resource  in  a  specified  movie  file. 

RemoveMovi  eResource  (III — 1458) 

Removes  a  movie  resource  from  a  specified  movie  file. 

PutMovi  elntoHandl  e  (II — 1151) 

Creates  a  new  movie  resource. 

FlattenMovie  (1-372) 

Creates  a  new  movie  file  containing  a  specified  movie. 

FI  attenMovi  eData  (1-374) 

Creates  a  new  movie  and  a  file  that  contains  all  the  movie  data. 
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NewMovi eFromDataFork  (11-1075) 

Retrieves  a  movie  that  is  stored  anywhere  in  the  data  fork  of  a  specified 
Macintosh  file. 

PutMovielntoDataFork  (11-1150) 

Stores  a  movie  in  the  data  fork  of  a  given  file. 


Controlling  Movie  Playback 

A  number  of  high-level  functions  provided  by  the  Movie  Toolbox  allow  your 
application  to  play  movies. 

You  can  use  the  StartMovi  e  (III— 1911)  and  StopMovi  e  (III— 1914)  functions  to  start  and 
stop  movies.  You  can  use  GoToBegi  nni  ngOfMovi  e  (1-550)  and  GoToEndOfMovi  e  to  set 
the  position  at  either  the  beginning  or  the  end  of  a  movie. 
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Functions 

StartMovi e  (III — 1911) 

Starts  the  movie  playing  from  the  current  movie  time. 

StopMovi e  (III — 1 914) 

Stops  the  playback  of  a  movie. 

GoToBegi  nni  ngOfMovi  e  (1-550) 

Repositions  a  movie  to  play  from  its  start. 

GoToEndOfMovie  (1-551) 

Repositions  a  movie  to  play  from  its  end. 

See  Also 

For  information  about  how  to  control  a  movie's  playback  rate,  see  "Working  With 
Movie  Time"  (V-2732).  Functions  that  work  with  time  bases,  such  as 
SetMovi  eTi  meVai  ue  (III— 1635)  and  Ge t Mo vi eTi meScal e  (I — 496),  can  be  used  to  control 
the  current  position  anywhere  within  a  movie. 


Using  the  Full  Screen 

Two  functions  let  you  put  a  device  into  full-screen  mode  (that  is,  select  where  and 
when  the  menu  bar  is  not  visible). 

These  functions  are  listed  below. 
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Functions 


Begi nFul  1  Screen  (1-52) 

Begins  full-screen  mode  for  a  specified  monitor. 
EndFul  1  Screen  (1-314) 

Ends  full-screen  mode  for  a  graphics  device. 


Controlling  Hardware  Scaling 

Three  functions  that  allow  applications  to  zoom  a  monitor.  These  functions  are 
considered  low-level  calls  that  you  should  use  only  when  playing  back  QuickTime 
movies  in  a  controlled  environment  with  no  user  interaction.  Also,  because  this 
capability  is  not  present  on  all  computers,  applications  should  not  depend  on  its 
availability. 

These  functions  are  listed  below. 


Functions 

GDHasScal  e  (1-381) 

Returns  the  closest  possible  scaling  that  a  particular  screen  device  can  be  set  to 
in  a  given  pixel  depth. 

GDGetScal  e  (1-380) 

Returns  the  current  scale  of  the  given  screen  graphics  device. 

GDSetScal  e  (1-382) 

Sets  a  screen  graphics  device  to  a  new  scale. 


Movie  Posters  and  Movie  Previews 


A  QuickTime  movie  may  contain  a  preview  and  a  poster.  A  movie  preview  is  a  very 
short  version  of  a  movie,  typically  less  than  five  seconds  in  duration.  The  preview 
is  intended  to  give  the  user  an  idea  of  a  movie's  contents.  A  movie  poster  is  a  still 
frame  representing  the  movie. 

Use  PI  ayMovi  ePrevi  ew  (11-1140)  to  display  a  movie's  preview.  PI  ayMovi  ePrevi  ew 
(II— 1 140)  sets  the  movie  into  preview  mode,  plays  the  movie  preview,  sets  the  movie 
back  to  normal  playback  mode,  and  returns  to  your  application. 

Alternatively,  your  application  can  control  the  playback  of  a  movie's  preview.  Use 
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SetMovi  ePrevi  ewMode  (III— 1628)  to  place  a  movie  into  preview  mode.  You  can  then 
use  StartMovi  e  (III— 191 1)  and  StopMovi  e  (III— 1914)  to  control  movie  playback.  Your 
application  can  find  out  if  a  movie  is  in  preview  mode  by  calling 
GetMovi ePrevi ewMode  (1-487). 

Your  application  can  specify  the  starting  time  and  duration  of  the  movie  preview 
with  SetMovi  ePrevi  ewTime  (III — 1629)  and  GetMoviePreviewTime. 

Use  ShowMovi  ePoster  (III— 1827)  to  display  a  movie's  poster.  You  can  work  with  the 
poster's  boundary  rectangle  using  Set  Poster  Box  (III— 1638)  and  Get  Poster  Box  (1-505). 
Your  application  can  work  with  the  starting  time  of  the  poster  with 
SetMovi  ePosterTime  (III— 1625)  and  GetMovi  ePosterTi me.  Posters  always  have  no 
duration. 

Tracks  may  be  specified  for  use  in  the  movie,  its  preview,  its  poster,  or  any 
combination  of  the  three.  So,  for  example,  when  the  Movie  Toolbox  plays  the  movie 
preview  it  uses  only  those  tracks  that  are  assigned  to  the  preview.  Your  application 
controls  the  use  of  a  movie's  tracks  with  SetT rackUsage  (III— 1668).  You  can  find  out 
how  a  track  is  used  by  calling  GetT rackUsage  (1-545). 


SUM 


Functions 

SetTrackUsage  (III — 1 668) 

Specifies  whether  a  track  is  used  in  a  movie,  its  preview,  its  poster,  or  a 
combination  of  these. 

GetTrackUsage  (1-545) 

Determines  whether  a  track  is  used  in  a  movie,  its  preview,  its  poster,  or  a 
combination  of  these. 

ShowMovi  ePoster  (III — 1827) 

Displays  a  movie's  poster. 

SetPosterBox  (III — 1 638) 

Sets  a  poster's  boundary  rectangle. 

GetPosterBox  (1-505) 

Obtains  a  poster's  boundary  rectangle. 

SetMoviePosterTime  (III — 1 625) 

Sets  the  poster  time  for  the  movie. 

GetMoviePosterTime  (1-485) 

Returns  the  poster's  time  in  a  movie. 
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PI  ayMovi  ePrevi  ew  (11-1140) 

Plays  a  movie's  preview. 

SetMovi  ePrevi  ewMode  (III — 1 628) 

Places  a  movie  into  and  out  of  preview  mode. 

GetMovi  ePrevi  ewMode  (1-487) 

Determines  whether  a  movie  is  in  preview  mode. 

SetMoviePreviewTime  (III — 1 629) 

Defines  the  starting  time  and  duration  of  the  movie's  preview. 
GetMoviePreviewTime  (1-487) 

Returns  the  starting  time  and  duration  of  the  movie's  preview. 


Movies  and  Your  Event  Loop 

The  Movie  Toolbox  supplies  several  functions  that  your  application  normally  calls 
from  its  main  event  loop. 

In  order  for  your  movies  to  play,  your  application  must  grant  time  to  the  Movie 
Toolbox.  You  do  this  by  calling  Movi  esTask  (11-973)  from  your  main  event  loop. 
Movi  esTask  (11-973)  causes  the  Movie  Toolbox  to  service  all  your  active  movies.  You 
should  call  this  function  regularly  so  that  your  movie  can  play  smoothly.  You  can 
use  UpdateMovie  (III— 1981)  to  force  your  movie  to  be  redrawn  after  it  has  been 
uncovered. 

You  may  want  your  application  to  take  a  particular  action  when  a  movie  is  done 
playing.  The  Movie  Toolbox  provides  IsMovi  eDone  (11-774),  which  allows  you  to 
determine  whether  a  movie  is  done  playing. 

The  Movie  Toolbox  provides  two  functions  that  allow  your  application  to 
determine  whether  a  specified  point  lies  in  either  a  movie  or  a  track.  Use  PtlnMovi  e 
(11-1148)  with  movies;  use  PtlnTrack  (11-1149)  with  tracks. 

Your  application  can  retrieve  some  status  information  about  movies  and  tracks.  Use 
GetMovi  eStatus  (1-494)  to  retrieve  movie  status;  use  GetT rackStatus  (1-544)  to  get 
track  status. 


Functions 


Movi  esTask  (11-973) 

Services  active  movies. 
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IsMovi  eDone  (11-774) 

Determines  if  a  particular  movie  has  completely  finished  playing. 

UpdateMovie  (III — 1 981 ) 

Ensures  that  the  Movie  Toolbox  properly  displays  your  movie  after  it  has  been 
uncovered. 

Inval  i  dateMovi  eRegi  on  (11-771) 

Invalidates  a  small  area  of  a  movie. 

PtlnMovie  (11-1148) 

Determines  whether  a  specified  point  lies  in  the  region  defined  by  a  movie's 
final  display  boundary  region  after  it  has  been  clipped  by  the  movie's  display 
clipping  region. 

PtlnTrack  (11-1149) 

Determines  whether  a  specified  point  lies  in  the  region  defined  by  a  track's 
display  boundary  region  after  it  has  been  clipped  by  the  movie's  final  display 
clipping  region. 

GetMovi eStatus  (1-494) 

Searches  for  errors  in  all  the  enabled  tracks  of  the  movie  and  returns 
information  about  errors  that  are  encountered  during  the  processing  associated 
with  the  Movi  esTask  function. 

GetTrackStatus  (1-544) 

Returns  the  value  of  the  last  error  the  media  encountered  while  playing  a 
specified  track. 

See  Also 

The  Movie  Toolbox  also  provides  more  sophisticated  callback  mechanisms,  which 
are  discussed  in  "Time  Base  Callback  Functions"  (V-2763). 
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Preferred  Movie  Settings 

Every  movie  has  default,  or  preferred,  settings  for  playback  rate  and  volume.  These 
settings  are  stored  with  the  movie  in  its  movie  file.  The  Movie  Toolbox  provides 
functions  that  allow  your  application  to  manipulate  these  default  settings. 

You  can  use  GetMovi  ePreferredRate  (1-485)  and  SetMovi  ePreferredRate  to  work 
with  a  movie's  default  playback  rate.  You  can  use  GetMovi ePreferredVol  ume  (1-486) 
and  SetMovi  ePreferredVol  ume  to  work  with  the  default  sound  volume  of  a  movie. 
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Functions 


GetMovi  ePreferredRate  (1-485) 

Returns  a  movie's  default  playback  rate. 

SetMovi  ePreferredRate  (III — 1 626) 

Specifies  a  movie's  default  playback  rate. 

GetMovi  ePreferredVol  ume  (1-486) 

Returns  a  movie's  preferred  volume  setting. 

SetMovi  ePreferredVol  ume  (III — 1627) 

Sets  a  movie's  preferred  volume  setting. 

See  Also 

You  can  use  SetMovi  eRate  to  change  a  movie's  playback  rate.  The  Movie  Toolbox 
also  provides  a  number  of  functions  that  allow  you  to  change  other  settings  when 
you  play  a  movie.  They  are  discussed  in  "Modifying  Movie  Properties"  (V-2728). 


Enhancing  Movie  Playback  Performance 

There  are  circumstances  in  which  an  application  needs  to  optimize  the  performance 
of  a  movie  or  a  portion  of  a  movie.  The  Movie  Toolbox  provides  several  functions 
to  help  in  this  process. 

The  first  step  you  can  take  to  enhance  movie  playback  performance  is  to  allow  the 
Movie  Toolbox  to  preroll  the  movie.  When  the  toolbox  prerolls  a  movie,  it  informs 
the  media  handlers  that  the  movie  is  about  to  play.  The  media  handlers  can  then 
load  the  appropriate  movie  data.  In  this  manner,  the  movie  can  play  smoothly  from 
the  start.  Use  Prerol  1  Movi  e  (11-1142)  to  preroll  a  movie. 

The  next  performance  enhancement  technique  is  to  load  portions  of  a  movie,  track, 
or  media  into  memory,  thus  reducing  or  eliminating  disk  access  during  playback. 
Loading  the  movie  into  RAM  provides  most  noticeable  performance  improvements 
when  there  is  a  lot  of  random  access  involved  in  the  playback  process  and  the  entire 
movie  fits  into  available  memory.  Use  LoadMovi  elntoRam  (11-781),  LoadT racklntoRam, 
and  LoadMedi  alntoRam  (11-779)  to  copy  all  or  part  of  a  movie  into  memory.  These 
functions  load  tracks  into  memory  in  a  time-slice  order  so  that,  if  a  function  fails 
because  it  is  out  of  memory,  all  tracks  are  left  loaded  to  about  the  same  point  in  time. 

You  can  influence  the  temporal  accuracy,  and  therefore  the  speed,  with  which  the 
Movie  Toolbox  tries  to  display  a  movie  by  calling  either  SetMovi  ePl  ay  Hi  nts 
(III — 1623)  or  SetMedi  aPl  ayHi  nts. 
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For  each  movie  currently  in  use,  the  Movie  Toolbox  maintains  an  active  movie 
segment.  The  active  movie  segment  is  the  part  of  the  movie  that  your  application  is 
interested  in  playing.  By  default,  the  active  movie  segment  is  set  to  be  the  entire 
movie.  You  may  wish  to  change  this  to  be  some  segment  of  the  movie;  for  example, 
if  you  wish  to  play  a  user's  selection  repeatedly.  By  setting  the  active  movie  segment 
you  guarantee  that  the  Movie  Toolbox  uses  no  samples  from  outside  of  that  range 
while  playing  the  movie.  Use  GetMovi  eActi  veSegment  (1-457)  and 
SetMovi  eActi  veSegment  to  work  with  the  active  segment. 

Some  movies  contain  very  few  key  frames  and  a  great  number  of  frame  differences. 
These  movies  play  back  very  well  because  they  have  a  lower  data  rate. 
Unfortunately,  this  makes  random  access  operations  on  a  movie,  such  as  scrubbing, 
difficult.  To  improve  random  access  performance  of  movies  with  few  key  frames 
and  many  frame  differences,  shadow  sync  samples  may  be  added.  Shadow  sync 
samples  are  self-contained  samples  that  are  alternates  for  already  existing  frame 
difference  samples.  During  certain  random  access  operations,  a  shadow  sync 
sample  is  used  instead  of  a  normal  key  frame,  which  may  be  very  far  away  from  the 
desired  frame.  The  Movie  Toolbox  provides  two  functions  to  let  you  create  just  such 
an  association  between  a  frame  difference  sample  and  a  sync  sample. 

SetMedi  aShadowSync  (III— 1607)  establishes  a  shadow  sync  sample  for  a  media.  You 
can  use  GetMedi  aShadowSync  (1-453)  to  find  out  if  a  particular  frame  difference 
sample  has  a  shadow  sync  sample. 
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Functions 

Prerol  1  Movi e  (11-1142) 

Prepares  a  portion  of  a  movie  for  playback. 

PrePrerol  1  Movi e  (II — 1141) 

Sets  up  any  necessary  network  connections  to  receive  streaming  content. 

AbortPrePrerol  1  Movi e  (1-21) 

Terminates  the  operation  of  PrePrerol  1  Movi  e  (11-1141). 

LoadMovi elntoRam  (II — 7 81) 

Loads  a  movie's  data  into  memory. 

LoadTracklntoRam  (11-782) 

Loads  a  track's  data  into  memory. 

LoadMedi  alntoRam  (11-779) 

Loads  a  media's  data  into  memory. 
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SetMovi  ePl  ayHi  nts  (III — 1 623) 

Provides  information  to  the  Movie  Toolbox  that  can  influence  movie  playback. 
SetMedi  aPl  ayHi  nts  (III — 1 601) 

Provides  information  to  the  Movie  Toolbox  that  can  influence  playback  of  a 
single  media. 

GetMovi  eActi  veSegment  (1-457) 

Determines  what  portion  of  a  movie  is  currently  active  for  playing. 

SetMovi  eActi  veSegment  (III — 1 609) 

Defines  a  movie's  active  segment. 

SetMedi aShadowSync  (III — 1607) 

Creates  an  association  between  the  indicated  frame  difference  sample  and  a 
specified  self-contained  sample  in  a  given  media. 

GetMedi aShadowSync  (1-453) 

Returns  the  sample  number  of  the  shadow  sync  sample  associated  with  a  given 
frame  difference  sample  number. 

SetTrackLoadSetti ngs  (III — 1 661) 

Specifies  a  portion  of  a  track  that  is  to  be  loaded  into  memory  whenever  it  is 
played. 

GetTrackLoadSetti ngs  (1-532) 

Retrieves  a  track's  preload  information. 

GetTrackDi  spl  ayMatri  x  (1-528) 

Returns  a  matrix  that  is  the  concatenation  of  all  matrices  currently  affecting  the 
track's  location,  scaling,  and  so  on,  including  the  movie's  matrix,  the  track's 
matrix,  and  the  modifier  matrix. 


Disabling  Movies  and  Tracks 

The  Movie  Toolbox  services  only  movies  and  tracks  that  are  active.  It  provides 
functions  that  allow  your  application  to  enable  and  disable  tracks  and  movies. 

You  can  use  SetMovi  eActi  ve  (III— 1609)  to  activate  and  deactivate  a  movie  and 
GetMovi  eActi  ve  (1-456)  to  determine  whether  a  movie  is  active.  Similarly,  your 
application  can  use  SetT rackEnabl  ed  (III— 1658)  to  enable  and  disable  a  track  and 
GetT rackEnabl  ed  (1-531)  to  determine  whether  a  track  is  enabled. 
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Functions 


SetMovi eActi ve  (III — 1 609) 

Activates  or  deactivates  a  movie. 

GetMovi  eActi  ve  (1-456) 

Determines  whether  a  movie  is  currently  active. 

SetTrackEnabl  ed  (III — 1 658) 

Enables  or  disables  a  track. 

GetTrackEnabl  ed  (1-531) 

Determines  whether  a  track  is  currently  enabled. 

See  Also 

The  Movie  Toolbox  also  allows  you  to  assign  alternate  tracks  based  on  language  or 
quality  criteria.  Functions  that  work  with  alternate  tracks  are  discussed  in 
"Working  With  Alternate  Tracks"  (V-2738). 
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Generating  Pictures  From  Movies 

The  Movie  Toolbox  provides  a  set  of  functions  that  allow  your  application  to  create 
QuickDraw  pictures  from  movies,  tracks,  and  posters. 

You  can  use  GetMovi  ePi  ct  (1-483)  to  create  a  picture  from  a  movie  or  its  preview; 
you  can  use  GetT rackPi  ct  (1-540)  to  create  a  picture  from  a  track. 

GetMovi  ePosterPi  ct  (1-484)  lets  you  create  a  picture  that  contains  a  movie's  poster. 
If  a  movie  or  track  has  no  spatial  representation,  the  returned  picture  is  empty  (that 
is,  the  upper-left  and  lower-right  coordinates  are  equal). 


Functions 

GetMovi  ePi  ct  (1-483) 

Creates  a  QuickDraw  picture  from  a  specified  movie  at  a  specified  time. 
GetT  rackPi  ct  (1-540) 

Creates  a  QuickDraw  picture  from  a  specified  track  at  a  specified  time. 
GetMovi  ePosterPi  ct  (I — 484) 

Creates  a  QuickDraw  picture  that  contains  a  movie's  poster. 
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Creating  Tracks  and  Media  Structures 


The  Movie  Toolbox  provides  several  functions  that  allow  your  application  to  create 
new  movie  tracks  and  media  structures  and  to  dispose  of  existing  tracks  and  media 
structures.  You  use  these  functions  when  you  are  creating  a  new  movie  or  when  you 
are  editing  an  existing  movie. 

You  can  use  NewMovi  eTrack  (11-1092)  to  create  a  new  track  for  a  specified  movie. 
Conversely,  you  can  use  Di  sposeMovi  eT rack  (1-278)  to  dispose  of  an  existing  track. 
Your  application  can  create  a  new  media  for  a  track  by  calling  NewT rackMedi  a 
(11-1120).  You  can  use  Di  sposeT rackMedi  a  (1-301)  to  dispose  of  an  existing  media. 


Functions 

NewMovi  eT  rack  (11-1092) 

Creates  a  new  movie  track,  without  a  media. 

Di  sposeMovi  eTrack  (1-278) 

Removes  a  track  from  a  movie. 

NewTrackMedi a  (11-1120) 

Creates  a  media  for  a  new  track. 

Di sposeTrackMedi a  (1-301) 

Removes  a  media  from  a  track. 


Working  With  Progress  and  Cover  Functions 

The  Movie  Toolbox  allows  your  application  to  assign  two  types  of  custom 
functions:  progress  functions  and  cover  functions.  These  functions  allow  you  to 
perform  special  processing  under  certain  circumstances. 

Some  Movie  Toolbox  functions  can  take  a  long  time  to  execute.  For  example,  if  you 
call  FI  attenMovi  e  (1-372)  and  specify  a  large  movie,  the  Movie  Toolbox  must  read 
and  write  all  the  sample  data  for  the  movie.  During  such  operations  you  may  wish 
to  display  some  kind  of  progress  indicator  to  the  user.  A  progress  function  is  an 
application-defined  function  that  you  can  use  to  track  the  progress  of 
time-consuming  activities,  and  thereby  keep  the  user  informed  about  that  progress. 
The  Movie  Toolbox  calls  your  progress  function  at  regular  intervals  during  long 
operations.  The  Movie  Toolbox  determines  whether  to  call  your  function  based  on 
the  duration  of  the  operation;  your  function  will  not  be  called  unnecessarily.  When 
it  calls  your  function,  the  Movie  Toolbox  provides  information  about  the  operation 
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that  is  underway  and  its  relative  completion.  You  can  use  this  information  to 
display  an  informational  dialog  box  to  the  user. 

The  Movie  Toolbox  allows  your  application  to  perform  custom  processing 
whenever  one  of  your  movie's  tracks  covers  a  screen  region  or  reveals  a  region  that 
was  previously  covered.  You  perform  this  processing  in  cover  functions.  There  are 
two  types  of  cover  functions:  those  that  are  called  when  your  movie  covers  a  screen 
region,  and  those  that  are  called  when  your  movie  uncovers  a  screen  region  that 
was  previously  covered.  Cover  functions  that  are  called  when  your  movie  covers  a 
screen  region  are  responsible  for  erasing  the  region;  you  may  choose  to  save  the 
hidden  region  in  an  offscreen  buffer.  Cover  functions  that  are  called  when  your 
movie  reveals  a  hidden  screen  region  must  redisplay  the  hidden  region.  The  Movie 
Toolbox  sets  the  graphics  world  before  it  calls  your  cover  function;  your  function 
must  not  change  the  graphics  world.  Note  that  the  Movie  Toolbox  does  not  call  your 
cover  function  in  response  to  changes  to  the  movie's  transformation  matrix. 

The  SetMovi  eProgressProc  (III— 1630)  function  helps  your  application  work  with 
progress  functions  and  the  SetMovi  eCoverProcs  (III— 1614)  function  helps  your 
application  work  with  cover  functions.  You  should  assign  your  progress  function 
when  you  open  the  movie;  the  Movie  Toolbox  will  call  your  function  when  it  is 
appropriate  to  do  so.  One  progress  function  may  support  more  than  one  movie. 
When  the  Movie  Toolbox  calls  your  function,  it  provides  you  with  the  movie 
identifier  so  that  you  can  discriminate  between  various  movies. 
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Functions 

SetMovieProgressProc  (III — 1 630) 

Attaches  a  progress  function  to  a  movie. 

SetMovi  eCoverProcs  (III — 1 614) 

Sets  the  callbacks  invoked  when  a  movie  is  covered  or  uncovered. 
GetMovi eCoverProcs  (1-464) 

Retrieves  the  cover  functions  that  you  set  with  the  SetMovi  eCoverProcs 
function. 

SetMovi  eDrawi  ngCompi  eteProc  (III — 1617) 

Assigns  a  drawing-complete  function  to  a  movie. 

Callbacks 

MovieProgressProc  (III — 2 105) 

Monitors  the  progress  of  the  Movie  Toolbox  during  long  operations. 
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Movi  eDrawi  ngCompl  eteProc  (III — 2100) 

Called  when  movie  drawing  is  complete. 

See  Also 

The  Movie  Toolbox  provides  default  cover  functions.  When  your  movie  uncovers  a 
region,  the  default  function  that  is  called  erases  the  movie's  image  by  displaying  the 
graphics  port's  background  color  and  pattern.  You  can  set  the  port's  characteristics 
by  calling  SetMovi  eGWorl  d.  When  your  movie  covers  a  region,  the  default  function 
that  is  called  does  nothing. 


Modifying  Movie  Properties 


The  Movie  Toolbox  provides  a  number  of  functions  that  allow  applications  to  edit 
existing  movies  or  to  create  the  contents  of  new  movies. 


Working  With  Movie  Spatial  Characteristics 

The  Movie  Toolbox  provides  a  number  of  functions  that  allow  your  application  to 
determine  and  change  the  display  characteristics  of  movies  and  tracks. 

Your  application  can  work  with  a  movie's  matrix  by  calling  Get  Movi  eMatrix  (1-478) 
and  SetMovi  eMatri  x  (III— 1622),  and  it  can  work  with  a  track's  matrix  with 
GetT rackMatri  x  (1-533)  SetTrackMatri  x.  Then  you  can  perform  operations  on 
matrixes  with  the  Movie  Toolbox's  matrix  functions  described  in  "Working  With 
Matrices"  (V-2764). 

Several  functions  affect  the  displayed  movie  and  its  tracks  in  the  final  display 
coordinate  system.  SetMovi  eGWorl  d  (III— 1619)  and  GetMovi  eGWorl  d  (1-471)  let  you 
work  with  a  movie's  display  destination.  GetMovi  eBox  (1-460)  and  SetMovi  eBox 
(III— 1611)  allow  you  to  work  with  a  movie's  boundary  rectangle  and  its  associated 
transformations.  Alternatively,  you  can  work  directly  with  a  movie's 
transformation  matrix.  GetMovi  eDi  spl  ayBoundsRgn  (1-468)  determines  a  movie's 
boundary  region  at  the  current  movie  time.  On  the  other  hand, 

GetMovi  eSegmentDi  spl  ayBoundsRgn  (1-490)  determines  a  movie's  boundary  region 
over  a  specified  time  segment.  You  can  use  GetMovi  eDi  spl  ayCl  i  pRgn  (1-469)  and 
SetMovi  eDi  spl  ayCl  i  pRgn  to  work  with  a  movie's  display  clipping  region. 
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GetT  rackDispl  ay  Bounds  Rgn  (1-528)  and  GetT  rackSegmentDi  splay  Bounds  Rgn  determine 

a  track's  final  boundary  region.  You  can  use  GetT rackLayer  (1-532)  and 

SetT rackLayer  (III— 1660)  to  control  the  drawing  order  of  tracks  within  a  movie. 

A  number  of  functions  affect  a  movie's  display  boundaries  before  any  display 
transformations;  these  functions  operate  in  the  movie's  display  coordinate  system. 
You  can  use  GetMovi  eCl  i  pRgn  (1-462)  and  SetMovi  eCl  i  pRgn  (III— 1612)  to  work  with  a 
movie's  clipping  region  (that  is,  the  clipping  region  that  is  applied  before  the  movie 
display  transformation).  Use  GetMovi  eBoundsRgn  (1-459)  to  determine  a  movie's 
boundary  region  at  the  current  movie  time. 


SUM 


Use  GetTrackMovi  eBoundsRgn  (1-537)  to  work  with  a  track's  boundary  region  after 
matrix  transformations  have  placed  the  track  into  the  movie's  display  system. 

The  Movie  Toolbox  provides  several  functions  that  affect  a  track's  display 
boundaries;  these  functions  operate  in  the  track's  display  coordinate  system  before 
any  other  display  transformations  are  applied.  GetT rackDi mensi  ons  (1-527)  and 
SetT  rackDi  mensi  ons  allow  you  to  establish  a  track's  coordinate  system  and  to 
establish  a  track's  source  rectangle.  A  track's  source  rectangle  defines  the  coordinate 
system  of  the  track.  You  specify  the  dimensions  of  the  rectangle  by  providing  the 
coordinates  of  the  lower-right  corner  of  the  rectangle.  The  Movie  Toolbox  sets  the 
upper-left  comer  to  (0,0)  in  the  track's  coordinate  system. 

You  can  use  GetT rackBoundsRgn  (1-523)  to  determine  a  track's  boundary  region. 
GetT rackCl  i  pRgn  (1-524)  and  SetTrackCl  i  pRgn  (III— 1656)  let  you  work  with  a  track's 
clipping  region. 

You  can  use  GetT rackMatte  (1-534)  and  SetT rackMatte  (III— 1663)  to  establish  a  track's 
matte.  Di  sposeMatte  (1-267)  function  allows  you  to  dispose  of  a  matte  once  you  are 
finished  with  it. 


Functions 

GetMovi  eMatri x  (1-478) 

Retrieves  a  movie's  transformation  matrix. 

SetMovi  eMatri  x  (III — 1 622) 

Sets  a  movie's  transformation  matrix. 

GetTrackMatrix  (1-533) 

Retrieves  a  track's  transformation  matrix. 
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SetTrackMatri  x  (III — 1 662) 

Establishes  a  track's  transformation  matrix. 

SetMovi  eGWorl  d  (III — 1 619) 

Establishes  a  movie's  display  coordinate  system  by  setting  the  graphics  world 
for  displaying  the  movie. 

GetMovi  eGWorl  d  (1-471) 

Returns  a  movie's  graphics  world. 

GetMovi  eBox  (1-460) 

Returns  a  movie's  boundary  rectangle,  which  is  a  rectangle  that  encompasses 
all  of  the  movie's  enabled  tracks. 

SetMovi  eBox  (III — 1 611) 

Sets  a  movie's  boundary  rectangle. 

GetMovi  eDi  spl  ayBoundsRgn  (1-468) 

Determines  a  movie's  display  boundary  region. 

GetMovi  eSegmentDi  spl  ayBoundsRgn  (1-490) 

Determines  a  movie's  display  boundary  region  for  a  specified  segment. 

GetMovi  eDi  spl  ayCl  i  pRgn  (1-469) 

Determines  a  movie's  current  display  clipping  region. 

SetMovi  eDi  spl  ayCl  i  pRgn  (III — 1 616) 

Establishes  a  movie's  current  display  clipping  region. 

SetMovi  eCol  orTabl  e  (III — 1 613) 

Associates  a  Col  orTabl  e  (IV-2210)  structure  with  a  movie. 

GetMovi  eCol  orTabl  e  (1-463) 

Retrieves  a  movie's  color  table. 

GetTrackDi  spl  ayBoundsRgn  (1-528) 

Determines  the  region  a  track  occupies  in  a  movie's  graphics  world. 

GetT rackSegmentDi  spl  ayBoundsRgn  (1-542) 

Determines  the  region  a  track  occupies  in  a  movie's  graphics  world  during  a 
specified  segment. 

GetTrackLayer  (1-532) 

Retrieves  a  track's  layer. 

SetTrackLayer  (III — 1 660) 

Sets  a  track's  layer. 
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GetMovi  eCl  i  pRgn  (1-462) 

Determines  a  movie's  clipping  region. 

SetMovi  eCl  i  pRgn  (III — 1 612) 

Establishes  a  movie's  clipping  region. 

GetMovieBoundsRgn  (1-459) 

Determines  a  movie's  boundary  region. 

GetTrackMovieBoundsRgn  (1-537) 

Determines  the  region  the  track  occupies  in  a  movie's  boundary  region. 

GetTrackDimensi ons  (1-527) 

Determines  a  track's  source  rectangle. 

SetTrackDimensi  ons  (III — 1 657) 

Establishes  a  track's  source  rectangle. 

GetTrackBoundsRgn  (1-523) 

Lets  the  media  limit  the  size  of  a  track  boundary  rectangle. 

GetT rackCl  i  pRgn  (1-524) 

Determines  the  clipping  region  of  a  track. 

SetT rackCl  i  pRgn  (III — 1 656) 

Sets  the  clipping  region  of  a  track. 

GetTrackMatte  (I — 534) 

Retrieves  a  copy  of  a  track's  matte. 

SetTrackMatte  (III — 1 663) 

Sets  a  track's  matte. 

Di  sposeMatte  (1-267) 

Disposes  of  a  matte  obtained  from  the  GetT rackMatte  (1-534)  function. 
SetTrackGWorl  d  (III — 1 659) 

Forces  a  track  to  draw  into  a  particular  graphics  world,  which  may  be  different 
from  that  of  the  movie. 

See  Also 

Before  using  any  of  these  functions,  you  should  be  familiar  with  the  way  in  which 
the  Movie  Toolbox  displays  movies.  For  this  information,  see  Inside  QuickTime: 
Interactive  Movies  (listed  in  the  bibliography).  Also  see  Inside  Macintosh:  Imaging 
With  QnickDraiv  (listed  in  the  bibliography)  for  detailed  information  about 
graphics  worlds. 
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Working  With  Sound  Volume 


The  Movie  Toolbox  allows  you  to  set  the  sound  volume  of  movies  and  tracks.  Track 
volumes  allow  tracks  within  a  movie  to  have  different  volumes.  A  track's  volume  is 
scaled  by  the  movie's  volume  to  produce  the  track's  final  volume.  Finally,  the 
movie's  volume  is  scaled  by  the  user's  sound  volume  controls. 

Volume  values  range  from  -1.0  to  +1.0.  Higher  values  translate  to  louder  volume. 
Negative  values  indicate  muted  volume.  That  is,  the  Movie  Toolbox  does  not  play 
any  sound  for  movies  or  tracks  with  negative  volume  settings,  but  the  original 
volume  level  is  retained  as  the  absolute  value  of  the  volume  setting.  Therefore,  if 
you  want  to  toggle  the  current  state  of  the  volume,  you  can  invert  the  sign  of  the 
current  volume  setting. 

You  can  use  GetMovi  eVol  ume  (1-500)  and  SetMovi  eVol  ume  (III— 1637)  to  work  with  a 
movie's  volume.  GetT rackVol  ume  (1-547)  and  SetT rackVol  ume  (III— 1669)  allow  you  to 
work  with  a  track's  volume. 


Functions 

GetMovi  eVol  ume  (1-500) 

Returns  a  movie's  current  volume  setting. 

SetMovi  eVol  ume  (III — 1 637) 

Sets  a  movie's  current  volume. 

GetT  rackVol  ume  (1-547) 

Returns  a  track's  current  volume  setting. 

SetT  rackVol  ume  (III — 1 669) 

Sets  a  track's  current  volume. 


Working  With  Movie  Time 

Every  QuickTime  movie  has  its  own  time  base.  A  movie's  time  base  allows  all  the 
tracks  that  make  up  the  movie  to  be  synchronized  when  the  movie  is  played.  The 
Movie  Toolbox  provides  a  number  of  functions  that  allow  your  application  to 
determine  and  establish  the  time  parameters  of  a  movie. 

You  can  use  GetMovi  eT i meBase  (1-496)  to  retrieve  the  time  base  for  a  movie.  You  can 
work  with  a  movie's  current  time  by  calling  GetMovi  eT i  me  (1-495),  SetMovi  eT i  me 
(III— 1634),  and  SetMovi  eT i  meVal  ue  (III— 1635).  You  can  work  with  a  movie's  time 
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scale  by  calling  GetMovi  eT i meScal  e  (1-496)  and  SetMovi  eT i meScal  e  (III— 1635). 

The  Movie  Toolbox  can  calculate  the  total  duration  of  a  movie;  use 
GetMovi  eDurati  on  (1-470)  to  retrieve  a  movie's  duration. 

Your  application  can  call  GetMovi  eRate  (1-490)  and  SetMovi  eRate  (III— 1631)  to  work 
with  a  movie's  playback  rate. 


Functions 

GetMovieTimeBase  (1-496) 

Returns  a  movie's  time  base. 

GetMovi eTi me  (1-495) 

Returns  a  movie's  current  time  both  as  a  time  value  and  in  a  time  structure. 

SetMovieTime  (III — 1 634) 

Changes  a  movie's  current  time. 

SetMovi  eTi  meVai  ue  (III — 1 635) 

Sets  a  movie's  time  value. 

GetMovi  eTi  meScal  e  (1-496) 

Returns  the  time  scale  of  a  movie. 

SetMovi  eTi  meScal  e  (III — 1 635) 

Establishes  a  movie's  time  scale. 

GetMovi  eDurati  on  (1-470) 

Returns  the  duration  of  a  movie. 

GetMovi  eRate  (1-490) 

Returns  a  movie's  playback  rate. 

SetMovi  eRate  (III — 1 631) 

Sets  a  movie's  playback  rate. 

See  Also 

See  also  "Working  With  Track  Time"  (V-2733)  and  "Working  With  Media  Time" 
(V-2735). 
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Working  With  Track  Time 

The  Movie  Toolbox  provides  several  functions  that  allow  your  application  to 
determine  and  establish  a  track's  time  parameters.  A  track  uses  the  time  base  of  the 
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movie  that  contains  the  track;  therefore  there  are  no  functions  that  work  with  a 
track's  time  base  or  time  scale.  However,  you  can  determine  a  track's  duration  and 
its  offset  from  the  start  of  a  movie. 

All  of  the  tracks  in  a  movie  use  the  movie's  time  coordinate  system.  That  is,  the 
movie's  time  scale  defines  the  basic  time  unit  for  each  of  the  movie's  tracks.  Each 
track  begins  at  the  beginning  of  the  movie,  but  the  track's  data  might  not  begin  until 
some  time  value  other  than  0.  This  intervening  time  is  represented  by  blank  space. 
In  an  audio  track  the  blank  space  translates  to  silence;  in  a  video  track  the  blank 
space  generates  no  visual  image.  This  blank  space  is  the  track  offset.  Each  track  has 
its  own  duration.  This  duration  need  not  correspond  to  the  duration  of  the  movie. 
A  movie  duration  always  equals  the  maximum  track  duration. 

You  can  use  GetTrackDurati  on  (1-529)  to  determine  a  track's  duration. 
SetTrackOffset  (III— 1664)  and  GetTrackOffset  (1-539)  enable  you  to  work  with  a 
track's  offset  from  the  start  of  the  movie  that  contains  it.  TrackTi  meToMedi  a  Time 
(III— 1951)  lets  you  translate  a  track's  time  to  the  corresponding  time  value  of  a 
media  in  the  track. 


Functions 

GetTrackDurati  on  (1-529) 

Returns  the  duration  of  a  track. 

SetTrackOffset  (III — 1 664) 

Modifies  the  duration  of  the  empty  space  that  lies  at  the  beginning  of  a  track, 
thus  changing  the  duration  of  the  entire  track. 

GetTrackOffset  (1-539) 

Determines  the  time  difference  between  the  start  of  a  track  and  the  start  of  the 
movie  that  contains  the  track. 

TrackT i meToMedi aTi me  (III — 1 951) 

Converts  a  track's  time  value  to  a  time  value  that  is  appropriate  to  the  track's 
media,  using  the  track's  edit  list. 

See  Also 

See  also  "Working  With  Movie  Time"  (V-2732)  and  "Working  With  Media  Time" 
(V-2735). 
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Working  With  Media  Time 


The  Movie  Toolbox  provides  functions  that  allow  your  application  to  work  with  the 
ti  me  parameters  of  a  media. 

You  can  use  GetMedi  aDurati  on  (1-430)  to  determine  a  media's  duration. 

GetMedi  aT i meScal  e  (1-455)  and  SetMedi  aT i meScal  e  (III— 1608)  let  you  determine  or 
establish  a  media's  time  scale. 


Functions 

GetMedi  aDurati  on  (1-430) 

Returns  the  duration  of  a  media. 

GetMedi  aTimeScal  e  (1-455) 

Determines  a  media's  time  scale. 

SetMedi  aTimeScal  e  (III — 1 608) 

Sets  a  media's  time  scale. 

See  Also 

See  also  "Working  With  Track  Time"  (V-2733)  and  "Working  With  Movie  Time" 
(V-2732). 
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Finding  Interesting  Times 

The  Movie  Toolbox  provides  a  set  of  functions  that  help  you  locate  samples  in 
movies,  tracks,  and  media  structures.  These  functions  are  based  on  the  concept  of 
interesting  times.  An  interesting  time  refers  to  a  time  value  in  a  movie,  track,  or 
media  that  meets  certain  search  criteria.  You  specify  the  search  criteria  to  the  Movie 
Toolbox.  The  Movie  Toolbox  then  scans  the  movie,  track,  or  media,  and  locates  time 
values  that  meet  those  search  criteria.  You  can  use  these  functions  to  search  through 
image  sequences.  For  example,  you  may  want  to  locate  each  frame  in  an  image 
sequence.  Or  you  may  be  more  interested  in  key  frames,  especially  if  you  are  trying 
to  optimize  display  performance.  An  easy  way  to  determine  whether  a  movie  has 
been  edited  is  to  look  for  track  edits  in  the  movie  data.  You  may  also  be  interested 
in  searching  for  samples  in  a  movie's  media.  If  you  set  the  appropriate  search 
criteria,  the  Movie  Toolbox  locates  the  appropriate  frames  for  you.  You  need  the 
functions  described  in  this  section  because  QuickTime  doesn't  have  a  fixed  rate. 
Each  frame  can  have  its  own  duration. 

The  Movie  Toolbox  identifies  an  interesting  time  by  specifying  its  starting  time  and 
duration.  The  starting  time  indicates  the  time  in  the  movie,  track,  or  media  where 
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the  search  criteria  are  met.  The  duration  indicates  the  length  of  time  during  which 
the  search  criteria  remain  in  effect.  For  example,  if  you  are  looking  for  samples  in  a 
media,  the  start  time  would  indicate  the  beginning  of  the  sample,  and  the  duration 
would  indicate  the  length  of  time  to  the  next  sample.  In  this  case,  you  could  find  the 
next  media  sample  by  adding  the  duration  to  the  start  time.  These  duration  values 
are  always  positive;  you  determine  the  direction  of  the  search  by  setting  the  sign  of 
the  rate  value  you  supply  to  the  functions. 

Note  that  movie  interesting  times  are  defined  in  the  scope  of  the  movie  as  a  whole. 
As  a  result,  one  interesting  time  ends  when  another  interesting  time  starts  in  any 
track  in  the  movie.  For  example,  if  you  are  looking  for  key  frames  in  a  movie,  the 
duration  value  from  one  interesting  time  tells  you  when  the  next  key  frame  starts. 
However,  that  second  key  frame  may  be  in  a  different  track  in  the  movie.  Therefore, 
the  duration  of  the  interesting  time  does  not  necessarily  correspond  to  the  duration 
of  the  key  frame. 

You  can  use  GetMovi  eNext  Interest i  ngT i me  (I — 480)  to  locate  times  of  interest  in  a 
movie.  GetT rackNextlnteresti  ngT i me  (1-537)  lets  you  work  with  tracks.  Use 
GetMedi  aNextlnteresti  ngT ime  (1-437)  to  locate  samples  in  a  media. 

Functions 

GetMovi  eNext  Interest!'  ngT  ime  (1-480) 

Searches  for  times  of  interest  in  a  movie's  enabled  tracks. 

GetT  rackNextlnteresti  ngT  ime  (1-537) 

Searches  for  times  of  interest  in  a  track. 

GetMedi  aNextlnteresti  ngT  ime  (1-437) 

Searches  for  times  of  interest  in  a  media. 


Locating  a  Movie's  Tracks  and  Media  Structures 

The  Movie  Toolbox  provides  a  set  of  functions  that  help  your  application  locate  a 
movie's  tracks  and  media  structures.  The  Movie  Toolbox  identifies  a  movie's  tracks 
in  two  ways.  First,  every  track  in  a  movie  has  a  unique  ID  value.  This  ID  value  is 
unique  throughout  the  life  of  a  movie,  even  after  it  has  been  saved.  That  is,  no  two 
tracks  of  a  movie  ever  have  the  same  ID,  and  no  ID  value  is  ever  reused.  Second,  a 
movie's  current  tracks  may  be  identified  by  their  index  value.  Index  values  always 
range  from  1  to  the  number  of  tracks  in  the  movie.  Track  indexes  provide  a 
convenient  way  to  access  each  track  of  a  movie. 
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There  are  several  functions  that  allow  you  to  find  a  movie's  tracks.  You  can  use 
GetMovi  eT rackCount  (1-498)  to  determine  the  number  of  tracks  in  a  movie.  Use 
GetMovi  eT  rack  (1-497)  to  obtain  the  track  identifier  for  a  specific  track,  given  its  ID. 
GetMovi  el  ndT rack  (1-473)  lets  you  obtain  a  track's  identifier,  given  its  track  index. 

You  can  obtain  a  track's  ID  value  given  its  track  identifier  by  calling  GetTrackID 
(1-531).  You  can  determine  the  movie  that  contains  a  track  by  calling  GetTrackMovi  e 
(1-536). 

GetT rackMedi  a  (1-535)  enables  you  to  find  a  track's  media.  Conversely,  you  can  find 
the  track  that  uses  a  media  by  calling  GetMedi  aTrack  (1-455). 


Functions 

GetMovi eTrackCount  (1-498) 

Returns  the  number  of  tracks  in  a  movie. 

GetMovi  eT  rack  (1-497) 

Determines  the  track  identifier  of  a  track,  given  the  track's  ID  value. 
GetMovielndTrack  (1-473) 

Determines  the  track  identifier  of  a  track,  given  the  track's  index  value. 
GetMovielndTrackType  (1-475) 

Searches  for  all  of  a  movie's  tracks  that  share  a  given  media  type  or  media 
characteri  sti  c. 

GetTrackID  (1-531) 

Determines  a  track's  unique  track  ID  value. 

GetTrackMovi e  (1-536) 

Determines  the  movie  that  contains  a  specified  track. 

GetTrackMedi  a  (1-535) 

Determines  the  media  that  contains  a  track's  sample  data. 

GetMedi  aTrack  (1-455) 

Determines  the  track  that  uses  a  specified  media. 
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Working  With  Track  References 

Track  references  allow  you  to  relate  tracks  to  one  another.  For  example,  they  can 
help  you  identify  the  text  track  that  contains  the  subtitles  for  a  movie's  audio  track 
and  relate  that  text  track  to  a  particular  audio  track. 
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The  AddT rackRef  erence  (T-42)  function  allows  you  to  relate  one  track  to  another.  The 
Del  eteT rackReference  (1-252)  function  removes  that  relationship.  The 
SetT rackReference  (III— 1665)  and  GetT rackReference  (1-541)  functions  allow  you  to 
modify  an  existing  track  reference  so  that  it  identifies  a  different  track.  The 
GetNextT rackReferenceType  (1-503)  and  GetT rackReferenceCount  functions  allow 
you  to  scan  all  of  a  track's  track  references. 


Functions 

AddTrackReference  (1-42) 

Adds  a  new  track  reference  to  a  track. 

Del  eteTrackReference  (1-252) 

Removes  a  track  reference  from  a  track. 

SetTrackReference  (III — 1665) 

Modifies  an  existing  track  reference. 

GetTrackReference  (1-541) 

Retrieves  the  track  identifier  contained  in  an  existing  track  reference. 
GetNextT  rackReferenceType  (1-503) 

Determines  all  of  the  track  reference  types  that  are  defined  for  a  given  track. 
GetTrackReferenceCount  (1-542) 

Determines  how  many  track  references  of  a  given  type  exist  for  a  track. 


Working  With  Alternate  Tracks 

The  Movie  Toolbox  allows  you  to  define  alternate  tracks  in  a  movie.  You  can  use 
alternate  tracks  to  support  multiple  languages  or  to  present  different  levels  of  visual 
quality  in  the  movie. 

You  collect  alternate  tracks  into  groups.  Alternate  track  groups  are  collections  of 
tracks  that  conceptually  represent  some  data  but  are  appropriate  for  use  in  different 
play  environments.  The  Movie  Toolbox  selects  one  track  from  each  alternate  group 
when  it  plays  the  movie.  For  example,  you  could  create  a  movie  that  has  three 
separate  audio  tracks:  one  in  English,  one  in  French,  and  one  in  Spanish.  You  would 
collect  these  audio  tracks  into  an  alternate  group.  When  the  user  plays  the  movie, 
the  Movie  Toolbox  selects  the  track  from  this  group  that  corresponds  to  the  current 
language  setting  for  the  movie. 

Similarly,  you  can  use  alternate  tracks  to  store  data  of  different  quality.  When  the 
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user  plays  the  movie,  the  Movie  Toolbox  selects  the  track  that  best  suits  the 
capabilities  of  the  Macintosh  computer  on  which  the  movie  is  being  played.  In  this 
manner,  you  can  create  a  single  movie  that  can  accommodate  the  playback 
characteristics  of  a  number  of  different  computer  configurations. 

You  set  a  movie's  language  by  calling  SetMovi  eLanguage  (III— 1620).  To  establish 
alternate  groups  of  tracks,  you  can  use  SetT rackAl  ternate  (III— 1656)  and 
GetTrackAlternate  (1-522).  You  can  work  with  the  language  and  quality 
characteristics  of  media  by  calling  GetMedi  aLanguage  (1-436),  SetMedi  aLanguage, 
GetMedi  aQual  i  ty  (1-441),  and  SetMedi  aQual  i  ty  (III — 1605). 
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By  default,  the  Movie  Toolbox  automatically  selects  the  appropriate  tracks  to  play 
according  to  a  movie's  quality  and  language  settings,  as  well  as  the  capabilities  of 
the  Macintosh  computer.  Whenever  your  application  calls  SetMovi  eGWorl  d 
(III — 1619),  SetMovi eBox,  UpdateMovi e  (III — 1981),  or  SetMovi eMatri x  (III — 1622),  the 
Movie  Toolbox  checks  each  alternate  group  for  an  appropriate  track.  However,  you 
can  control  this  selection  process.  Use  SetAutoT rackAl  ternatesEnabl  ed  (III— 1570)  to 
enable  or  disable  automatic  track  selection.  Sel  ectMovi  eAl  ternates  (III— 1569) 
instructs  the  Movie  Toolbox  to  select  appropriate  tracks  immediately.  If  no  tracks  in 
an  alternate  track  group  are  enabled,  then  the  Movie  Toolbox  does  not  activate  any 
track  from  that  group  during  automatic  track  selection. 


Functions 

SetMovi  eLanguage  (III — 1 620) 

Specifies  a  movie's  localized  language  or  region  code. 

SetTrackAl  ternate  (III — 1 656) 

Adds  tracks  to,  or  remove  tracks  from,  alternate  groups. 

GetTrackAlternate  (1-522) 

Determines  all  the  tracks  in  an  alternate  group. 

GetMedi  a  Language  (1-436) 

Returns  a  media's  localized  language  or  region  code. 

SetMedi  a  Language  (III — 1 600) 

Sets  a  media's  localized  language  or  region  code. 

GetMedi  aQual  i  ty  (1-441) 

Returns  a  media's  quality  level  value. 

SetMedi  aQual  i  ty  (III — 1 605) 

Sets  a  media's  quality  level  value. 
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SetAutoTrackAlternatesEnabled  (III — 1 570) 

Enables  or  disables  automatic  track  selection  by  the  Movie  Toolbox. 

Sel  ectMovi  eAl  ternates  (III — 1 569) 

Instructs  the  Movie  Toolbox  to  select  appropriate  tracks  immediately. 

See  Also 

For  language  and  geographic  region  identifiers,  see  "Localization  Codes" 
(IV-2673). 

Working  With  Track  Sound 

Two  functions  operate  on  the  static  3D  sound  setting  for  a  track.  By  constantly 
setting  the  value,  it  is  possible  for  an  application  to  make  a  track's  sound  move  in 
3D  space.  If  it  is  necessary  to  store  dynamically  changing  3D  sound  settings  for  the 
track,  this  can  be  done  using  the  modifier  track  mechanism  in  conjunction  with  a 
tween  track. 

These  functions  are  listed  below. 


Functions 


SetTrackSound Local  izationSettings  (III — 1 666) 

Applies  3D  sound  effect  data  to  a  track. 

GetTrackSound Local  izationSettings  (1-543) 

Returns  a  handle  to  a  copy  of  the  current  3D  sound  settings  for  a  specified  track. 


Working  With  Data  References 

Media  structures  identify  how  and  where  to  find  their  sample  data  by  means  of  data 
references.  For  sound  and  video  media,  data  references  identify  files,  memory 
areas,  or  net  addresses  that  contain  media  data.  Media  handlers  use  these  data 
references  in  order  to  manipulate  media  data.  A  single  media  may  contain  one  or 
more  data  references.  The  Movie  Toolbox  identifies  a  media's  data  references  with 
an  index  value.  Index  values  always  range  from  1  to  the  number  of  references  in  the 
media.  Data  reference  indexes  provide  a  convenient  way  to  access  each  reference  in 
a  media. 

You  can  use  GetMedi  aDataRef  (1-427)  to  retrieve  information  about  a  media's  data 
reference.  You  can  add  a  data  reference  to  a  media  by  calling  AddMedi  aDataRef  (1-26). 
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Your  application  can  determine  the  number  of  data  references  in  a  media  by  calling 
GetMedi  aDataRefCount  (1-428). 


Functions 

GetMedi  aDataRef  (1-427) 

Returns  a  copy  of  a  specified  data  reference. 

AddMedi  aDataRef  (1-26) 

Adds  a  data  reference  to  a  media. 

GetMedi  aDataRefCount  (1-428) 

Determines  the  number  of  data  references  in  a  media. 
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Determining  Movie  Creation  and  Modification  Time 

The  Movie  Toolbox  maintains  two  timestamps  in  every  movie,  track,  and  media. 
One  timestamp,  the  creation  date,  indicates  the  date  and  time  when  the  item  was 
created.  The  other,  the  modification  date,  contains  the  date  and  time  when  the  item 
was  last  changed  and  saved.  The  timestamp  value  is  in  the  same  format  as 
Macintosh  file  system  creation  and  modification  times;  that  is,  the  timestamp 
indicates  the  number  of  seconds  since  midnight,  January  1, 1904. 

You  can  use  GetMovi  eCreati  onT i  me  (1-465)  and  GetMovi  eModi  f  i  cati  onT i  me  to  work 
with  movie  creation  and  modification  dates.  You  can  use  GetT rackCreati  onT i  me 
(1-524)  and  GetT rackModi  f  i  cati  onT ime  to  retrieve  a  track's  creation  and 
modification  dates.  You  can  use  GetMedi  aCreati  onTime  (1-424)  and 
GetMedi  a  Modi  fi  cati  onTime  to  get  a  media's  creation  and  modification  dates. 


Functions 

GetMovi  eCreati  onTi  me  (1-465) 

Returns  the  movie's  creation  date  and  time  information. 

GetMovi  eModi  fi  cati  onTime  (1-479) 

Returns  a  movie's  modification  date  and  time. 

GetTrackCreati  onTime  (1-524) 

Returns  a  track's  creation  date  and  time. 

GetTrackModi  fi  cati  onTime  (1-536) 

Returns  a  track's  modification  date  and  time. 
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GetMedi  aCreati  onTi  me  (1-424) 

Returns  the  creation  date  and  time  stored  in  a  media. 

GetMedi  a  Modi  f  i  cat  i  onTi  me  (1-437) 

Returns  a  media's  modification  date  and  time. 


Working  With  Media  Samples 

The  Movie  Toolbox  provides  a  number  of  functions  that  allow  applications  to 
determine  information  about  a  movie's  sample  data. 

Your  application  can  use  GetMovi  eDataSi  ze  (1-465),  GetT rackDataSi  ze,  and 
GetMedi  aDataSi  ze  (1-429)  to  determine  the  size,  in  bytes,  of  the  data  stored  in  a 
media,  movie,  or  track. 

You  can  use  GetMedi  aSampl  eDescri  pti  onCount  (IM47)  and 

GetMedi  aSampleDescripti  on  to  retrieve  a  media's  sample  descriptions. 

SetMedi  aSampl  eDescri  pti  on  (III— 1606)  enables  you  to  change  the  contents  of  a 
particular  sample  description  associated  with  a  media.  GetMediaSampleCount  (1-445) 
determines  the  number  of  samples  in  a  media.  Sampl  eNumToMedi  aTime  (III— 1526)  and 
Medi  aT i meToSampl  eNum  allow  you  to  convert  from  a  time  value  to  a  sample  number 
and  vice  versa. 


Functions 

GetMovi  eDataSi  ze  (1-465) 

Determines  the  size  of  the  sample  data  in  a  segment  of  a  movie. 
GetTrackDataSi ze  (1-525) 

Determines  the  size,  in  bytes,  of  the  sample  data  in  a  segment  of  a  track. 
GetMedi  aDataSi  ze  (1-429) 

Determines  the  size,  in  bytes,  of  the  sample  data  in  a  media  segment. 

GetMedi  aSampl  eDescri  pti  onCount  (1-447) 

Returns  the  number  of  sample  descriptions  in  a  media. 

GetMedi  aSampl  eDescri  pti  on  (1-445) 

Retrieves  a  Sampl  eDescri  pti  on  (IV-2414)  structure  from  a  media. 

SetMedi  aSampl  eDescri  pti  on  (III — 1 606) 

Changes  the  contents  of  a  particular  Sampl  eDescri  pti  on  (IV-2414)  structure  of  a 
specified  media. 
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GetMedi  aSampl  eCount  (1-445) 

Determines  the  number  of  samples  in  a  media. 

Sampl  eNumToMedi  a  Time  (III — 1 526) 

Finds  the  time  at  which  a  specified  sample  plays. 

Medi  aTimeToSampl  eNum  (11-913) 

Lets  you  find  the  sample  that  contains  the  data  for  a  specified  time. 

See  Also 

You  can  use  the  functions  described  in  "Finding  Interesting  Times"  (V-2735)  to 
locate  specific  samples  in  a  media.  Also  see  "Adding  Samples  to  Media  Structures" 
(V-2752)  for  information  about  functions  that  allow  you  to  retrieve  sample  data 
from  a  media. 
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Working  With  Movie  User  Data 

Each  movie,  track,  and  media  can  contain  a  user  data  list,  which  your  application 
can  use  in  any  way  you  want.  A  user  data  list  contains  all  the  user  data  for  a  movie, 
track,  or  media.  Each  user  data  list  may  contain  one  or  more  user  data  items. 

All  QuickTime  user  data  items  share  several  attributes.  First,  each  user  data  item 
carries  a  type  identifier,  stored  in  a  long  integer.  Apple  has  reserved  all  lowercase 
user  data  type  values.  You  are  free  to  create  user  data  type  values  using  uppercase 
or  mixed  case.  Apple  recommends  using  type  values  that  begin  with  the  ©  character 
(ASCII  0xA9)  to  specify  user  data  items  that  store  text  data.  User  data  items  of  these 
types  must  contain  text  data  only. 

Second,  the  Movie  Toolbox  allows  you  to  create  more  than  one  user  data  item  in  a 
user  data  list.  Therefore,  each  user  data  item  is  identified  by  a  unique  index.  Index 
values  are  assigned  sequentially  within  a  user  data  type  and  start  at  1. 

Finally,  you  may  create  alternate  text  for  a  given  user  data  text  item.  For  example, 
you  may  want  to  support  multiple  languages  and  may  therefore  want  to  create 
different  text  for  each  language.  The  Movie  Toolbox  allows  you  to  specify  different 
versions  of  the  text  of  a  single  user  data  item.  These  versions  are  distinguished  by 
their  region  code  values. 

Before  you  can  work  with  the  contents  of  a  user  data  list,  you  must  obtain  a 
reference  to  the  list.  GetMovi  ellserData  (1-499),  GetT rackUserData,  and 
GetMedi  allserData  (1-456)  allow  you  to  get  a  reference  to  a  user  data  list.  You  can 
then  use  GetUserData  (1-547),  AddllserData  (1-44),  and  RemoveUserData  (III— 1459)  to 
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work  with  the  items  contained  in  the  user  data  list.  If  your  user  data  items  contain 
text  data,  you  can  use  AddUserDataText  (1-45),  GetUserDataText,  and 
RemoveUserDataText  (III— 1460)  to  work  with  the  text  of  a  user  data  item.  Note  that  a 
single  user  data  item  can  store  either  text  or  other  data,  but  not  both. 

You  can  count  the  number  of  user  data  items  of  a  specified  type  in  a  movie,  track, 
or  media  by  calling  CountUserDataType  (1-144).  You  can  use  GetNextUserDataType 
(1-503)  to  scan  all  the  types  of  user  data  in  a  specified  user  data  list. 

The  Movie  Toolbox  also  supplies  a  number  of  functions  for  the  manipulation  of  user 
data.  SetUserData  Item  (III— 1673)  and  GetUserData  Item  (1-548)  allow  easy  access  to 
data  stored  in  user  data  items.  NewUserData  (11-1124)  and  Di  sposellserData  (1-303) 
provide  for  the  use  of  user  data  outside  of  the  immediate  context  of  QuickTime 
movies. 

Your  applications  and  components  can  also  create  user  data  structures. 
PutUserDatalntoHandl  e  (11-1154)  and  the  NewUserDataFromHandl  e  (11-1124)  permit 
user  data  to  be  stored  and  retrieved  in  atoms. 


Functions 

GetMovi  eUserData  (1-499) 

Obtains  access  to  a  movie's  user  data  list. 

GetTrackUserData  (1-546) 

Obtains  access  to  a  track's  user  data  list. 

GetMedi aUserData  (1-456) 

Obtains  access  to  a  media's  user  data  list. 

GetUserData  (1-547) 

Returns  a  specified  user  data  item. 

AddUserData  (1-44) 

Adds  an  item  to  a  user  data  list. 

RemoveUserData  (III — 1459) 

Removes  an  item  from  a  user  data  list. 

GetUserDataText  (1-549) 

Retrieves  language-tagged  text  from  an  item  in  a  user  data  list. 
AddUserDataText  (1-45) 

Places  language-tagged  text  into  an  item  in  a  user  data  list. 
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RemoveUserDataText  (III — 1460) 

Removes  language-tagged  text  from  an  item  in  a  user  data  list. 
CountUserDataType  (1-144) 

Determines  the  number  of  items  of  a  given  type  in  a  user  data  list. 
GetNextUserDataType  (1-503) 

Retrieves  the  next  user  data  type  in  a  specified  user  data  list. 

SetUserData Item  (III — 1 673) 

Sets  an  item  in  a  user  data  list. 

GetUserData Item  (1-548) 

Returns  a  specified  user  data  item. 

NewUserData  (11-1124) 

Creates  a  new  user  data  structure. 

Di  sposellserData  (1-303) 

Disposes  of  a  user  data  structure  created  by  NewUserData  (11-1124). 
PutUserDatalntoHandl  e  (11-1154) 

Takes  a  specified  user  data  structure  and  replaces  the  contents  of  the  handle 
with  a  publicly  parsable  form  of  the  user  data. 

NewUserDataFromHandl  e  (11-1124) 

Creates  a  new  user  data  structure  from  a  handle. 
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Managing  the  Video  Frame  Playback  Rate 

Two  functions  let  you  determine  the  rate  at  which  a  QuickTime  movie  plays  back 
each  video  frame.  You  should  use  these  functions  for  debugging. 

These  functions  are  listed  below. 


Functions 

Vi  deoMedi  aGetStati  sti  cs  (III — 2059) 

Returns  the  play-back  frame  rate  of  a  movie. 

Vi  deoMedi  aResetStati  sti  cs  (III — 2059) 

Resets  the  video  media  handler's  counters  before  using 

Vi  deoMedi  aGetStati  sti  cs  (III— 2059)  to  determine  the  frame  rate  of  a  movie. 
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Editing  Movies 


The  Movie  Toolbox  provides  a  number  of  functions  that  allow  applications  to  edit 
existing  movies  or  create  the  contents  of  new  movies. 


High-Level  Movie  Editing  Functions 

The  Movie  Toolbox  provides  a  set  of  high-level  functions  that  allow  you  to  edit 
movies.  These  functions  work  with  a  movie's  current  selection,  defined  by  a  starting 
time  and  a  duration.  If  you  are  calling  the  Movie  Toolbox  directly  to  do  editing,  you 
should  use  these  functions. 

The  movies  created  by  these  functions  contain  references  to  the  data  in  the  source 
movie.  Because  the  new  movies  contain  references  and  not  data,  they  are  small  and 
easily  moved  to  and  from  the  scrap.  If  you  delete  the  movie  that  contains  the  data, 
the  data  references  in  the  new  movies  are  no  longer  valid  and  the  new  movies 
cannot  be  played.  Therefore,  before  you  delete  the  original  movie,  you  should  call 
FI  attenMovi  e  (1-372)  for  each  of  the  new  movies.  This  function  copies  the  data  into 
each  of  the  new  movies,  eliminating  the  data  references. 

Note  that  the  Movie  Toolbox  does  not  always  copy  empty  tracks  from  the  source 
movie  to  the  movies  that  are  created  by  these  functions.  Specifically,  the  Movie 
Toolbox  preserves  the  empty  tracks  until  you  paste  or  add  the  selection  into  the 
destination  movie.  At  that  time,  the  Movie  Toolbox  removes  the  empty  tracks  from 
the  selection.  In  addition,  if  a  track  in  the  source  movie  has  trailing  empty  space,  the 
Movie  Toolbox  removes  that  empty  space  from  the  track  when  it  is  copied  into  the 
new  movie.  Therefore,  if  you  want  to  add  a  segment  beyond  the  end  of  a  movie,  you 
insert  the  space  when  you  insert  the  new  segment  using  I  nsertMovi  eSegment 
(11-762). 

The  Movie  Toolbox  allows  you  to  paste  different  data  types  into  a  movie.  For 
example,  QuickDraw  pictures  and  standard  sound  data  can  be  pasted  directly  into 
a  movie.  If  you  are  using  the  movie  controller  component,  you  do  not  need  to  use 
these  functions  to  paste  different  data  types  into  a  movie. 

To  get  and  change  a  movie's  current  selection,  your  application  can  call 
GetMovi  eSel  ecti  on  (1-491)  and  SetMovi  eSel  ecti  on  (III— 1632).  Your  application  can 
work  with  a  movie's  current  selection  by  calling  CutMovi eSel  ecti  on  (1-166), 
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CopyMovi  eSel  ecti  on,  PasteMovi  eSel  ecti  on  (11-1139),  Cl  earMovi  eSel  ecti  on,  and 
AddMovi eSel ecti on  (1-38). 

PutMovi  eOnScrap  and  NewMovi eFromScrap  (11-1085)  enable  your  application  to  work 
with  movies  that  are  on  the  scrap.  IsScrapMovie  (11-775)  examines  the  system  scrap 
to  determine  whether  it  can  translate  any  of  the  data  into  a  movie. 

PasteHandl  elntoMovi  e  (11-1137)  takes  the  contents  of  a  specified  handle,  together 
with  its  type,  and  pastes  it  into  a  movie.  PutMovi  elntoTypedHandl  e  (11-1152)  takes  a 
movie  (or  a  single  track  from  within  a  movie)  and  converts  it  into  a  handle. 
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Functions 

GetMovi  eSel  ecti  on  (1-491) 

Returns  information  about  a  movie's  current  selection. 

SetMovi  eSel  ecti  on  (III — 1 632) 

Sets  a  movie's  current  selection. 

CutMovi  eSel  ecti  on  (1-166) 

Creates  a  new  movie  that  contains  the  original  movie's  current  selection. 
CopyMovi  eSel  ecti  on  (1-139) 

Creates  a  new  movie  that  contains  the  original  movie's  current  selection. 

PasteMovi  eSel  ecti  on  (11-1139) 

Places  the  tracks  from  one  movie  into  another  movie. 

Cl  earMovi  eSel  ecti  on  (1-90) 

Removes  the  segment  of  the  movie  that  is  defined  by  the  current  selection. 

AddMovi  eSel  ecti  on  (1-38) 

Adds  one  or  more  tracks  to  a  movie. 

PutMovi  eOnScrap  (11-1153) 

Places  a  movie  into  the  Macintosh  scrap. 

NewMovi  eFromScrap  (11-1085) 

Creates  a  movie  from  the  contents  of  the  scrap. 

IsScrapMovie  (11-775) 

Checks  the  system  scrap  to  find  out  if  it  can  translate  any  of  the  data  into  a 
movie. 
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PasteHandl  elntoMovi  e  (11-1137) 

Takes  the  contents  of  a  specified  handle,  together  with  its  type,  and  pastes  it 
into  a  specified  movie. 

PutMovi  elntoTypedHandle  (11-1152) 

Takes  a  movie,  or  a  single  track  from  within  that  movie,  and  converts  it  into  a 
handle  of  a  specified  type. 

See  Also 

See  "Low-Level  Movie  Editing  Functions"  (V-2749). 


Undo  for  Movies 


The  Movie  Toolbox  provides  functions  that  allow  you  to  save  and  restore  the  edit 
state  of  a  movie.  An  edit  state  contains  information  that  completely  defines  a 
movie's  content  at  the  time  you  create  the  edit  state.  It  is,  in  essence,  a  checkpoint  in 
the  edit  session.  You  can  manage  a  movie's  edit  states  in  order  to  implement  an 
undo  capability  for  editing  movies.  For  example,  you  can  save  a  movie's  edit  state 
before  performing  an  editing  operation,  such  as  a  cut,  and  later  restore  the  old  state. 
You  can  have  several  movie  edit  states  obtained  at  different  times  during  an  editing 
session,  and  restore  to  any  one  of  them  at  any  time.  In  this  manner,  you  can  provide 
a  multilevel  undo  capability. 

Note  that  a  movie's  edit  state  does  not  save  everything  about  a  movie.  Most 
important,  the  edit  state  does  not  contain  information  about  the  movie's  spatial 
characteristics.  For  example,  the  edit  state  does  not  store  the  current  boundary 
rectangle  or  clipping  region.  Consequently,  edit  states  are  best  suited  to  supporting 
undo  operations  involving  movie  content,  including  track  creation  and  removal. 
You  can  use  other  Movie  Toolbox  functions  to  support  undo  operations  for  movie 
characteristics. 

You  can  use  NewMovi  eEdi  tState  (11-1073)  to  save  a  movie's  edit  state.  Use 
UseMovieEditState  (III— 1984)  to  restore  the  movie  to  its  condition  according  to  a 
previous  edit  state.  Your  application  must  dispose  of  an  edit  state  by  calling 
DisposeMovieEditState  (1-273) .  Y  ou  must  dispose  of  a  movie's  edit  states  before  you 
dispose  of  the  movie. 


Functions 


NewMovi  eEdi  tState  (11-1073) 
Creates  an  edit  state. 
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UseMovi eEdi tState  (III — 1 984) 

Returns  a  movie  to  the  condition  determined  by  an  edit  state  created 
previously. 

Di  sposeMovi  eEdi  tState  (1-273) 

Disposes  of  an  edit  state. 


Low-Level  Movie  Editing  Functions 

The  Movie  Toolbox  provides  a  number  of  functions  that  allow  your  application  to 
perform  low-level  editing  operations  on  movies.  These  functions  work  with  movie 
segments  (pieces  of  a  movie  that  are  defined  by  a  starting  time  and  duration)  and 
therefore  give  you  a  great  deal  of  control  over  the  editing  process.  These  functions 
never  copy  the  movie  data;  rather,  they  work  with  references  to  the  movie's  data. 

Use  Copy Mo vi  eSetti  ngs  (1-140)  to  copy  certain  important  settings  from  one  movie  to 
another.  Use  InsertMovi  eSegment  (11-762)  to  copy  a  segment  from  one  movie  to 
another.  Use  InsertEmptyMovi  eSegment  (11-759)  to  insert  an  empty  segment  into  a 
movie.  Use  Del  eteMovi  eSegment  (1-250)  to  delete  a  segment  from  a  movie. 

You  can  change  a  segment's  duration  by  calling  the  Seal  eMovi  eSegment  (III— 1528) 
function.  This  function  stretches  or  shrinks  the  segment  to  accommodate  a  specified 
duration. 
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Functions 

CopyMovi  eSetti  ngs  (1-140) 

Copies  many  settings  from  one  movie  to  another,  overwriting  the  destination 
settings  in  the  process. 

InsertMovi eSegment  (11-762) 

Copies  part  of  one  movie  to  another. 

InsertEmptyMovi  eSegment  (11-759) 

Adds  an  empty  segment  to  a  movie. 

Del  eteMovi  eSegment  (1-250) 

Removes  a  specified  segment  from  a  movie. 

Seal  eMovi  eSegment  (III — 1 528) 

Changes  the  duration  of  a  segment  of  a  movie. 
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See  Also 

See  ''High-Level  Movie  Editing  Functions"  (V-2746).  These  functions  let  edit 
movies  by  working  with  the  current  selection. 


Editing  Tracks 

The  Movie  Toolbox  provides  a  number  of  functions  that  allow  your  application  to 
perform  editing  operations  on  tracks.  They  work  with  track  segments  (pieces  of  a 
track  that  are  defined  by  a  starting  time  and  duration)  and  therefore  give  you  a  great 
deal  of  control  over  the  editing  process.  These  functions  may  copy  movie  data,  if 
required  by  the  operation.  Note  that  when  you  edit  a  track  you  may  change  the 
duration  of  the  movie  that  contains  that  track. 

CopyT rackSettings  (1-141)  lets  you  copy  certain  important  settings  from  one  track  to 
another.  You  can  use  InsertT rackSegment  (11-764)  to  copy  a  segment  from  one  track 
to  another  (by  reference  or  by  moving  data)  or  to  copy  a  segment  within  a  track. 
InsertEmptyT rackSegment  (11-760)  allows  you  to  insert  an  empty  segment  into  a 
track.  You  can  use  the  InsertMedialntoTrack  (11-76 1 )  function  to  insert  a  media  into 
a  track. 

You  can  delete  a  segment  from  a  track  by  calling  the  Del  eteT rackSegment  (1-252) 
function.  You  can  change  a  segment's  duration  by  calling  the  Seal  eT rackSegment 
(III— 1529)  function.  This  function  stretches  or  shrinks  the  segment  to  accommodate 
a  specified  duration. 

You  can  use  the  GetTrackEditRate  (1-530)  function  to  determine  the  rate  of  the  track 
edit  of  a  specified  track  at  an  indicated  time. 


Functions 

CopyTrackSetti  ngs  (1-141) 

Copies  many  settings  from  one  track  to  another,  overwriting  the  destination 
settings. 

InsertTrackSegment  (11-764) 

Copies  data  into  a  track. 

InsertEmptyTrackSegment  (11-760) 

Adds  an  empty  segment  to  a  track. 

InsertMedialntoTrack  (11-761) 

Inserts  a  reference  to  a  media  segment  into  a  track. 
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Del  eteTrackSegment  (1-252) 

Removes  a  specified  segment  from  a  track. 

Seal  eTrackSegment  (III — 1 529) 

Changes  the  duration  of  a  segment  of  a  track. 

GetTrackEdi  tRate  (1-530) 

Returns  the  rate  of  the  track  edit  of  a  specified  track  at  an  indicated  time. 
AddEmptyTrackToMovie  (1-23) 

Duplicates  a  track  from  a  movie  into  the  same  movie  or  into  another  movie. 
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Undo  for  Tracks 

The  Movie  Toolbox  provides  functions  that  allow  you  to  capture  and  restore  the 
edit  state  of  a  track.  As  with  the  functions  that  manipulate  a  movie's  edit  state,  you 
can  manage  a  track's  edit  states  in  order  to  implement  an  undo  capability  for  track 
editing.  For  example,  you  can  capture  a  track's  edit  state  before  performing  an 
editing  operation,  such  as  a  cut,  and  later  restore  the  old  state.  You  can  have  several 
track  edit  states  obtained  at  different  times  during  an  editing  session,  and  you  can 
restore  to  any  one  of  them  at  any  time.  In  this  manner,  you  can  provide  a  multilevel 
undo  capability. 

Note  that  a  track's  edit  state  does  not  save  everything  about  the  track.  Most 
important,  the  edit  state  does  not  contain  information  about  track  spatial 
characteristics.  For  example,  the  edit  state  does  not  store  the  current  clipping  region. 
Consequently,  edit  states  are  best  suited  to  supporting  undo  operations  involving 
track  content.  You  can  use  other  Movie  Toolbox  functions  to  support  undo 
operations  for  track  characteristics. 

Use  NewT rackEdi  tState  (11-1119)  to  capture  a  track's  edit  state.  Use 
UseT rackEdi  tState  (III— 1984)  to  restore  the  track  to  its  condition  according  to  a 
previous  edit  state.  You  can  dispose  of  an  edit  state  by  calling 
Di  sposeT rackEdi  tState  (1-300). 


Functions 


NewTrackEdi  tState  (11-1119) 

Creates  a  new  edit  state  for  a  given  track. 

UseTrackEdi  tState  (III — 1 984) 

Returns  a  track  to  the  condition  determined  by  an  edit  state  created  previously. 
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Di  sposeT rackEdi  tState  (1-300) 

Disposes  of  a  movie's  track  edit  state. 


Adding  Samples  to  Media  Structures 

Certain  Movie  Toolbox  functions  directly  manipulate  media  samples.  These 
functions  are  used  only  by  applications  that  create  movies  or  add  data  to  existing 
movies. 

You  add  samples  to  a  media  by  calling  AddMedi  aSampl  e  (1-27).  You  can  indicate  that 
the  sample  to  be  added  is  or  is  not  a  sync  sample.  You  can  obtain  the  data  in  a  media 
sample  by  calling  GetMedi  aSampl  e  (1-443).  If  you  are  going  to  add  samples  to  a 
media,  you  must  do  so  within  a  media-editing  session.  You  start  a  media-editing 
session  by  calling  Begi  nMedi  a  Ed  i  ts  (1-56).  Once  you  have  finished  adding  samples 
to  the  media,  you  end  the  editing  session  by  calling  EndMedi  a  Edi  ts  (1-335). 

Once  you  have  added  samples  to  a  media,  you  can  work  with  references  to  those 
samples  by  calling  AddMedi  aSampl  eReference  (1-31)  and  GetMedi  aSampl  eReference. 
You  do  not  have  to  be  in  a  media-editing  session  to  use  these  functions 


Functions 

AddMedi  aSampl  e  (1-27) 

Adds  sample  data  and  a  description  to  a  media. 

GetMedi  aSampl  e  (1-443) 

Returns  a  sample  from  a  movie  data  file. 

Begi  nMedi  aEdi  ts  (1-56) 

Starts  a  media-editing  session. 

EndMedi  aEdi  ts  (1-335) 

Ends  a  media-editing  session. 

AddMedi  aSampl  eReference  (1-31) 

Works  with  samples  that  have  already  been  added  to  a  movie  data  file. 

AddMedi  aSampl  eReferences  (1-33) 

Adds  groups  of  samples  to  a  movie  data  file. 

GetMedi  aSampl  eReference  (1-447) 

Obtains  reference  information  about  samples  that  are  stored  in  a  movie  data 
file. 
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GetMedi  aSampI  eReferences  (1-449) 

Obtains  reference  information  about  groups  of  samples  that  are  stored  in  a 
movie. 

SetMedi  aDefaul  tDataRef  Index  (III — 1597) 

Specifies  which  of  a  media's  data  references  is  to  be  accessed  during  an  editing 
session. 

SetMedi  aPref  erredChunkSi  ze  (III — 1 603) 

Specifies  a  maximum  chunk  size  for  a  media. 

GetMedi  aPreferredChunkSi  ze  (1-440) 

Retrieves  the  maximum  chunk  size  for  a  media. 
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Manipulating  Media  Input  Maps 

The  Movie  Toolbox  contains  two  functions  for  maintaining  media  input  maps. 

Each  track  has  particular  attributes  such  as  size,  position,  and  volume  associated 
with  it.  The  media  input  map  of  that  track  describes  where  the  variable  parameters 
are  stored  so  that  modifier  tracks  know  where  to  send  their  data.  When  a  track  is 
copied,  its  input  map  is  also  copied. 


Functions 


GetMedi  alnputMap  (1-435) 

Returns  a  copy  of  the  input  map  associated  with  a  specified  media. 
SetMedi  alnputMap  (III — 1 599) 

Replaces  the  media's  existing  input  map  with  a  given  input  map. 


Interacting  With  Media  Handlers 


The  Movie  Toolbox  does  not  contain  any  support  for  specific  media  types.  Rather, 
it  delegates  this  work  to  media  handler  components.  The  Movie  Toolbox  provides 
a  number  of  functions  that  allow  your  application  to  interact  with  media  handlers. 
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Selecting  Media  Handlers 


Media  handler  components  are  responsible  for  interpreting  and  manipulating  a 
media's  sample  data.  Each  type  of  media  has  its  own  media  handler,  which  deals 
with  the  specific  characteristics  of  the  media  data.  The  Movie  Toolbox  provides  a  set 
of  functions  that  allow  you  to  gather  information  about  a  media  handler  and  assign 
a  particular  media  handler  to  a  media. 

Each  media  handler  has  an  associated  data  handler  for  each  data  reference.  The  data 
handler  is  responsible  for  fetching,  storing,  and  caching  the  data  that  the  media 
handler  uses.  The  Movie  Toolbox  provides  functions  that  allow  you  to  get 
information  about  data  handlers  and  to  assign  a  particular  data  handler  to  a  media. 

GetMedi  aHandl  er  (1-432)  and  GetMedi  aHandl  erDescri  pti  on  (1-432)  allow  you  to 
retrieve  information  about  a  media  handler.  You  can  use  the  SetMedi  aHandl  er 
(III— 1598)  to  assign  a  media  handler  to  a  media. 

GetMedi  aDataHandl  er  (1-425)  and  GetMedi  aDataHandl  erDescri  pti  on  enable  you  to 
retrieve  information  about  a  data  handler.  Use  SetMedi  aDataHandl  er  (III— 1594)  to 
assign  a  data  handler  to  a  media. 


Functions 

GetMedi  aHandl  er  (1-432) 

Obtains  a  reference  to  a  media  handler  component. 

GetDataHandl  er  (1-407) 

Retrieves  the  best  data  handler  component  to  use  with  a  given  data  reference. 

GetMedi  aHandl  erDescri  pti  on  (1-432) 

Retrieves  information  about  a  media  handler. 

SetMedi  aHandl  er  (III — 1 598) 

Assigns  a  specific  media  handler  to  a  track. 

GetMedi  aDataHandl  er  (1-425) 

Determines  a  media's  data  handler. 

GetMedi  aDataHandl  erDescri  pti  on  (1-426) 

Retrieves  information  about  a  media's  data  handler. 

SetMedi  aDataHandl  er  (III — 1 594) 

Assigns  a  data  handler  to  a  media. 
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Working  With  Media  Handler  Properties 


Two  functions  are  provided  for  setting  and  retrieving  the  property  atom  container 
of  a  media  handler. 

These  functions  are  listed  below. 


Functions 

GetMedi  aPropertyAtom  (1-440) 

Retrieves  the  property  atom  container  of  a  media  handler. 

SetMedi  aPropertyAtom  (III — 1 604) 

Sets  the  property  atom  container  of  a  media  handler. 
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Video  Media  Handler  Functions 


Video  media  handlers  are  responsible  for  interpreting  and  manipulating  video 
data.  You  can  call  them  directly  to  work  with  graphics  modes  and  color  values  that 
affect  the  display  of  video  data. 

Use  Medi  aSetGraphi  csMode  (11-892)  and  Medi  aGetGraphi  csMode  to  work  with  these 
characteristics. 


Functions 

Medi  aSetGraphi  csMode  (11-892) 

Sets  the  graphics  mode  and  blend  color  of  any  media  handler. 

Medi  aGetGraphi  csMode  (11-852) 

Obtains  the  graphics  mode  and  blend  color  values  currently  in  use  by  any 
media  handler. 


Sound  Media  Handler  Functions 


Sound  media  handlers  are  responsible  for  interpreting  and  manipulating  sound 
data.  You  can  call  them  directly  to  work  with  their  stereo  balance  settings. 

Use  Medi  aSetSoundBal ance  (11-904)  and  Medi  aGetSoundBal  ance  to  work  with  a 
handler's  balance  setting. 
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Functions 


Medi aSetSoundBal ance  (11-904) 

Sets  the  sound  balance  of  the  media  handler. 

Medi  aGetSoundBal  ance  (11-860) 

Obtains  the  sound  balance  of  the  media  handler. 


Text  Media  Handler  Functions 


You  can  use  text  media  handlers  to  add  plain  or  styled  text  samples  to  a  movie, 
indicate  scrolling  and  highlighting  properties  for  the  text,  search  for  text,  and 
highlight  specified  text.  A  particular  text  sample  has  a  default  font,  size,  typeface, 
and  color  as  well  as  a  location  (text  box)  within  the  track  bounds  to  be  drawn.  The 
data  format  allows  you  to  include  style  run  information  for  the  text.  You  can  set 
flags  to  clip  the  display  to  the  text  box,  inhibit  automatic  scaling  of  text  as  the  track 
bounds  are  scaled,  scroll  the  text,  and  specify  if  text  is  to  be  displayed  at  all. 

You  can  use  TextMedi  aAddTextSampl  e  (III— 1936)  to  add  text  to  a  media. 

TextMedi  aAddTESampl  e  (III— 1933)  allows  you  to  specify  a  TextEdit  handle  (which 
may  have  multiple  style  runs)  to  be  added  to  a  media.  TextMedi  a  A  d  d  H  i  1  i  teSampl  e 
(III— 1932)  allows  you  to  indicate  highlighting  for  text  that  has  just  been  added. 

These  functions  convert  text  into  the  text  media  format  and  add  it  to  a  media.  To  use 
them,  you  need  to  create  a  text  track  and  media,  call  Begi  nMedi  a  Ed  i  ts  (1-56),  call  the 
appropriate  text  media  handler  function,  call  EndMedi  aEdi  ts  (1-335),  and  call 
Insert  Med  ialntoT  rack  (11-761). 

The  format  of  the  text  data  that  is  added  to  the  media  is  a  16-bit  length  word 
followed  by  the  text.  The  length  word  specifies  the  number  of  bytes  in  the  text. 
Optionally,  one  or  more  atoms  of  additional  data  may  follow. 

The  Movie  Toolbox  provides  functions  that  allow  you  to  search  for  and  highlight 
text.  You  can  use  TextMedi  a  FI  ndNextText  (III— 1941)  to  search  for  text  in  a  text  track 
and  TextMedi  a H i  1  i  teTextSampi  e  (III— 1944)  to  highlight  specified  text  in  a  text  track. 
You  can  use  TextMedi  aSetTextProc  (III— 1947)  to  specify  a  callback  to  be  invoked 
whenever  a  new  text  sample  is  added  to  a  movie. 


Functions 


TextMedi  aAddTextSampl  e  (III — 1 936) 

Adds  a  single  block  of  styled  text  to  an  existing  media. 
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TextMedi  aAddTESampl  e  (III — 1 933) 

Specifies  a  TextEdit  handle  to  be  added  to  a  specified  media. 

TextMedi  aAddHi  1  i  teSampl  e  (III — 1 932) 

Provides  dynamic  highlighting  of  text. 

TextMedi  aFi  ndNextText  (III — 1941) 

Searches  for  text  with  a  specified  media  handler  starting  at  a  given  time. 

TextMedi  a H i  1  i  teTextSampl  e  (III — 1 944 ) 

Specifies  selected  text  to  be  highlighted  for  a  given  text  media  handler. 

TextMedi  aSetTextSampl  eData  (III — 1 950) 

Sets  values  before  calling  TextMedi  aAddTextSampl  e  (III— 1936)  or 
TextMedi  aAddTESampl  e  (III — 1933). 

TextMedi  aSetTextProc  (III — 1947) 

Specifies  a  custom  function  to  be  called  whenever  a  text  sample  is  displayed  in 
a  movie. 

Callbnack 

TextMedi  aProc  (III — 2 150) 

A  callback  that  can  be  called  whenever  a  text  sample  is  displayed  in  a  movie. 

See  Also 

For  more  information  on  styled  text,  style  runs,  and  TextEdit,  see  Inside  Macintosh: 
Text  (listed  in  the  bibliography). 
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Previewing  Files 


File  previews  contain  information  that  gives  the  user  an  idea  of  a  file's  contents 
without  opening  the  file.  Typically,  a  file's  preview  is  a  small  PICT  image  (called  a 
thumbnail),  but  previews  may  also  contain  other  types  of  information  that  is 
appropriate  to  the  type  of  file  being  considered.  For  example,  a  text  file's  preview 
might  tell  the  user  when  the  file  was  created  and  what  it  discusses. 


Creating  File  Previews 

The  Movie  Toolbox  provides  two  functions  that  allow  you  to  create  file  previews. 
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You  can  use  MakeFi  1  ePrevi ew  (11-784)  to  create  a  preview  for  a  file.  AddFi  1  ePrevi ew 
(1-24)  allows  you  to  add  the  preview  to  a  file. 


Functions 


MakeFi  1  ePrevi  ew  (11-784) 

Creates  a  preview  for  a  file. 

AddFi  1  ePrevi  ew  (1-24) 

Adds  a  preview  to  a  file. 


Displaying  File  Previews 

Four  Movie  Toolbox  functions  let  you  display  file  previews. 

Two  functions  allow  you  to  display  file  previews  in  an  Open  dialog  box  in  System 
6  using  standard  file  reply  structures:  SFGetFi  1  ePrevi  ew  (III— 1674)  and 
SFPGetFi  1  ePrevi  ew  (III— 1676).  Two  newer  functions  allow  you  to  display  file 
previews  in  an  Open  dialog  box  in  System  7  using  standard  file  reply  structures: 
StandardGetFi  1  ePrevi  ew  (III — 1910)  and  CustomGetFi  1  ePrevi  ew. 

These  functions  allow  the  user  to  automatically  convert  files  to  movies  if  your 
application  requests  movies.  If  there  is  a  file  that  can  be  converted  into  a  movie  file 
using  a  movie  import  component,  then  the  file  is  shown  in  the  Standard  File  dialog 
box  in  addition  to  any  movies.  When  the  user  selects  the  file,  the  Open  button 
changes  to  a  Convert  button.  Choosing  Convert  displays  a  dialog  box  that  allows 
the  user  to  choose  where  the  converted  file  should  be  saved. 

When  conversion  is  complete,  the  converted  file  is  returned  to  the  calling 
application  as  the  movie  that  the  user  chose.  If  you  want  to  disable  automatic  file 
conversion  in  your  application,  you  must  write  a  file  filter  function  and  pass  it  to  the 
file  preview  display  function  you  are  using. 


Functions 


SFGetFi  1  ePrevi  ew  (III — 1674) 

Displays  a  file  preview  in  an  Open  dialog  box  using  a  standard  file  reply 
structure. 

SFPGetFi  1  ePrevi  ew  (III — 1 676) 

Displays  file  previews  in  an  Open  dialog  box  using  a  standard  file  reply 
structure. 
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StandardGetFi  1  ePrevi ew  (III — 1 910) 

Displays  file  previews  in  an  Open  dialog  box  using  a  standard  file  reply 
structure. 

CustomGetFi  1  ePrevi  ew  (1-163) 

Presents  an  Open  dialog  box  to  the  user  and  allows  the  user  to  view  file 
previews. 


Working  With  Time  Bases 


SUM 


The  Movie  Toolbox  provides  a  number  of  functions  that  allow  you  to  work  with 
time  bases.  A  QuickTime  time  base  defines  the  time  coordinate  system  of  a  movie. 
However,  you  can  also  use  QuickTime  time  bases  to  provide  general  timing 
services. 

Note  that  time  base  functions  do  not  change  the  value  of  the  Movie  Toolbox  sticky 
error  value.  Although  most  time  base  functions  can  be  used  at  interrupt  time, 
several  of  the  Movie  Toolbox  functions  cannot.  For  further  information,  see  the 
detailed  function  descriptions. 


Creating  and  Disposing  of  Time  Bases 

The  Movie  Toolbox  provides  several  functions  your  application  can  use  to  create 
and  dispose  of  time  bases. 

NewT i  meBase  (11-1119)  lets  you  create  a  new  time  base.  You  can  use  Di  sposeT i  meBase 
(1-299)  to  dispose  of  a  time  base  once  you  are  finished  with  it. 

Time  bases  rely  on  either  a  clock  component  or  another  time  base  for  their  time 
source.  You  can  use  SetT imeBaseMasterTi  meBase  (III— 1650)  to  cause  one  time  base  to 
be  based  on  another  time  base.  GetTi meBaseMasterTi meBase  (1-517)  allows  you  to 
determine  the  master  time  base  of  a  given  time  base. 

You  can  assign  a  clock  component  to  a  time  base;  that  clock  then  acts  as  the  master 
clock  for  the  time  base.  You  can  use  SetT i  meBaseMasterCl  ock  (III— 1649)  to  assign  a 
clock  component  to  a  time  base.  GetT i meBaseMasterCl  ock  (1-516)  enables  you  to 
determine  the  clock  component  that  is  assigned  to  a  time  base. 
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You  can  change  the  offset  between  a  time  base  and  its  time  source  by  calling 
SetTimeBaseZero  (III— 1 655).Youcanset  the  time  source  of  a  movie  by  calling 
SetMovi  eMasterTimeBase  (III — 1621)  or  SetMovi  eMasterClock. 


Functions 

NewTimeBase  (11-1119) 

Obtains  a  new  time  base. 

DisposeTimeBase  (1-299) 

Disposes  of  a  time  base  once  you  are  finished  with  it. 

SetTi meBaseMasterTimeBase  (III — 1650) 

Assigns  a  master  time  base  to  a  time  base. 

GetTi meBaseMasterTimeBase  (1-517) 

Determines  the  master  time  base  that  is  assigned  to  a  time  base. 

SetTi  me  BaseMasterClock  (III — 1 649) 

Assigns  a  clock  component  to  a  time  base. 

GetT i  meBaseMasterCl  ock  (1-516) 

Determines  the  clock  component  that  is  assigned  to  a  time  base. 
SetTimeBaseZero  (III — 1 655) 

Changes  the  offset  from  a  time  base  to  either  its  master  time  base  or  its  clock 
component. 

SetMovi  eMasterTimeBase  (III — 1621) 

Assigns  a  master  time  base  to  a  movie. 

SetMovi  eMasterCl  ock  (III — 1 620) 

Assigns  a  clock  component  to  a  movie. 

Working  With  Time  Base  Values 

Every  time  base  contains  a  rate,  a  start  time,  a  stop  time,  a  current  time,  and  some 
status  information.  The  Movie  Toolbox  provides  a  number  of  functions  that  allow 
your  application  to  work  with  the  contents  of  a  time  base. 

GetT i  meBaseTi  me  (1-521)  lets  you  retrieve  the  current  time  value  of  a  time  base.  You 
can  set  the  current  time  value  by  calling  SetT i  meBaseT i  me  (III— 1653);  this  function 
requires  you  to  provide  a  time  structure.  Alternatively,  you  can  set  the  current  time 
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based  on  a  time  value  by  calling  SetTi  meBaseVal  ue  (III— 1654). 


You  can  determine  the  rate  of  a  time  base  by  calling  GetT i  meBaseRate  (1-518).  You 
can  set  the  rate  of  a  time  base  by  calling  SetTi  meBaseRate  (III— 1651).  You  can 
determine  the  effective  rate  of  a  specified  time  base  (relative  to  the  master  time  base 
to  which  it  is  subordinate)  by  calling  GetT i meBaseEf  f  ecti  veRate  (1-514). 

You  can  retrieve  the  start  time  of  a  time  base  by  calling  GetTimeBaseStartTime 
(1-518).  You  can  set  the  start  time  of  a  time  base  by  calling  SetT i meBaseStartT i me 
(III— 1652).  Similarly,  you  can  use  GetTimeBaseStopTime  (1-520)  and 
SetT i  meBaseStopT i  me  to  work  with  the  stop  time  of  a  time  base. 

The  Movie  Toolbox  provides  functions  that  allow  you  to  work  with  the  status 
information  of  a  time  base.  GetTi  meBaseStatus  (1-519)  allows  you  to  read  the  current 
status  of  a  time  base.  GetT imeBaseFlags  (1-515)  helps  you  obtain  the  control  flags  of 
a  time  base.  You  can  set  these  flags  by  calling  SetTi  meBaseFlags  (III— 1648). 
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Functions 

GetTimeBaseTime  (1-521) 

Obtains  the  current  time  value  from  a  time  base. 

SetTimeBaseTime  (III — 1 653) 

Sets  the  current  time  of  a  time  base. 

SetT i meBaseVal  ue  (III — 1 654) 

Sets  the  current  time  of  a  time  base. 

GetTimeBaseRate  (1-518) 

Retrieves  the  rate  of  a  time  base. 

SetTimeBaseRate  (III — 1651) 

Sets  the  rate  of  a  time  base. 

GetTimeBaseEffecti  veRate  (1-514) 

Returns  the  effective  rate  at  which  the  specified  time  base  is  moving  relative  to 
its  master  clock. 

GetTimeBaseStartTime  (1-518) 

Determines  the  start  time  of  a  time  base. 

SetT i  meBaseStartTi  me  (III — 1 652) 

Sets  the  start  time  of  a  time  base. 
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GetTimeBaseStopTime  (1-520) 

Determines  the  stop  time  of  a  time  base. 

SetTimeBaseStopTime  (III — 1 652) 

Sets  the  stop  time  of  a  time  base. 

GetTimeBaseStatus  (1-519) 

Determines  when  the  current  time  of  a  time  base  would  fall  outside  of  the  range 
of  values  specified  by  the  time  base's  start  and  stop  times. 

GetTimeBaseFl  ags  (1-515) 

Obtains  the  control  flags  of  a  time  base. 

SetTimeBaseFl  ags  (III — 1 648) 

Sets  the  contents  of  the  control  flags  of  a  time  base. 


Working  With  Times 

The  Movie  Toolbox  provides  a  number  of  functions  that  allow  you  to  work  with 
time  structures;  see  "The  Time  Structure"  (V-2710).  You  can  use  time  structures  to 
represent  either  time  values  or  durations.  Time  values  specify  a  point  in  time, 
relative  to  a  given  time  base.  Durations  specify  a  span  of  time,  relative  to  a  given 
time  scale.  Durations  are  represented  by  time  structures  that  have  the  time  base  set 
to  0  (that  is,  the  base  field  in  the  time  structure  is  set  to  NIL). 

You  can  use  ConvertT i  me  (1-137)  to  convert  a  time  you  obtain  from  one  time  base 
into  a  time  that  is  relative  to  another  time  base.  Similarly,  you  can  use 
Conver tTi meScal  e  (1-138)  to  convert  a  time  from  one  time  scale  to  another.  You  can 
add  two  times  by  calling  AddT i  me  (1-41);  you  can  subtract  two  times  with 
SubtractTi me  (III — 1915). 


Functions 


ConvertTime  (1-137) 

Converts  a  time  obtained  from  one  time  base  into  a  time  that  is  relative  to 
another  time  base. 

ConvertTimeScale  (1-138) 

Converts  a  time  from  one  time  scale  into  a  time  that  is  relative  to  another  time 
scale. 

AddT i  me  (1-41) 

Adds  two  times. 
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SubtractTime  (III — 1 915) 

Subtracts  one  time  from  another. 


Time  Base  Callback  Functions 


If  your  application  uses  QuickTime  time  bases,  it  may  define  callback  functions  that 
are  associated  with  a  specific  time  base.  Your  application  can  then  use  these  callback 
functions  to  perform  activities  that  are  triggered  by  temporal  events,  such  as  a 
certain  time  being  reached  or  a  specified  rate  being  achieved.  The  time  base 
functions  of  the  Movie  Toolbox  interact  with  clock  components  to  schedule  the 
invocation  of  these  callback  functions;  the  clock  components  are  responsible  for 
invoking  the  callback  function  at  its  scheduled  time. 

You  can  define  three  types  of  callback  events,  distinguished  by  the  nature  of  the 
temporal  event  that  triggers  the  Movie  Toolbox  to  call  your  function.  They  include 
events  that  are  triggered  at  a  specified  time,  events  that  are  triggered  when  the  rate 
reaches  a  specified  value,  and  events  that  are  triggered  when  the  time  value  of  a 
time  base  changes  by  an  amount  different  from  the  time  base's  rate. 

You  specify  a  callback  event's  type  when  you  define  the  callback  event,  using 
NewCal  1  Back  (11-1053).  This  function  also  allocates  the  memory  to  support  the 
callback  event. 

You  also  specify  whether  your  event  can  occur  at  interrupt  time.  Your  function  is 
called  closer  to  the  triggering  event  at  interrupt  time,  but  it  is  subject  to  all  the 
restrictions  of  interrupt  functions  (for  example,  your  callback  function  cannot  cause 
memory  to  be  moved).  If  your  function  is  not  called  at  interrupt  time,  you  are  free 
of  these  restrictions,  but  your  function  may  be  called  later  because  the  invocation  is 
delayed  to  avoid  interrupt  time. 

You  schedule  a  callback  event  by  calling  Cal  1  MeWhen  (1-67).  Call  Cancel  Cal  1  Back 
(1-70)  to  unschedule  a  callback  event.  When  you  are  done  with  a  callback  event,  you 
dispose  of  it  by  calling  DisposeCallBack  (1-256). 

You  can  retrieve  the  time  base  of  a  callback  event  by  calling  GetCal  1  BackT i meBase 
(1-384).  You  can  obtain  the  type  of  a  callback  event  by  calling  GetCal  1  BackType 
(1-384). 
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Functions 


NewCal  1  Back  (11-1053) 

Creates  a  new  callback  event. 

Cal  1  MeWhen  (1-67) 

Schedules  a  callback  event. 

Cancel  Call  Back  (1-70) 

Cancels  a  callback  event  before  it  executes. 

Di sposeCal  1  Back  (1-256) 

Disposes  of  a  callback  event. 

GetCallBackTimeBase  (1-384) 

Retrieves  the  time  base  of  a  callback  event. 

GetCal  1  BackType  (1-384) 

Retrieves  a  callback  event's  type. 

Callbacks 

QTCal  1  BackProc  (III— 2124) 

A  generic  callback  function,  installed  byCallMeWhen  (1-67). 


Working  With  Matrices 


The  Movie  Toolbox  makes  extensive  use  of  transformation  matrices  to  define 
graphical  operations  that  are  performed  on  movies  when  they  are  displayed.  A 
transformation  matrix  defines  how  to  map  points  from  one  coordinate  space  into 
another  coordinate  space.  By  modifying  the  contents  of  a  transformation  matrix, 
you  can  perform  several  standard  graphical  display  operations,  including 
translation,  rotation,  and  scaling.  The  Movie  Toolbox  provides  a  set  of  functions 
that  make  it  easy  for  you  to  manipulate  and  apply  translation  matrices. 


Managing  Matrices 

The  Movie  Toolbox  provides  several  functions  that  help  you  create,  modify,  and 
compare  matrices. 
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These  functions  are  listed  below. 


Functions 

SetldentityMatrix  (III — 1 593) 

Sets  the  contents  of  a  matrix  so  that  it  performs  no  transformation. 

GetMatri  xType  (1-419) 

Obtains  information  about  a  matrix. 

CopyMatrix  (1-139) 

Copies  the  contents  of  one  matrix  into  another  matrix. 

Equal  Matri x  (1-338) 

Compares  two  matrices  and  returns  a  result  that  indicates  whether  the  matrices 
are  equal. 

Transl  ateMatri x  (III — 1 956) 

Adds  a  translation  value  to  a  specified  matrix. 

Seal  eMatri x  (III — 1527) 

Modifies  the  contents  of  a  matrix  so  that  it  defines  a  scaling  operation. 
RotateMatrix  (III — 1462) 

Modifies  the  contents  of  a  matrix  so  that  it  defines  a  rotation  operation. 
SkewMatrix  (III — 1827) 

Modifies  the  contents  of  a  matrix  so  that  it  defines  a  skew  transformation. 
ConcatMatrix  (1-128) 

Concatenates  two  matrices,  combining  the  transformations  described  by  both 
matrices  into  a  single  matrix. 

InverseMatrix  (11-774) 

Creates  a  new  matrix  that  is  the  inverse  of  a  specified  matrix. 

RectMatrix  (III — 1451) 

Creates  a  matrix  that  performs  the  translate  and  scale  operation  described  by 
the  relationship  between  two  rectangles. 

MapMatrix  (11-794) 

Alters  an  existing  matrix  so  that  it  defines  a  transformation  from  one  rectangle 
to  another. 
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Applying  Matrix  Transformations 

The  Movie  Toolbox  provides  several  functions  that  help  you  apply  matrices  to 
various  graphic  entities. 

These  functions  are  listed  below. 


Functions 

TransformPoi nts  (III — 1953) 

Transforms  a  set  of  QuickDraw  points  through  a  specified  matrix. 

TransformFi xedPoi nts  (III — 1 951) 

Transforms  a  set  of  fixed  points  through  a  specified  matrix. 

TransformRect  (III — 1 954) 

Transforms  the  upper-left  and  lower-right  points  of  a  rectangle  through  a 
specified  matrix. 

TransformFi xedRect  (III — 1952) 

Transforms  the  upper-left  and  lower-right  points  of  a  rectangle  through  a 
matrix  that  is  specified  by  fixed  points. 

TransformRgn  (III — 1955) 

Applies  a  specified  matrix  to  a  region. 


Working  With  QT  Atoms 


QuickTime  atoms  are  basic  data  containers  used  in  QuickTime  programming. 
QuickTime  contains  a  complete  set  of  functions  for  creating,  manipulating,  finding, 
and  accessing  QT  atoms  and  atom  containers. 


Creating  and  Disposing  of  Atom  Containers 

The  Movie  Toolbox  provides  two  calls  to  let  you  create  and  dispose  of  QuickTime 
atom  containers. 


V-2766 


Inside  QuickTime:  Programming  Summary 


Before  you  can  add  atoms  to  an  atom  container,  you  must  first  create  the  container 
by  calling  QTNewAtomContai  ner  (11-1203).  When  you  have  finished  using  an  atom 
container,  you  should  dispose  of  it  by  calling  QTDi  sposeAtomContai  ner  (11-1164). 


Functions 


QTNewAtomContai  ner  (11-1203) 

Creates  a  new  atom  container. 

QTDi  sposeAtomContai  ner  (11-1164) 
Disposes  of  an  atom  container. 
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Creating  New  Atoms 

Once  you  have  created  an  atom  container,  the  Movie  Toolbox  provides  a  call  to  let 
you  place  new  QuickTime  atoms  in  it. 

QTInsertChi  1  d  (11-1183)  creates  a  new  child  atom  for  a  parent  atom.  The  caller 
specifies  an  atom  type  and  atom  ID  for  the  new  atom.  If  you  specify  a  value  of  0  for 
the  atom  ID,  QTInsertChi  1  d  (11-1183)  assigns  a  unique  ID  to  the  atom. 

This  function  inserts  the  atom  in  the  parent's  child  list  at  the  index  specified  by  the 
i  ndex  parameter;  any  existing  atoms  at  the  same  index  or  greater  are  moved  toward 
the  end  of  the  child  list.  If  you  specify  a  value  of  0  for  the  index  parameter,  it  inserts 
the  atom  at  the  end  of  the  child  list. 


Functions 


QTInsertChi  1  d  (11-1183) 

Creates  a  new  child  atom  of  the  specified  parent  atom. 


Copying  Existing  Atoms 

The  Movie  Toolbox  provides  several  functions  for  copying  existing  atoms  within  an 
atom  container. 

QTInsertChi  1  dren  (11-1185)  inserts  a  container  of  atoms  as  children  of  a  parent  atom 
in  another  atom  container.  QTRepl  aceAtom  (11-1217)  replaces  an  atom  and  its  children 
with  a  different  atom  and  its  children.  You  can  call  QTSwapAtoms  (11-1315)  to  swap 
the  contents  of  two  atoms  in  an  atom  container;  after  swapping,  the  ID  and  index  of 
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each  atom  remains  the  same.  QTCopyAtom  (11-1158)  copies  an  atom  and  its  children  to 
a  new  atom  container. 


Functions 

QTInsertChi  1  dren  (11-1185) 

Inserts  a  container  of  atoms  as  children  of  the  specified  parent  atom. 

QTRepl  aceAtom  (11-1217) 

Replaces  the  contents  of  an  atom  and  its  children  with  a  different  atom  and  its 
children. 

QTSwapAtoms  (11-1315) 

Swaps  the  contents  of  two  atoms  in  an  atom  container. 

QTCopyAtom  (11-1158) 

Copies  an  atom  and  its  children  to  a  new  atom  container. 


Retrieving  Atoms  and  Atom  Data 

The  Movie  Toolbox  provides  functions  you  can  use  to  retrieve  information  about 
the  types  of  a  parent  atom's  children,  to  search  for  a  specific  atom,  and  to  retrieve  a 
leaf  atom's  data. 

QTCountChi  1  drenOfType  (11-1160)  returns  the  number  of  children  of  a  given  atom 
type  for  a  parent  atom.  QTGetNextChi  1  dType  (11-1178)  returns  the  next  atom  type  in 
the  child  list  of  a  parent  atom. 

You  call  QTFi  ndChi  1  dBy  Index  (11-1167)  to  search  for  and  retrieve  a  parent  atom's 
child  by  its  type  and  index  within  that  type.  You  can  call  QTFi  ndChi  1  dBy  ID  (11-1166) 
to  search  for  and  retrieve  a  parent  atom's  child  by  its  type  and  ID.  Once  you  have 
retrieved  a  child  atom,  you  can  call  QTNextChi  1  dAnyType  (11-1209)  to  retrieve 
subsequent  children  of  a  parent  atom.  It  returns  an  offset  to  the  next  atom  of  any 
type  in  a  parent  atom's  child  list.  This  function  is  useful  for  iterating  through  a 
parent  atom's  children  quickly. 

QuickTime  also  provides  functions  for  retrieving  an  atom's  type,  ID,  and  data.  You 
can  call  QTGetAtomTypeAndID  (11-1172)  to  retrieve  an  atom's  type  and  ID.  You  can 
access  an  atom's  data  in  one  of  three  ways.  To  copy  an  atom's  data  to  a  handle,  you 
can  use  QTCopyAtomDataToHandl  e  (11-1158). 

To  access  an  atom's  data  directly,  you  should  lock  the  atom  container  in  memory  by 
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calling  QTLockContai  ner  (11-1187).  Once  the  container  is  locked,  you  can  call 
QTGetAtomDataPtr  (11-1171)  to  retrieve  a  pointer  to  an  atom's  data.  When  you  have 
finished  accessing  the  atom's  data,  you  should  call  the  QTUnlockContainer  (11-1316) 
function  to  unlock  the  container  in  memory. 


Functions 

QTCountChi  1  drenOfType  (11-1160) 

Returns  the  number  of  atoms  of  a  given  type  in  the  child  list  of  the  specified 
parent  atom. 

QTGetNextChi  1  dType  (11-1178) 

Returns  the  next  atom  type  in  the  child  list  of  the  specified  parent  atom. 

QTFi ndChi  1  dBylndex  (11-1167) 

Retrieves  an  atom  by  index  from  the  child  list  of  the  specified  parent  atom. 
QTFi  ndChi  IdBylD  (11-1166) 

Retrieves  an  atom  by  ID  from  the  child  list  of  the  specified  parent  atom. 
QTNextChi  1  dAnyType  (11-1209) 

Returns  the  next  atom  in  the  child  list  of  the  specified  parent  atom. 

QTGetAtomTypeAndID  (11-1172) 

Retrieves  an  atom's  type  and  ID. 

QTCopyAtomDataToHandl  e  (11-1158) 

Copies  the  specified  leaf  atom's  data  to  a  handle. 

QTCopyAtomDataToPtr  (11-1159) 

Copies  the  specified  leaf  atom's  data  to  a  buffer. 

QTGetAtomDataPtr  (11-1171) 

Retrieves  a  pointer  to  the  atom  data  for  a  specified  leaf  atom. 

QTLockContainer  (11-1187) 

Locks  an  atom  container  in  memory. 

QTUnl  ockContai  ner  (11-1316) 

Unlocks  an  atom  container  in  memory. 
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Modifying  Atoms 

QuickTime  provides  functions  that  you  can  call  to  modify  attributes  or  data 
associated  with  an  atom  in  an  atom  container. 
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To  modify  an  atom's  ID,  call  QTSetAtomlD  (11-1225).  You  can  use  QTSetAtomData 
(11-1223)  to  update  the  data  associated  with  a  leaf  atom  in  an  atom  container. 


Functions 


QTSetAtomlD  (11-1225) 

Changes  the  ID  of  an  atom. 

QTSetAtomData  (11-1223) 

Changes  the  data  of  a  leaf  atom. 


Removing  Atoms  From  an  Atom  Container 

The  Movie  Toolbox  provides  two  function  that  let  you  remove  atoms  from  a 
container. 

QTRemoveAtom  (11-1215)  removes  an  atom  and  its  children,  if  any,  from  a  container. 
QTRemoveChi  1  dren  (11-1216)  removes  an  atom's  children  from  a  container,  but  does 
not  remove  the  atom  itself.  You  can  also  use  this  function  to  remove  all  the  atoms  in 
an  atom  container.  To  do  so,  pass  the  constant  kParentAtomlsContai  ner  for  the  atom 
parameter. 


Functions 


QTRemoveAtom  (11-1215) 

Removes  an  atom  and  its  children  from  the  specified  atom  container. 
QTRemoveChi  1  dren  (11-1216) 

Removes  all  the  children  of  an  atom  from  the  specified  atom  container. 


Working  With  Access  Keys 


Certain  compression  formats,  such  as  the  Intel  Indeo  format  for  video  compression, 
allow  data  to  be  encrypted  when  it  is  compressed.  For  software  to  gain  access  to  the 
encrypted  data,  the  access  key  for  the  data  must  be  registered  with  QuickTime.  For 
example,  a  CD-ROM  title  would  register  one  or  more  access  keys  for  encrypted 
video  data  it  presents.  Once  the  access  keys  are  registered,  the  keys  are  available  to 
the  decompressor  component  that  will  be  used  to  decompress  the  data.  The 
CD-ROM  title  can  then  use  the  encrypted  data  in  the  same  way  it  uses  unencrypted 
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data. 


The  scope  of  an  access  key  is  determined  when  it  is  registered.  If  a  key  is  registered 
as  a  system  access  key,  data  protected  by  that  key  is  available  to  any  QuickTime 
client  on  the  computer.  If  a  key  is  registered  as  an  application  access  key,  data 
protected  by  the  key  is  available  only  to  QuickTime  clients  of  the  application  that 
registers  the  key. 

Although  most  access  keys  are  character  strings,  an  access  key  can  be  of  any  data 
type.  Users  can  enter,  edit,  and  delete  system  access  keys  in  the  QuickTime  control 
panel.  Access  keys  entered  in  the  QuickTime  control  panel  are  always  registered  as 
system  access  keys. 
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Registering  and  Unregistering  Access  Keys 

Two  functions  let  your  application  register  and  unregister  access  keys. 

Use  QTRegi  sterAccessKey  (11-1214)  to  register  an  access  key;  use 
QTUnregi  sterAccessKey  (11-1317)  to  unregister  it. 


Functions 


QTRegi  sterAccessKey  (11-1214) 

Registers  an  access  key. 

QTUnregi  sterAccessKey  (11-1317) 

Removes  a  previously  registered  access  key. 


Retrieving  Access  Keys 

A  Movie  Toolbox  function  lets  your  application  determine  all  the  application  and 
system  access  keys  of  a  specified  access  key  type. 

Use  QTGetAccessKeys  (11-1168)  to  return  an  atom  container  with  the  current  access 
keys. 


Functions 

QTGetAccessKeys  (11-1168) 

Returns  all  the  application  and  system  access  keys  of  a  specified  access  key 
type. 
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Managing  Progressive  Downloads 


The  Movie  Toolbox  includes  support  for  progressive  downloads,  which  allow  part 
of  a  movie  to  be  displayed  before  all  of  its  data  has  been  received  over  a  network  or 
other  slow  link.  Applications  that  use  the  movie  controller  component  provided  by 
Apple  automatically  get  support  for  progressive  downloads. 


High-Level  Download  Control 

Applications  that  do  not  use  the  standard  move  controller  can  use  two  high-level 
functions  to  control  progressive  downloads. 

You  can  use  QTMovi  eNeedsT i  meTabl  e  (11-1202)  and  GetMaxLoadedTi  melnMovi  e  to 
determine  whether  a  movie  is  being  progressively  downloaded  and,  if  so,  to  see 
how  much  of  it  has  already  been  downloaded. 


Functions 

QTMovieNeedsTimeTable  (11-1202) 

Returns  whether  a  movie  is  being  progressively  downloaded. 

GetMaxLoadedTi melnMovi  e  (1-423) 

When  a  movie  is  being  progressively  downloaded,  returns  the  duration  of  the 
part  of  a  movie  that  has  already  been  downloaded. 

See  Also 

See  "Low-Level  Download  Control"  (V-2772). 


Low-Level  Download  Control 


Some  applications  may  need  more  control  over  progressive  downloads,  such  as 
control  over  individual  tracks  or  media,  than  is  possible  with  the  high-level 
functions  for  progressive  downloads. 

You  can  use  one  or  both  of  the  functions  MakeT rackT i  meTabl  e  (11-793)  and 
MakeMedi  aTi meTabl  e  for  low-level  download  control. 
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Functions 


MakeTrackTimeTable  (11-793) 

Returns  a  time  table  for  a  specified  track  in  a  movie. 

MakeMedi  aTi  meTabi  e  (11-788) 

Returns  a  time  table  for  the  specified  media. 

See  Also 

See  "High-Level  Download  Control"  (V-2772). 
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Using  Movie  Controllers 


Movie  controller  components  provide  a  high-level  interface  that  allows  your 
application  to  present  movies  to  users  quickly  and  easily.  Movie  controller 
components  eliminate  much  of  the  complexity  of  working  with  movies  by 
assuming  primary  responsibility  for  the  movie,  freeing  your  application  to  focus  on 
the  unique  services  it  offers  to  users. 


Movie  Controller  Actions 


Movie  controller  actions  are  designated  by  integer  constants  (defined  by  the 
mcActi  on  data  type)  used  by  movie  controller  components. 

Applications  that  use  movie  controller  components  can  invoke  these  actions  by 
calling  MCDoActi  on  (11-801).  If  the  application  includes  an  action  filter  function,  that 
function  may  receive  any  of  these  actions.  You  can  install  an  action  filter  with 
MCSetActi  onFi  1  terWi  thRefCon  (11-829). 

Your  action  filter  function  should  refer  any  actions  that  you  do  not  want  to  handle 
back  to  the  calling  movie  controller  component.  If  you  use  any  Movie  Toolbox 
functions  that  modify  the  movie  in  your  action  filter  function,  be  sure  to  call 
MCMovi eChanged  (11-822). 


Functions 


MCDoActi  on  (II — 8 01) 

Invokes  a  movie  controller  component  and  makes  it  perform  a  specified  action. 
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MCSetActi  onFilterWithRefCon  (11-829) 

Establishes  an  action  filter  function  for  a  movie  controller. 

MCMovi  eChanged  (11-822) 

Informs  a  movie  controller  component  that  your  application  has  used  the 
Movie  Toolbox  to  change  the  characteristics  of  its  associated  movie. 

Callback 

MCActi  onFilterWithRefConProc  (III — 2097) 

Responds  to  movie  controller  actions  with  a  reference  constant. 


Associating  Movies  With  Controllers 

Once  your  application  has  established  a  connection  to  a  movie  controller 
component,  you  may  associate  one  movie  with  a  movie  controller.  By  default,  the 
new  controller  has  editing  and  keystroke  processing  turned  off. 

You  create  a  new  movie  controller  and  assign  it  to  a  movie  by  calling 
NewMovi  eControl  1  er  (11-1071).  This  is  the  easiest  way  to  use  a  movie  controller 
component.  If  you  want  to  assign  a  movie  to  an  existing  controller,  you  can  use 
MCNewAttachedControl  1  er  (11-823).  Use  MCSetMovi  e  to  assign  a  movie  to  or  remove  a 
movie  from  a  controller.  You  can  use  MCGetlndMovi  e  (11-812)  to  retrieve  a  reference 
to  the  movie  that  is  assigned  to  a  controller.  When  you  are  done  with  a  controller, 
call  Di  sposeMovi  eControl  1  er  (1-270)  to  dispose  of  it. 


Functions 

NewMovi  eControl  1  er  (11-1071) 

Locates  a  movie  controller  component  and  assigns  a  movie  to  that  controller. 

MCNewAttachedControl  1  er  (11-823) 

Associates  a  specified  movie  with  a  movie  controller. 

MCSetMovi  e  (11-835) 

Associates  a  movie  with  a  specified  movie  controller. 

MCGetlndMovi  e  (11-812) 

Lets  your  application  to  retrieve  the  movie  reference  for  a  movie  that  is 
associated  with  a  movie  controller. 

Di  sposeMovi  eControl  ler  (1-270) 

Disposes  of  a  movie  controller. 
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Managing  Controller  Attributes 


Movie  controller  components  provide  a  number  of  functions  that  allow  your 
application  to  control  the  display  attributes  of  a  movie  controller.  For  example,  you 
can  detach  the  controller  from  its  movie,  so  that  the  controller  and  movie  can  be 
managed  as  separate  graphics  entities.  In  addition,  movie  controller  components 
provide  a  number  of  functions  that  allow  you  to  work  with  a  controller's  boundary 
rectangles  and  regions. 

MCSetControl  1  erAttached  (11-831)  lets  you  control  whether  the  movie  controller  is 
attached  to  its  movie.  MCIsControl  1  erAttached  (11-818)  allows  you  to  determine  if  a 
controller  is  attached  to  its  movie.  You  can  use  MCSetControl  1  erPort  (11-833)  and 
MCGetControl  1  erPort  to  work  a  movie  controller's  graphics  port.  MCSetVi  si  bl  e 
(11-837)  and  MCGetVi  si  bl  e  (11-815)  enable  you  to  control  the  visibility  of  the  movie 
controller. 

MCSetControl  lerBoundsRect  (11-832)  and  MCGetControl  lerBoundsRect  help  you  work 
with  a  movie  controller's  boundary  rectangle.  You  can  use 

MCGetControl  lerBoundsRgn  (11-807)  and  MCGetControl  1  erWi  ndowRgn  if  the  controller  is 
not  rectangular.  You  can  position  a  controller  and  its  movie  separately  by  calling 
MCPosi  ti  onControl  1  er  (11-824). 
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Functions 

MCSetControl  1  erAttached  (11-831) 

Lets  your  application  control  whether  a  movie  controller  is  attached  to  its 
movie  or  detached  from  it. 

MCIsControl  1  erAttached  (11-818) 

Returns  a  value  that  indicates  whether  a  movie  controller  is  attached  to  its 
movie. 

MCSetControl  1  erPort  (11-833) 

Lets  your  application  set  the  graphics  port  for  a  movie  controller. 

MCGetControl  1  erPort  (11-810) 

Returns  a  movie  controller's  color  graphics  port. 

MCSetVi  si  ble  (11-837) 

Lets  your  application  control  the  visibility  of  a  movie  controller. 

MCGetVi  sibl  e  (11-815) 

Returns  a  value  that  indicates  whether  or  not  a  movie  controller  is  visible. 
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MCSetControllerBoundsRect  (11-832) 

Lets  you  change  the  position  and  size  of  a  movie  controller. 

MCGetControl  1  erBoundsRect  (11-806) 

Returns  a  movie  controller's  boundary  rectangle. 

MCGetControllerBoiindsRgn  (11-807) 

Returns  the  actual  region  occupied  by  the  controller  and  its  movie. 

MCGetWi ndowRgn  (11-815) 

Determines  the  window  region  that  is  actually  in  use  by  a  controller  and  its 
movie. 

MCPosi  ti  onControl  1  er  (11-824) 

Controls  the  position  of  a  movie  and  its  controller  on  the  computer  display. 
MCSetCl  i  p  (11—830) 

Lets  you  set  a  movie  controller's  clipping  region. 

MCGetCl  ip  (11-805) 

Obtains  information  describing  a  movie  controller's  clipping  regions. 

MCDrawBadge  (11-804) 

Displays  a  controller's  badge. 


Handling  Movie  Events 

Movie  controller  components  provide  functions  that  handle  movie  controller 
actions.  Your  application  must  call  these  functions  whenever  an  event  occurs.  If  the 
movie  controller  component  handles  the  event,  your  application  can  loop  to  wait 
for  the  next  event.  Otherwise,  your  application  must  take  care  of  the  event  as  part 
of  its  normal  event  handling. 

Movie  controller  components  support  an  action  filter.  You  can  instruct  the  filter  to 
invoke  a  function  in  your  application  whenever  actions  occur.  This  action  filter 
function  can  then  perform  specialized  processing  or  refer  the  action  back  to  the 
movie  controller  component.  See  "Movie  Controller  Actions"  (V-2773). 

You  can  use  MCIsPl  ayerEvent  (11-819)  to  handle  events  for  a  movie  controller.  You 
can  obtain  information  about  the  current  state  of  the  movie  controller  and  its  movie 
by  calling  MCGetControl  1  erlnfo  (11-808). 
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Functions 


MCIsPl  ayerEvent  (11-819) 

Handles  all  events  for  a  movie  controller. 

MCGetControl  1  erlnfo  (11-808) 

Determines  the  current  status  of  a  movie  controller  and  its  associated  movie,  for 
menu  highlighting. 

MCPtlnControl  1  er  (11-826) 

Reports  whether  a  point  is  in  the  control  area  of  a  movie. 
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For  functions  that  invoke  and  filter  controller  events,  see  "Movie  Controller 
Actions"  (V-2773). 


Editing  Movies  With  a  Controller 

Movie  controller  components  can  provide  editing  capabilities.  Your  application  can 
use  several  functions  to  alter  movies  that  are  associated  with  movie  controllers. 

Your  application  uses  MCEnabl  eEdi  ti  ng  (11-805)  to  enable  editing  for  a  specified 
movie  controller.  Movie  controller  components  may  return  an  error  code  indicating 
that  editing  is  not  supported.  Use  MCIsEdi  ti  ngEnabl  ed  (11-818)  to  find  out  if  editing 
is  enabled  for  a  specified  controller. 

MCCopy  (11-800),  MCCut  (11-800),  MCPaste  (11-824),  MCC1  ear  (11-798),  and  MCUndo  (11-838) 
support  normal  editing  operations  on  movies  associated  with  movie  controllers. 
These  functions  operate  on  the  current  movie  selection. 

Two  functions  are  also  provided  that  facilitate  work  with  Edit  menus.  You  can  use 
MCSetUpEdi  tMenu  (11-836)  to  highlight  and  name  the  items  in  the  Edit  menu  for  your 
application,  and  MCGetMenuStri  ng  (11-814)  is  provided  for  you  to  use  with  a 
non-standard  Edit  menu. 


Functions 


MCEnabl  eEdi  ti  ng  (11-805) 

Enables  and  disables  editing  for  a  movie  controller. 

MCIsEdi  ti  ngEnabl  ed  (11-818) 

Determines  whether  editing  is  currently  enabled  for  a  movie  controller. 
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MCCopy  (11-800) 

Returns  a  copy  of  the  current  movie  selection  from  the  movie  associated  with  a 
specified  controller. 

MCCut  (11-800) 

Returns  a  copy  of  the  current  movie  selection  from  the  movie  associated  with  a 
specified  controller  and  then  removes  the  current  movie  selection  from  the 
source  movie. 

MCPaste  (11-824) 

Inserts  a  specified  movie  at  the  current  movie  time  in  the  movie  associated  with 
a  specified  controller. 

MCClear  (11-798) 

Removes  the  current  movie  selection  from  the  movie  associated  with  a 
specified  controller. 

MCUndo  (11-838) 

Lets  your  application  discard  the  effects  of  the  most  recent  edit  operation. 
MCSetUpEdi  tMenu  (11-836) 

Correctly  highlights  and  names  the  items  in  your  application's  Edit  menu. 
MCGetMenuStri ng  (11-814) 

Retrieves  the  text  string  for  a  movie  controller  menu  command. 

See  Also 

For  alternatives,  see  "Editing  Movies"  (V-2746). 


Getting  and  Setting  Movie  Controller  Time 

Movie  controller  components  provide  functions  that  allow  your  application  to  work 
with  temporal  aspects  of  movie  controllers. 

You  can  use  the  MCSetDurati  on  (11-834)  function  to  set  the  duration  of  a  movie 
controller  to  some  arbitrary  value.  The  MCGetCurrentT i  me  (11-810)  function  lets  you 
retrieve  the  time  value  represented  by  the  indicator  on  the  movie  controller's  slider. 


Functions 


MCSetDurati  on  (11-834) 

Lets  your  application  set  a  controller's  duration  in  the  case  where  a  controller 
does  not  have  a  movie  associated  with  it. 
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MCGetCurrentTime  (11-810) 

Obtains  the  time  value  represented  by  the  indicator  on  the  movie  controller's 
slider. 


Customizing  Event  Processing 

Movie  controller  components  provide  a  number  of  functions  that  allow  your 
application  to  customize  event  processing.  If  your  application  does  not  use 
MCIsPl  ayerEvent  (11-819),  you  can  use  these  functions  to  direct  movie  controller 
events  to  the  appropriate  movie  controller  component.  The  component  then 
attempts  to  handle  the  event. 

Your  application  obtains  the  values  for  many  of  the  function  parameters  from  the 
appropriate  event  structure.  Each  function  returns  a  value  that  indicates  whether  it 
handled  the  event.  If  the  controller  component  completely  handles  the  event,  the 
function  sets  the  return  value  to  1.  If  the  controller  component  does  not  handle  the 
event,  the  function  sets  the  return  value  to  0,  and  your  application  must  then  handle 
the  event. 

Your  application  can  use  the  functions  listed  below  for  customized  event 
processing. 
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Functions 

MCActi  vate  (11-795) 

Lets  a  controller  respond  to  activate,  deactivate,  suspend,  and  resume  events. 
MCC1  ick  (11-799) 

Lets  a  controller  respond  when  the  user  clicks  in  a  movie  controller  window. 
MCDraw  (11-803) 

Responds  to  an  update  event. 

MCIdle  (D-816) 

Performs  idle  processing  for  a  movie  controller. 

MCKey  (II— 8  21) 

Handles  keyboard  events  for  a  movie  controller. 

See  Also 

For  functions  that  invoke  and  filter  controller  events,  see  "Movie  Controller 
Actions"  (V-2773). 
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Managing  Components 


Besides  the  Movie  Toolbox,  the  QuickTime  system  software  contains  some  200  or  so 
components.  Each  component  is  a  piece  of  QuickTime  code  that  provides  a  defined 
set  of  services  to  one  or  more  clients.  Applications,  system  extensions,  and  other 
components  use  these  services.  Multiple  components  can  provide  the  same  type  of 
service,  but  all  components  of  the  same  type  must  support  the  same  basic  interface. 
This  allows  your  application  to  use  the  same  interface  for  any  given  type  of 
component  and  get  the  same  type  of  service,  yet  allows  your  application  to  obtain 
different  levels  of  service. 

The  Component  Manager  allows  your  application  to  find  and  utilize  various 
components  at  run  time.  It  provides  access  to  components  and  manages  them  by 
keeping  track  of  the  currently  available  components  and  routing  requests  to  the 
appropriate  one.  You  can  also  create  your  own  components  and  use  the  Component 
Manager  to  help  manage  them. 


Component  Data  Structures 


Every  component  type  has  its  own  data  structures,  by  which  components  of  that 
type  communicate  with  their  clients;  for  further  information,  see  the  documentation 
for  each  component  type.  In  addition,  there  is  one  structure  that  all  components  use 
to  describe  themselves  through  the  Component  Manager. 

Your  application  can  use  the  ComponentDescri  pti  on  (IV-2212)  structure  to  find 
components  that  provide  specific  services  or  meet  other  selection  criteria.  It 
identifies  the  characteristics  of  a  component,  including  the  type  of  services  offered 
by  the  component  and  its  manufacturer. 


Data  Structure 


ComponentDescri  pti  on  (IV-2212) 

Describes  a  class  of  components  by  their  attributes. 
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Component  Functions  Used  By  Applications 


The  Component  Manager  provides  functions  that  allow  your  application  to  search 
for  components,  gain  access  to  and  release  components,  get  detailed  information 
about  specific  components,  and  get  component  error  information. 

When  using  Component  Manager  routines,  your  application  must  specify  the 
particular  component  by  either  a  component  identifier  or  a  component  instance. 
The  Component  Manager  identifies  each  component  by  a  component  identifier  of 
type  Component.  It  identifies  each  instance  of  a  component  by  a  component  instance 
of  type  Componentlnstance. 

You  can  use  CountComponents  (1-143)  to  determine  the  number  of  components  that 
match  a  component  description.  Use  Fi  ndNextComponent  (1-360)  to  find  an 
individual  component  that  matches  a  description. 

You  can  use  OpenDef  aul  tComponent  (11-1131)  to  open  a  component  of  a  specified 
component  type  and  subtype,  or  OpenComponent  (11—1130)  to  gain  access  to  a 
specified  component.  Use  Cl  oseComponent  (1-100)  to  close  an  open  component. 

Your  application  can  get  the  registration  information  for  any  component  using 
GetComponentlnfo  (1-389).  You  can  use  GetComponentlconSui  te  (1-387)  to  get  a 
handle  to  the  component's  icon  suite,  if  any.  In  addition,  for  components  to  which 
your  application  already  has  a  connection,  your  application  can  obtain  the 
component's  version  number  and  also  determine  whether  the  component  supports 
a  particular  request  by  using  GetComponentVersi  on  (1-395)  and 
Component  Fun cti onlmpl emented. 

Finally,  the  Component  Manager  provides  a  routine  that  allows  your  application  to 
retrieve  the  last  error  code  that  was  generated  by  a  component  instance.  Some 
component  routines  return  error  information  as  their  function  result.  Other 
component  routines  set  an  error  code  that  your  application  can  retrieve  using 
GetComponent InstanceError  (1-390). 
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Functions 


CountComponents  (1-143) 

Determines  the  number  of  registered  components  that  meet  a  given  set  of 
criteria. 


Inside  QuickTime:  Programming  Summary 


V-2781 


Programming  Summary 


Fi ndNextComponent  (1-360) 

Returns  the  component  identifier  for  the  next  registered  component  that  meets 
the  selection  criteria  specified  by  an  application. 

OpenDefaul  tComponent  (II — 1131) 

Gains  access  to  the  services  provided  by  a  component  specified  by  component 
type  and  subtype. 

OpenADefaul tComponent  (11-1129) 

Gains  access  to  the  services  provided  by  a  component,  specified  by  component 
type  and  subtype,  and  returns  an  OSErr  value. 

OpenComponent  (11-1130) 

Gains  access  to  the  services  provided  by  a  component  specified  by  a  component 
identifier. 

OpenAComponent  (11-1126) 

Gains  access  to  the  services  provided  by  a  component  specified  by  a  component 
identifier  and  returns  an  OSErr  value. 

Cl  oseComponent  (1-100) 

Terminates  your  application's  access  to  the  services  provided  by  a  component. 
GetComponentlnfo  (1-389) 

Returns  all  of  the  registration  information  for  a  component. 
GetComponentlconSui  te  (1-387) 

Returns  a  handle  to  the  component's  icon  suite  (if  it  provides  one). 

GetComponentVersi on  (1-395) 

Returns  a  component's  version  number. 

Component Functi on  Imp 1 emented (I —  111) 

Determines  whether  a  component  supports  a  specified  request. 

Get  Component  Instance  Error  (1-390) 

Returns  the  last  error  generated  by  a  specific  connection  to  a  component. 

Functions  Used  By  Components 

The  Component  Manager  provides  several  routines  that  components  can  use  to 
communicate  with  applications  and  with  one  another.  To  use  these  routines,  a 
component  must  first  be  registered. 
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Both  applications  and  components  can  use  either  Regi  sterComponent  (III— 1451)  or 
Regi  sterComponentResource  to  register  components,  or  they  can  use 
Regi  sterComponentResourceFi  1  e  (III— 1455)  to  register  all  components  specified  in  a 
given  resource  file.  All  components  stored  in  a  component  file  must  provide  a 
Component  Resource  (IV-2219)  structure. 

You  can  use  Unregi  sterComponent  (III— 1979)  to  remove  a  component  from  the 
registration  list,  and  GetComponentLi  stModSeed  (1-391)  to  determine  whether  the  list 
of  registered  components  has  changed.  A  component  can  use  SetDef  aul  tComponent 
(III— 1581)  to  change  the  order  in  which  the  list  of  registered  components  is  searched. 
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When  an  application  requests  service  from  your  component,  your  component 
receives  a  ComponentParameters  (IV-2216)  structure  containing  the  information  for 
that  request.  Your  component  can  use  this  structure  to  access  the  parameters 
directly,  or  it  can  use  certain  routines  to  extract  those  parameters  and  pass  them  to 
one  of  its  subroutines.  You  can  use  Cal  1  ComponentFuncti  on  (1-61)  to  call  a 
component  subroutine  without  providing  it  access  to  global  data.  You  can  use 
Cal  1  ComponentFuncti  onWi  thStorage  (1-61)  to  call  a  component  subroutine  while 
passing  it  a  handle  to  global  data  for  that  connection. 

Use  SetComponentlnstanceStorage  (III— 1572)  to  inform  the  Component  Manager  of 
the  memory  your  component  is  using  to  maintain  global  data  for  a  connection,  and 
GetComponentlnstanceStorage  (1-391)  to  retrieve  a  handle  to  that  storage.  Use 
CountComponentlnstances  (1-142)  to  count  all  the  connections  that  are  currently 
maintained  by  your  component. 

In  general,  your  component  returns  error  information  (0  or  nonzero)  in  its  function 
result;  however,  some  requests  require  that  your  component  return  other 
information.  In  these  cases,  your  component  can  use  SetComponentlnstanceError 
(III— 1571)  to  report  its  latest  error  state.  It  can  also  use  this  function  to  report  an  error 
at  any  time  during  component  execution. 

Each  component  is  assigned  a  reference  constant,  a  4-byte  value  that  it  can  use  in 
any  way.  Typically  you  use  the  reference  constant  to  store  the  address  of  a  data 
structure  that  is  shared  by  all  connections  maintained  by  your  component.  Use 
SetComponentRef  con  (III— 1573)  to  set  the  value  of  the  reference  constant,  and  use 
GetComponentRef  con  (1-394)  to  retrieve  its  value. 

If  you  store  your  component  in  a  component  resource  and  register  it,  or  if  the 
Component  Manager  automatically  registers  your  component,  your  component  can 
gain  read-only  access  to  its  resource  file.  Use  OpenComponentResFi  1  e  (11-1130)  to 
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open  your  component's  resource  file,  and  Cl  oseComponentResFi  1  e  (I— 101)  to  close 
the  resource  file  before  returning  to  the  calling  application. 

Del  egateComponentCal  1  (1-249)  allows  your  component  to  pass  a  request  to  a 
specified  component.  For  example,  you  might  want  to  create  two  similar 
components  that  provide  different  levels  of  service  to  applications.  Rather  than 
completely  implementing  both  components,  you  could  design  one  to  rely  on  the 
capabilities  of  the  other.  You  can  also  capture  and  override  a  component,  removing 
it  from  the  list  of  available  components.  Use  CaptureComponent  (1-74)  to  capture  a 
component  and  UncaptureComponent  (III— 1979)  to  restore  a  previously  captured 
component  to  the  search  list.  Your  component  can  target  a  component  instance 
without  capturing  the  component  or  your  component  can  first  capture  the 
component  and  then  target  a  specific  instance  of  the  component.  To  target  a 
component  instance,  use  ComponentSetTarget  (1-112). 


Functions 

Regi sterComponent  (III — 145 1) 

Makes  a  component  that  is  resident  in  memory  available  for  use  by  applications 
or  other  clients. 

Regi  sterComponentResource  (III — 1453) 

Makes  a  component  that  is  stored  in  a  file  available  for  use  by  applications  or 
other  clients. 

Regi sterComponentResourceFi  1  e  (III — 14551 

Registers  all  component  resources  in  a  given  resource  file. 

Unregi  sterComponent  (III — 1 979) 

Removes  a  component  from  the  Component  Manager's  registration  list. 

GetComponentLi  stModSeed  (1-391) 

Determines  if  the  list  of  registered  components  has  changed. 

GetComponentTypeModSeed  (1-395) 

Determines  if  the  specified  type  of  registered  component  has  changed. 

SetDefaul  tComponent  (III — 1 581) 

Changes  the  search  order  for  registered  components. 

Cal  1  ComponentFuncti  on  (1-61) 

Invokes  a  specified  function  of  your  component  with  the  parameters  originally 
provided  by  the  application  that  called  your  component. 
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Call  ComponentFuncti  onWith  Storage  (1-61) 

Invokes  a  specified  function  of  your  component  with  the  parameters  originally 
provided  by  the  application  that  called  your  component  and  provides  a  handle 
to  the  memory  associated  with  the  current  connection. 

Call ComponentFuncti onWithStorageProcInfo  (1-62) 

Invokes  a  specified  function  of  your  component  with  the  parameters  originally 
provided  by  the  application  that  called  it;  used  when  your  component  links 
with  Components  Interfaces  Li  b. 

SetComponentlnstanceStorage  (III — 1 572) 

Lets  a  component  pass  the  Component  Manager  a  handle  to  the  memory  that 
was  allocated  for  the  connection  to  it. 

GetComponentlnstanceStorage  (1-391) 

Lets  your  component  retrieve  a  handle  to  the  memory  associated  with  a 
component  connection. 

CountComponentlnstances  (1-142) 

Allows  you  to  determine  the  number  of  open  connections  being  managed  by  a 
specified  component. 

SetComponent InstanceError  (III — 1571) 

Lets  a  component  pass  error  information  to  the  Component  Manager  other 
than  through  its  return  value. 

SetComponentRef con  (III — 1 573) 

Sets  the  reference  constant  for  a  component. 

GetComponentRef con  (I — 394) 

Retrieves  the  value  of  the  reference  constant  for  your  component. 

OpenComponentResFi  1  e  (11-1130) 

Allows  your  component  to  gain  access  to  its  resource  file. 

OpenAComponentResFi  1  e  (11-1127) 

Allows  your  component  to  gain  access  to  its  resource  file  and  returns  an  OSErr 
value. 

Cl  oseComponentResFi  1  e  (I — 1 01) 

Closes  the  resource  file  that  your  component  opened  previously  with  the 
OpenComponentResFi  1  e  function. 
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Del  egateComponentCal  1  (1-249) 

Provides  an  efficient  mechanism  for  passing  on  requests  to  a  specified 
component. 

CaptureComponent  (1-74) 

Allows  your  component  to  capture  another  component. 

UncaptureComponent  (III — 1 979) 

Uncaptures  a  previously  captured  component. 

ComponentSetTarget  (1-112) 

Calls  a  component's  target  request  routine,  which  handles  the 
kComponentT a  rgetSel  ect  request  code. 

Data  Structures 

ComponentParameters  (IV — 2 216) 

Data  structure  passed  by  the  Component  Manager  to  a  component. 

ComponentResource  (IV-2219) 

Defines  the  structure  of  a  component  resource. 


Managing  Image  Compression 


The  Image  Compression  Manager  provides  image-compression  and 
image-decompression  services  to  applications  and  other  managers.  Image 
compression  benefits  you  by  decreasing  the  amount  of  storage  required  for  image 
data,  decreasing  the  time  required  to  exchange  image  data  across  networks,  and 
decreasing  the  time  required  to  read  data  from  disks  and  CD-ROM  volumes. 


Image  Compression  Data  Structures 


The  Image  Compression  Manager  uses  several  data  structures  to  communicate  with 
your  application. 

An  ImageDescri  pti  on  (IV-2285)  structure  contains  information  that  defines  the 
characteristics  of  a  compressed  image  or  sequence.  Data  in  the  image  description 
structure  indicates  the  type  of  compression  that  was  used,  the  size  of  the  image 
when  displayed,  the  resolution  at  which  the  image  was  captured,  and  so  on.  One 
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image  description  structure  may  be  associated  with  one  or  more  compressed 
frames. 

A  Codec  Info  (IV-2202)  structure  contains  compressor  information.  A  CodecNameSpec 
(IV-2208)  structure  contains  a  compressor's  name,  and  a  CodecNameSpecLi  st 
(IV-2208)  structure  contains  a  list  of  such  names. 

Data  Structures 

ImageDescri  pti  on  (IV-2285) 

Defines  the  characteristics  of  a  compressed  image  or  sequence. 
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Codeclnfo  (IV-2202) 

Describes  the  capabilities  of  a  compressor. 

CodecNameSpec  (IV-2208) 

Defines  a  compressor  name. 

CodecNameSpecLi  st  (IV-2208) 

Contains  a  list  of  CodecNameSpec  (IV-2208)  structures. 


Getting  Information  About  Compressed  Data 

Several  functions  enable  your  application  to  collect  information  about  compressed 
images  and  images  that  are  about  to  be  compressed.  Your  application  may  use  some 
of  these  functions  in  preparation  for  compressing  or  decompressing  an  image  or 
sequence. 

You  can  use  Get  Comp  res  si  onTime  (1-401)  to  determine  how  long  it  will  take  for  a 
compressor  to  compress  a  specified  image.  Similarly,  you  can  use 
GetMaxCompressi  onSi  ze  (1-420)  to  find  out  how  large  the  compressed  image  maybe 
after  the  compression  operation.  You  can  use  GetCompressedlmageSi  ze  (1-396)  to 
determine  the  size  of  a  compressed  image  that  does  not  have  a  complete  image 
description. 

GetSi  mi  1  a  ri  ty  (1-508)  allows  you  to  determine  how  similar  two  images  are.  This 
information  is  useful  when  you  are  performing  temporal  compression  on  an  image 
sequence. 


Functions 


GetCompressi  onTime  (1-401) 

Determines  the  estimated  amount  of  time  required  to  compress  a  given  image. 
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GetMaxCompressi  onSi  ze  (1-420) 

Determines  the  maximum  size  an  image  will  be  after  compression. 

GetCompressedlmageSi  ze  (1-396) 

Determines  the  size,  in  bytes,  of  a  compressed  image. 

GetSimilarity  (1-508) 

Compares  a  compressed  image  to  a  picture  stored  in  a  pixel  map  and  returns  a 
value  indicating  the  relative  similarity  of  the  two  images. 


Getting  Information  About  Compressor  Components 

The  Image  Compression  Manager  provides  functions  that  let  you  get  information 
about  itself  and  about  the  available  codecs. 

You  can  use  CodecManagerVersi  on  (1-103)  to  retrieve  the  version  number  associated 
with  the  Image  Compression  Manager  that  is  installed  on  a  particular  computer. 
You  can  use  Fi ndCodec  (1-358),  GetCodecInfo  (1-385),  and  GetCodecNameLi  st  (1-386) 
to  locate  and  retrieve  information  about  the  compressor  components  that  are 
available. 


Functions 

CodecManagerVersi  on  (1-103) 

Determines  the  version  of  the  installed  Image  Compression  Manager. 

Fi  ndCodec  (1-358) 

Determines  which  of  the  installed  compressors  or  decompressors  has  been 
chosen  to  field  requests  made  by  using  one  of  the  special  compressor 
identifiers. 

GetCodecInfo  (1-385) 

Returns  information  about  a  single  compressor  component. 

GetCodecNameLi  st  (1-386) 

Retrieves  a  list  of  installed  compressor  components  or  types. 

Di sposeCodecNameLi st  (1-257) 

Disposes  of  the  compressor  name  list  structure  you  obtained  by  calling 
GetCodecNameLi  st  (1-386). 
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Working  With  Pixel  Maps 


The  Image  Compression  Manager  provides  two  levels  of  functionality  for 
compressing  and  decompressing  single-frame  images  stored  as  pixel  maps. 

If  you  do  not  need  to  assert  a  lot  of  control  over  the  compression  operation,  you  can 
use  Compress  Image  (1-113)  and  Decompress  Image  (1-235)  to  work  with  compressed 
images.  If  you  need  more  control  over  the  compression  parameters,  you  can  use 
FCompress Image  (1-344)  and  FDecompressImage  (1-355). 

You  can  convert  a  compressed  image  from  one  compression  format  to  another  by 
calling  Convertlmage  (1-131).  You  can  alter  the  spatial  characteristics  of  a 
compressed  image  by  calling  T rimlmage  (III— 1956).  You  can  work  with  an  image's 
color  table  using  SetlmageDescri  pti  onCTabl  e  (III— 1593)  and 
GetlmageDescri pti onCTabl e. 
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Functions 

Compress  Image  (1-113) 

Compresses  a  single-frame  image  that  is  currently  stored  as  a  pixel  map 
structure. 

Decompress  Image  (1-235) 

Decompresses  a  single-frame  image  into  a  pixel  map  structure. 

FCompress  Image  (1-344) 

Compresses  a  single-frame  image  that  is  currently  stored  as  a  pixel  map 
structure,  with  added  control  over  the  compression  process. 

FDecompressImage  (1-355) 

Decompresses  a  single-frame  image  into  a  pixel  map  structure,  with  added 
control  over  the  decompression  process. 

Convertlmage  (1-131) 

Converts  the  format  of  a  compressed  image. 

Trimlmage  (III — 1 956) 

Adjusts  a  compressed  image  to  the  boundaries  defined  by  a  specified  rectangle. 

SetlmageDescri  pti  onCTabl  e  (III — 1 593) 

Updates  the  custom  Col  orTabl  e  (IV-2210)  structure  for  an  image. 

GetlmageDescri  pti  onCTabl  e  (1-417) 

Sets  the  custom  color  table  for  an  image. 
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Working  With  Image  Descriptions 

The  Image  Compression  Manager  provides  several  functions  that  let  you  modify 
ImageDescri  pti  on  (IV-2285)  structures. 

These  functions  are  listed  below. 


Functions 

AddlmageDescripti  on  Ext  en  si  on  (1-25) 

Adds  an  extension  to  an  ImageDescri  pti  on  (IV-2285)  structure. 

Get  Next  ImageDescri  pti  on  Ext  en  si  onType  (1-501) 

Retrieves  an  image  description  structure  extension  type. 

CountlmageDescripti  on  Ext  en  si  onType  (1-143) 

Counts  the  number  of  extensions  of  a  given  type  in  an  ImageDescri  ptionHandle. 

GetlmageDescripti  on  Ext  en  si  on  (1-418) 

Returns  a  new  handle  with  the  data  from  a  specified  image  description 
extension. 

Remove  ImageDescri  pti  on  Ext  en  si  on  (III — 1457) 

Removes  a  specified  extension  from  an  ImageDescri  pti  on  (IV-2285)  structure. 


Working  With  Pictures  and  PICT  Files 

The  Image  Compression  Manager  provides  two  levels  of  functionality  for 
compressing  and  decompressing  single-frame  images  stored  as  pictures  and  PICT 
files. 

If  you  do  not  need  to  control  the  compression  parameters,  use  CompressPicture 
(1-116)  or  Compress  Pi  ctureFi  1  e  (1-118).  If  you  need  more  control  over  the  operation, 
use  FCompressPi  cture  (1-348)  or  FCompressPi  ctureFi  I  e  (1-352). 

The  Image  Compression  Manager  automatically  expands  compressed  pictures 
when  you  display  them.  Use  DrawPi  ctureFi  1  e  (1-310)  to  display  the  contents  of  a 
picture  file.  If  you  want  to  alter  the  spatial  characteristics  of  the  image,  use 
DrawTri  mmedPi  cture  (1-311)  or  DrawTrimmedPi  ctureFi  1  e.  You  can  work  with  an 
image's  control  information  by  calling  GetPi  ctureFi  leHeader  (1-504). 
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Functions 


CompressPi  cture  (1-116) 

Compresses  a  single-frame  image  stored  as  a  picture  structure  and  places  the 
result  in  another  picture. 

CompressPi  ctureFi  1  e  (1-118) 

Compresses  a  single-frame  image  stored  as  a  picture  file  and  places  the  result 
in  another  picture  file. 

FCompressPi  cture  (1-348) 

Compresses  a  single-frame  image  stored  as  a  picture  structure  and  places  the 
result  in  another  picture,  with  added  control  over  the  compression  process. 

FCompressPi  ctureFi  1  e  (1-352) 

Compresses  a  single-frame  image  stored  as  a  picture  file  and  places  the  result 
in  another  picture  file,  with  added  control  over  the  compression  process. 

DrawPi  ctureFi  1  e  (1-310) 

Draws  an  image  from  a  specified  picture  file  in  the  current  graphics  port. 
DrawT ri mmedPi  cture  (1-311) 

Draws  an  image  that  is  stored  as  a  picture  into  the  current  graphics  port  and 
trims  that  image  to  fit  a  specified  region. 

DrawT  ri  mmedPi  ctureFi  1  e  (1-313) 

Draws  an  image  that  is  stored  as  a  picture  file  into  the  current  graphics  port 
and  trims  that  image  to  fit  a  specified  region. 

GetPi  ctureFi  1  eHeader  (1-504) 

Extracts  the  picture  frame  and  file  header  from  a  specified  picture  file. 
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Making  Thumbnail  Pictures 

The  Image  Compression  manager  provides  functions  that  allow  your  application  to 
create  thumbnail  pictures  from  existing  images  that  are  stored  as  pixel  maps, 
pictures,  or  picture  files.  Thumbnail  pictures  are  useful  for  creating  small, 
representative  images  of  a  source  image.  You  can  use  thumbnails  when  you  create 
previews  for  files  that  contain  image  data. 

Use  MakeThumbnai  1  FromPi  cture  (11-790),  MakeThumbnai  1  FromPi  ctureFi  1  e,  or 
MakeThumbnai  1  FromPixMap  (11-792),  as  appropriate. 
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Functions 


MakeThumbnai  1  FromPi  cture  (11-790) 

Creates  a  thumbnail  picture  from  a  specified  Pi  cture  (IV-2331)  structure. 

MakeThumbnai  lFromPictureFile  (II — 7  91) 

Creates  a  thumbnail  picture  from  a  specified  picture  file. 

MakeThumbnai  1  FromPixMap  (11-792) 

Creates  a  thumbnail  picture  from  a  specified  Pi  xMap  (IV-2332)  structure. 


Working  With  Sequences 

The  Image  Compression  Manager  provides  a  rich  set  of  functions  that  allow  your 
application  to  compress  and  decompress  sequences  of  images.  Each  image  in  the 
sequence  is  referred  to  as  a  frame.  Note  that  the  sequence  carries  no  time 
information;  the  Movie  Toolbox  manages  all  temporal  aspects  of  displaying  the 
sequence.  Consequently,  your  application  can  focus  on  the  order  of  images  in  the 
sequence. 

To  process  a  sequence  of  frames,  your  program  begins  by  calling  either 
Comp  r  ess  Sequence  Beg  i  n  (1-119),  Decomp  ressSequenceBegi  n,  or 
DecompressSequenceBegi  nS  (1-239).  You  then  process  each  frame  in  the  sequence. 
Use  CompressSequenceFrame  (1-124)  to  compress  a  frame;  use 

DecompressSequenceFrame  (1-242)  to  decompress  a  frame.  When  you  are  done,  close 
the  sequence  by  calling  CDSequenceEnd  (1-77).  You  can  check  on  the  status  of  the 
current  operation  by  calling  CDSequenceBusy  (1-75). 


Functions 

CompressSequenceBegi n  (1-119) 

Signals  the  beginning  of  the  process  of  compressing  a  sequence  of  frames. 

DecompressSequenceBegi  n  (1-238) 

Obsolete.  See  DecompressSequenceBegi  nS  (1-239). 

DecompressSequenceBegi  nS  (1-239) 

Sends  a  sample  image  to  a  decompressor. 

CompressSequenceFrame  (1-124) 

Compresses  one  of  a  sequence  of  frames. 

DecompressSequenceFrame  (1-242) 

Obsolete.  See  DecompressSequenceFrameS  (1-243). 
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DecompressSequenceFrameS  (1-243) 

Queues  a  frame  for  decompression  and  specifies  the  size  of  the  compressed 
data;  new  applications  should  use  DecompressSequenceFrameWhen. 

Decomp  res  sSequenceFrameWhen  (1-245) 

Queues  a  frame  for  decompression  and  specifies  the  time  at  which 
decompression  will  begin. 

CDSequenceEnd  (1-77) 

Indicates  the  end  of  processing  for  an  image  sequence. 

CDSequenceBusy  (1-75) 

Checks  the  status  of  an  asynchronous  compression  or  decompression 
operation. 

CDSequenceFl  ush  (1-80) 

Stops  a  decompression  sequence,  aborting  processing  of  any  queued  frames. 

CDSequenceEqui  val  entlmageDescription  (1-78) 

Reports  whether  two  image  descriptions  are  the  same. 

CDSequenceNewMemory  (I — 84) 

Requests  codec-allocated  memory. 

CDSequenceDi  sposeMemory  (1-77) 

Disposes  of  memory  allocated  by  the  codec. 

CDSeq uence Invalidate  (1-82) 

Notifies  the  Image  Compression  Manager  that  the  destination  port  for  the 
given  image  decompression  sequence  has  been  invalidated. 

CDSequenceNewDataSource  (1-82) 

Creates  a  new  data  source. 

CDSequenceDi  sposeDataSource  (1-76) 

Disposes  of  a  data  source. 

CDSequenceSetSourceData  (1-86) 

Sets  data  in  a  new  frame  to  a  specific  data  source. 

CDSequenceChangedSourceData  (1-76) 

Notifies  the  compressor  that  the  image  source  data  has  changed. 

SetSequenceProgressProc  (III — 1 639) 

Installs  a  progress  procedure  for  a  sequence. 
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Changing  Sequence-Compression  Parameters 

The  Image  Compression  Manager  provides  functions  that  allow  your  application  to 
manipulate  the  parameters  that  control  sequence  compression  and  to  get 
information  about  memory  that  the  compressor  has  allocated.  You  can  use  these 
functions  during  the  sequence-compression  process.  Some  of  these  functions  deal 
with  parameter  values  that  cannot  be  set  when  starting  a  sequence. 

You  can  determine  the  location  of  the  previous  image  buffer  used  by  the  Image 
Compression  Manager  by  calling  GetCSequencePrevBuffer  (1-406). 

You  can  set  a  number  of  compression  parameters.  Use  SetCSequenceFl  ushProc 
(III— 1575)  to  assign  a  data-unloading  function  to  the  operation.  You  can  set  the  rate 
at  which  the  Image  Compression  Manager  inserts  key  frames  into  the  compressed 
sequence  by  calling  SetCSequenceKey  FrameRate  (III— 1577).  You  can  set  the  frame 
against  which  the  compressor  compares  a  frame  when  performing  temporal 
compression  by  calling  SetCSequencePrev  (III— 1579).  Finally,  you  can  control  the 
quality  of  the  compressed  image  by  calling  SetCSequenceQual  i  ty  (III— 1580). 


Functions 

GetCSequencePrevBuffer  (1-406) 

Determines  the  location  of  the  previous  image  buffer  allocated  by  the 
compressor. 

GetCSequenceMaxCompressi onSi ze  (1-405) 

Determines  the  maximum  size  an  image  will  be  after  compression  for  a  given 
compression  sequence. 

SetCSequenceFl  ushProc  (III — 1 575) 

Assigns  a  data-unloading  function  to  a  sequence. 

SetCSequenceKey  FrameRate  (III — 1 577) 

Adjusts  the  key  frame  rate  for  the  current  sequence. 

SetCSequencePrev  (III — 1 579) 

Allows  the  application  to  set  the  pixel  map  and  boundary  rectangle  used  by  the 
previous  frame  in  temporal  compression. 

SetCSequenceQual  i  ty  (III — 1 580) 

Adjusts  the  spatial  or  temporal  quality  for  the  current  sequence. 

SetCSequencePreferredPacketSize  (III — 1 578) 

Sets  the  preferred  packet  size  for  a  sequence. 
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Callback 


ICMF1  ushProc  (ID-2091) 

Writes  compressed  data  to  a  storage  device  during  a  compression  operation. 


Constraining  Compressed  Data 

The  Image  Compression  Manager  provides  two  functions  and  a  data  structure  that 
allow  your  application  to  communicate  information  to  compressors  that  can 
constrain  compressed  data  to  a  specific  data  rate. 
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A  compressor  indicates  that  it  can  constrain  the  data  rate  by  setting  the 
codecInfoDoesRateConstrai  n  flag  in  its  Codeclnfo  (IV-2202)  structure. 
SetCSequenceDataRateParams  (III-1574)  allows  you  to  specify  the  parameters  in  the 
DataRateParams  (IV-2231)  structure  and  GetCSequenceDataRateParams  (1-403)  allows 
you  to  retrieve  these  parameters. 


Functions 

SetCSequenceDataRateParams  (III-1574) 

Communicates  information  to  compressors  that  can  constrain  compressed  data 
in  a  particular  sequence  to  a  specific  data  rate. 

GetCSequenceDataRateParams  (1-403) 

Obtains  the  data  rate  parameters  previously  set  with 
SetCSequenceDataRateParams  (III-1574). 

Data  Structure 

DataRateParams  (IV-2231) 

Communicates  information  to  compressors  that  can  constrain  compressed  data 
to  a  specific  data  rate. 

See  Also 

See  "Image  Compression  Data  Structures"  (V-2786). 


Changing  Sequence-Decompression  Parameters 

The  Image  Compression  Manager  provides  functions  that  enable  your  application 
to  manipulate  the  parameters  that  control  sequence  decompression  and  to  get 
information  about  memory  that  the  decompressor  has  allocated.  Some  of  these 
functions  deal  with  parameter  values  that  cannot  be  set  when  starting  a  sequence. 
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Use  GetDSequencelmageBuf  f  er  (1-409)  to  determine  the  location  of  the  image  buffer. 
Use  GetDSequenceScreenBuf  fer  (1-410)  to  determine  the  location  of  the  screen  buffer. 


Use  SetDSequenceAccuracy  (III— 1583)  to  control  the  accuracy  of  the  decompression. 
Use  SetDSequenceDataProc  (III— 1584)  to  assign  a  data-loading  function  to  the 
operation.  Use  SetDSequenceMask  (III— 1586)  to  set  the  clipping  region  for  the 
resulting  image.  You  can  establish  a  blend  matte  for  the  operation  by  calling 
SetDSequenceMatte  (III— 1588).  You  can  alter  the  spatial  characteristics  of  the 
resulting  image  by  calling  SetDSequenceMatri  x  (III— 1587).  Your  application  can 
establish  the  size  and  location  of  the  operation's  source  rectangle  by  calling 
SetDSequenceSrcRect  (III— 1589).  Finally,  you  can  set  the  transfer  mode  used  by  the 
decompressor  when  it  draws  to  the  screen  by  calling  SetDSequenceT ransferMode 
(III— 1591). 


Functions 

GetDSequencelmageBuffer  (1-409) 

Determines  the  location  of  the  offscreen  image  buffer  allocated  by  a 
decompressor. 

GetDSequenceScreenBuffer  (1-410) 

Determines  the  location  of  the  offscreen  screen  buffer  allocated  by  a 
decompressor. 

SetDSequenceAccuracy  (III — 1 583) 

Adjusts  the  decompression  accuracy  for  the  current  sequence. 

SetDSequenceDataProc  (III — 1 584) 

Assigns  a  data-loading  function  to  a  sequence. 

SetDSequenceMask  (III — 1 586) 

Assigns  a  clipping  region  to  a  sequence. 

SetDSequenceMatte  (III — 1 588) 

Assigns  a  blend  matte  to  a  sequence. 

SetDSequenceMatri x  (III — 1 587) 

Assigns  a  mapping  matrix  to  a  sequence. 

SetDSequenceSrcRect  (III — 1 589) 

Defines  the  portion  of  an  image  to  decompress. 

Set  DSequenceTrans  fer  Mode  (III — 1591) 

Sets  the  mode  used  when  drawing  a  decompressed  image. 
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SetDSequenceTimeCode  (III — 1 590) 

Sets  the  timecode  value  for  a  frame  that  is  about  to  be  decompressed. 
PtlnDSequenceData  (11-1147) 

Tests  to  see  if  a  compressed  image  contains  data  at  a  a  given  point. 

Callback 

ICMDataProc  (III— 2090) 

Supplies  compressed  data  during  a  decompression  operation. 

Working  With  the  StdPix  Function 

The  StdPix  (III— 1912)  function  extends  the  graf  P  rocs  field  of  the  CGraf  Port  (IV-2168) 
structure  to  support  compressed  data,  mattes,  and  matrices. 

To  work  with  the  control  information  associated  with  a  compressed  image,  you  can 
use  SetCompressedPixMapInfo  (ill-1573)  and  GetCompressedPixMapInfo. 
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Functions 

StdPix  (III— 1912) 

Extends  the  graf  Procs  field  of  the  CGraf  Port  (IV-2168)  structure  to  support 
compressed  data,  mattes,  matrices,  and  pixel  maps,  letting  you  intercept  image 
data  in  compressed  form  before  it  is  decompressed  and  displayed. 

SetCompressedPi xMapInf o  (III — 1 573) 

Stores  information  about  a  compressed  image  for  StdPix  (III— 1912). 

GetCompressedPixMapInfo  (1-397) 

Retrieves  information  about  a  compressed  image. 

Data  Structure 

CGraf  Port  (IV-2168) 

Defines  a  complete  drawing  environment  for  color  graphics  operations. 


Aligning  Windows 

The  Image  Compression  Manager  provides  functions  that  allow  your  application  to 
position  and  drag  windows  to  optimal  screen  positions  based  on  the  depth  of  the 
screen. 
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A1  i  gnWi  ndow  (1-47)  enables  you  to  transport  a  specified  window  to  the  nearest 
optimal  alignment  position.  DragAl  1  gnedWi  ndow  (1-306)  drags  the  specified  window 
along  an  optimal  alignment  grid.  DragAl  i  gnedGray  Rgn  (1-304)  drags  a  specified  gray 
region  along  an  optimal  alignment  grid.  A1  i  gnScreenRect  (1-46)  aligns  a  specified 
rectangle  to  the  strictest  screen  that  the  rectangle  intersects.  The  alignment  behavior 
provided  by  these  functions  is  adequate  in  the  vast  majority  of  situations.  However, 
if  you  need  customized  alignment  behavior  (for  example,  justification  specifications 
geared  to  particular  video  hardware),  you  can  use  the  ICMA1  i  gnmentProc  (III— 2086) 
callback. 


Functions 

A1  i  gnWi  ndow  (1-47) 

Moves  a  specified  window  to  the  nearest  optimal  alignment  position. 

DragAl  i  gnedWi  ndow  (1-306) 

Drags  the  specified  window  along  an  optimal  alignment  grid. 

DragAl  1  gnedGrayRgn  (1-304) 

Drags  a  specified  gray  region  along  an  optimal  alignment  grid. 

A1  i  gnScreenRect  (1-46) 

Aligns  a  specified  rectangle  to  the  strictest  screen  that  the  rectangle  intersects. 

Callback 

ICMA1  i  gnmentProc  (III — 2086) 

Provides  an  alignment  behavior  for  windows  based  on  the  screen's  bit  depth. 


Working  With  Graphics  Devices  and  Graphics  Worlds 

Two  Image  Compression  Manager  functions  enable  you  to  select  graphics  devices 
and  create  graphics  worlds. 

You  can  use  GetBestDevI  ceRect  (1-382)  to  select  the  best  available  graphics  device. 
NewImageGWorl  d  (11-1066)  allows  you  to  create  a  graphics  world  based  on  the  width, 
height,  depth,  and  color  table  of  a  specified  ImageDescri  pti  on  (IV-2285)  structure. 


Functions 


GetBestDevi  ceRect  (1-382) 

Selects  the  deepest  of  all  available  graphics  devices,  while  treating  16-bit  and 
32-bit  screens  as  having  equal  depth. 
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NewImageGWorl d  (11-1066) 

Creates  an  offscreen  graphics  world. 


Image  Compression  Progress  and  Completion  Callbacks 

The  Image  Compression  Manager  defines  two  callbacks  that  you  may  provide  to 
compressor  components. 

The  ICMProgressProc  (III— 2093)  callback  allows  compressors  and  decompressors  to 
report  that  asynchronous  operations  have  completed.  The  ICMCompl  eti  onProc 
(III— 2087)  callback  provides  a  mechanism  for  compressors  and  decompressors  to 
report  their  progress  toward  completing  an  operation. 
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Callbacks 

ICMProgressProc  (III — 2093) 

Reports  on  the  progress  of  a  compressor  or  decompressor. 

ICMCompl  eti  onProc  (III — 2087) 

Called  by  a  compressor  component  upon  completion  of  an  asynchronous 
operation. 


Image  Compression  Manager  Utility  Functions 

The  Image  Compression  Manager  supports  two  general  utility  functions. 
These  functions  are  listed  below. 


Functions 

ICMShi  el  dSequenceCursor  (11-679) 

Hides  the  cursor  during  decompression  operations. 

ICMDecompressCompl  ete  (11-671) 

Signals  the  completion  of  a  decompression  operation. 
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Using  Image-Compression  Dialogs 


Standard  image-compression  dialog  components  provide  a  consistent  user 
interface  for  selecting  parameters  that  govern  the  compression  of  an  image  or  image 
sequence  and  the  management  of  the  compression  operation.  Applications  that  use 
these  components  are  freed  from  many  of  the  details  of  obtaining  and  validating 
image-compression  parameters  and  interacting  with  the  Image  Compression 
Manager  to  compress  an  image  or  sequence. 


Getting  Default  Settings  for  an  Image  or  a  Sequence 

The  Image  Compression  Manager  provides  functions  that  allow  you  to  derive 
sensible  default  compression  settings  for  an  image  or  a  sequence.  The  standard 
dialog  component  examines  an  image  you  provide  and  selects  appropriate  default 
settings  based  on  the  image's  characteristics.  The  component  stores  those  settings 
for  you  and  uses  them  with  other  functions.  If  you  choose  to  display  a  dialog  box  to 
the  user,  the  component  uses  these  settings  as  the  default  dialog  box  settings. 

SCDefaul  tPi  ctHandl  eSetti  ngs  (III— 1540)  works  with  pictures, 

SCDefaul  tPi  ctFi  1  eSetti  ngs  (III— 1540)  works  with  picture  files,  and 
SCDefaul  tPi  xMapSetti  ngs  (III— 1541)  works  with  pixel  maps. 


Functions 


SCDefaul  tPi  ctHandl  eSetti  ngs  (III — 1 540) 

Derives  default  compression  settings  for  a  Pi  cture  (IV-2331)  structure  that  is 
stored  by  a  handle. 

SCDefaul  tPi  ctFi  1  eSetti  ngs  (III — 1 540) 

Derives  default  compression  settings  for  a  Pi  cture  (IV-2331)  structure  that  is 
stored  in  a  file. 

SCDefaul  t Pi  xMapSetti  ngs  (III — 1 541) 

Derives  default  compression  settings  for  an  image  that  is  stored  in  a  pixel  map. 
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Displaying  the  Standard  Image-Compression  Dialog  Box 


Standard  image-compression  dialog  components  provide  two  functions  that  allow 
you  to  display  the  standard  dialog  box  to  the  user  and  retrieve  the  compression 
parameters  specified  by  the  user. 

Use  SCRequestlmageSetti  ngs  (III— 1555)  to  retrieve  the  user's  preferences  for 
compressing  a  single  image;  use  SCRequestSequenceSetti  ngs  (III— 1556)  when  you 
are  working  with  an  image  sequence.  You  may  customize  the  dialog  boxes  by 
specifying  a  modal-dialog  hook  function  or  a  custom  button.  You  may  use  the 
custom  button  to  invoke  an  ancillary  dialog  box  that  is  specific  to  your  application. 


Functions 
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SCRequestlmageSetti  ngs  (III — 1 555) 

Displays  the  standard  image  dialog  box  to  the  user  and  shows  default  settings 
you  have  established. 

SCRequestSequenceSetti  ngs  (III — 1 556) 

Displays  the  standard  sequence  dialog  box  to  the  user  and  shows  default 
settings  you  have  established. 


Compressing  Still  Images 

The  standard  dialog  component  provides  three  functions  you  may  use  to  compress 
a  still  image.  All  of  these  functions  use  the  current  compression  settings. 

SCCompress  Image  (III— 1530)  works  with  pixel  maps;  SCCompressPi  cture  (III— 1531) 
compresses  a  picture  that  is  stored  in  a  handle;  and  SCCompressPi  ctureFi  1  e 
(III— 1532)  works  with  pictures  stored  in  files. 


Functions 

SCCompress  Image  (III — 1 530) 

Compresses  an  image  that  is  stored  in  a  Pi  xMap  (IV-2332)  structure. 
SCCompressPi  cture  (III — 1 531) 

Compresses  a  Pi  cture  (IV-2331)  structure  that  is  stored  by  a  handle. 

SCCompressPi  ctureFi  1  e  (III — 1 532) 

Compresses  a  Pi  cture  (IV-2331)  structure  that  is  stored  in  a  file. 
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Compressing  Image  Sequences 


The  standard  dialog  component  provides  three  functions  you  may  use  to  compress 
an  image  sequence.  The  standard  dialog  component  manages  all  of  the  compression 
details  for  you.  Your  application  may  have  only  one  sequence-compression 
operation  active  on  any  given  connection;  naturally,  you  may  have  more  than  one 
connection  active  at  a  time.  All  of  these  functions  use  the  current  compression 
settings. 

SCCompressSequenceBegin  (III— 1533)  allows  you  to  start  a  sequence-compression 
operation.  Use  SCCompressSequenceFrame  (III— 1534)  for  each  image  in  the  sequence. 
End  the  sequence  by  calling  SCCompressSequenceEnd  (III— 1534). 


Functions 

SCComp  r  ess  Sequence  Beg  i  n  (III — 1 533) 

Initiates  a  sequence-compression  operation. 

SCCompressSequenceFrame  (III — 1 534) 

Continues  a  sequence-compression  operation. 

SCCompressSequenceEnd  (III — 1 534) 

Ends  a  sequence-compression  operation. 


Working  With  Image  or  Sequence  Settings 

The  standard  dialog  component  provides  two  functions  that  allow  you  to  work 
with  the  current  compression  settings  for  an  image  or  a  sequence  of  images. 

Use  SCGetlnfo  (III— 1545)  to  retrieve  settings  information.  SCSetlnfo  (III— 1558) 
enables  you  to  modify  the  settings.  These  functions  can  work  with  a  number  of 
different  types  of  settings  information.  When  you  call  either  function,  you  specify 
the  type  of  data  you  want  to  work  with.  Each  of  these  request  types  requires 
different  parameter  data. 


Functions 


SCGetlnfo  (III— 1545) 

Retrieves  configuration  information  from  the  standard  dialog  component. 
SCSetlnfo  (III— 1558) 

Modifies  the  standard  dialog  component's  configuration  information. 
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Specifying  a  Test  Image 


The  standard  image-compression  dialog  component  provided  by  Apple  supports  a 
test  image.  The  component  uses  this  image  to  display  the  effect  of  the  user's 
image-compression  settings.  In  this  manner,  the  user  can  experiment  with  different 
settings  and  see  the  results  of  those  settings  immediately.  The  component  provides 
three  functions  that  allow  you  to  specify  the  test  image. 

Use  SCSetTestlmagePi  ctHandl  e  (III— 1566)  if  your  test  image  is  stored  in  a  handle. 
Use  SCSetTestlmagePi  ctFi  1  e  (III— 1564)  if  your  test  image  is  in  a  picture  file. 
SCSetTestlmagePi xMap  (III— 1568)  sets  the  test  image  from  a  pixel  map. 


Functions 


SUM 


SCSetTestlmagePi  ctHandl  e  (III — 1 566) 

Sets  the  dialog  box's  test  image  from  a  P  i  c  t  u  r  e  (IV-233 1 )  structure  that  is  stored 
in  a  handle. 

SCSetTestlmagePi  ctFi  1  e  (III — 1 564) 

Sets  the  dialog  box's  test  image  from  a  P  i  c  t  u  r  e  (IV-233 1 )  structure  that  is  stored 

in  a  picture  file. 

SCSetTestlmagePixMap  (III — 1 568) 

Sets  the  dialog  box's  test  image  from  a  P  i  c  t  u  r  e  (IV-233 1 )  structure  that  is  stored 
in  a  Pi  xMap  (IV-2332)  structure. 


Positioning  Dialog  Boxes  and  Rectangles 

Standard  image-compression  dialog  components  provide  functions  that  allow  you 
to  position  rectangles  and  dialog  boxes.  These  functions  are  most  useful  in  helping 
you  to  manage  dialog  boxes  that  are  related  to  the  standard  image-compression 
dialog. 

SCPosi  ti  onRect  (III— 1554)  positions  a  rectangle;  SCPosi  ti  onDi  al  og  (III— 1553) 
positions  a  dialog  box.  The  SCGetBestDevi  ceRect  (III— 1542)  function  returns 
information  about  the  best  available  display  device. 


Functions 


SCPosi  ti  onRect  (III — 1 554) 

Positions  a  rectangle  on  the  screen. 
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SCPosi  ti  onDi  al  og  (III — 1 553) 

Helps  position  a  dialog  box  on  the  screen. 

SCGetBestDevi  ceRect  (III — 1 542) 

Determines  the  boundary  rectangle  that  surrounds  the  display  device  that 
supports  the  largest  color  or  grayscale  palette. 

Creating  a  Compression  Graphics  World 

The  standard  dialog  component  provides  a  single  utility  function  that  you  can  use 
to  create  a  graphics  world  that  is  appropriate  for  the  current  compression  settings. 

Use  SCNewGWorl  d  (III— 1552)  to  create  such  a  graphics  environment. 


Functions 

SCNewGWorl  d  (III— 1552) 

Creates  a  graphics  world  based  on  the  current  compression  settings. 


Using  the  Base  Image  Decompressor 


The  base  image  decompressor  is  a  component  that  performs  tasks  for  other  image 
decompressor  components,  including  the  scheduling  of  asynchronous 
decompression  operations. 


Base  Image  Decompressor  Data  Structures 


The  base  image  decompressor  component  communicates  with  image  decompressor 
components  through  two  data  structures. 

Your  image  decompressor  component  uses  the 

ImageSubCodecDecompressCapabi  1  i  ti  es  (IV-2288)  structure  to  report  its  capabilities 
to  the  base  image  decompressor.  The  ImageSubCodecDecompressRecord  (IV-2289) 
structure  contains  information  needed  for  decompressing  a  frame. 
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Data  Structures 


ImageSubCodecDecompressCapabi  1  i ti es  (IV-2288) 

Returned  by  an  image  decompressor  component  in  response  to 
ImageCodecInitial  ize  (11-724). 

I mageSubCodecDecomp res s Record  (TV-2289) 

Contains  information  needed  for  decompressing  a  frame. 


Base  Image  Decompressor  Functions 


SUM 


The  base  image  decompressor  makes  several  calls  to  your  image  decompressor 
component  during  the  decompression  process. 

It  calls  your  image  decompressor  component's  ImageCodecIni  ti  al  i  ze  (11-724) 
function  before  making  any  other  all  calls  to  your  component,  and  it  calls  your 
image  decompressor  component's  ImageCodecBegi  nBand  (11-690)  function  before 
drawing  a  band  or  frame.  The  base  image  decompressor  calls  your 
ImageCodecPreflight  (11-732)  function  before  decompressing  an  image,  then  calls 
ImageCodecDrawBand  (11-697)  to  decompress  a  band  or  frame.  The  ImageCodecEndBand 
(11-704)  function  notifies  your  image  decompressor  component  that  decompression 
of  a  band  has  finished  or  that  it  was  terminated  by  the  Image  Compression 
Manager. 

If  your  component  supports  asynchronous  scheduled  decompression,  the  base 
image  decompressor  calls  its  ImageCodecQueueStarti  ng  (11-733)  function  before 
decompressing  the  frames  in  the  queue,  and  ImageCodecQueueStoppi  ng  (11-734)  to 
notify  your  component  that  the  frames  in  the  queue  have  been  decompressed. 


Functions 


ImageCodecIni  ti  al  i  ze  (II — 7 24) 

Called  before  making  any  other  all  calls  to  your  component. 

ImageCodecPref  1  i  ght  (11-732) 

Called  before  decompressing  an  image,  in  response  to  an 
ImageCodecPreDecompress  (11-731)  call  from  the  Image  Compression  Manager. 

ImageCodecBegi  nBand  (11-690) 

Called  before  drawing  a  band  or  frame;  it  allows  your  image  decompressor 
component  to  save  information  about  a  band  before  decompressing  it. 
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ImageCodecDrawBand  (11-697) 

Decompresses  a  band  or  frame. 

ImageCodecEndBand  (11-704) 

Notifies  your  image  decompressor  component  that  decompression  of  a  band 
has  finished  or  that  it  was  terminated  by  the  Image  Compression  Manager. 

ImageCodecQueueStarti  ng  (11-733) 

Called  by  the  base  image  decompressor  before  decompressing  the  frames  in  the 
queue  if  your  image  decompressor  component  supports  asynchronous 
scheduled  decompression. 

ImageCodecQueueStoppi ng  (11-734) 

Notifies  your  component  that  the  frames  in  the  queue  have  been 
decompressed,  if  your  image  decompressor  component  supports 
asynchronous  scheduled  decompression. 

ImageCodec  Extract  An  dCombi  neFi  el  ds  (11-705) 

Performs  field  operations  on  video  data. 

ImageCodecFl  ush  (11-708) 

Empties  an  image  decompressor  component's  input  queue  of  pending 
scheduled  frames. 

ImageCodecSetTi meCode  (11-738) 

Sets  the  timecode  for  the  next  frame  that  is  to  be  decompressed. 

ImageCodecIsI  mage  Description  Equivalent  (11-725) 

Compares  image  descriptions. 

ImageCodecNewMemory  (11-729) 

Requests  codec-allocated  memory. 

ImageCodec  New  I  mageBufferMemory  (11-727) 

Asks  a  codec  to  allocate  memory  for  an  offscreen  buffer  of  non-RGB  pixels. 

ImageCodecDi sposeMemory  (11-696) 

Disposes  codec-allocated  memory. 

ImageCodecRequestSetti ngs  (11-735) 

Displays  a  dialog  box  containing  codec-specific  compression  settings. 

ImageCodecGetSetti ngs  (11-719) 

Returns  the  codec  settings  chosen  by  the  user. 
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ImageCodecSetSetti ngs  (11-737) 

Sets  the  settings  of  an  optional  image  codec  dialog  box. 

ImageCodecHi tTestData  (11-722) 

Notifies  your  codec  when  the  application  calls  PtlnDSequenceData  (11-1147). 

ImageCodecGetMaxCompressi  onSi  zeWi  thSources  (11-716) 

Notifies  your  codec  when  an  application  calls  GetCSequenceMaxCompressi  on  Si  ze 
(1-405). 

ImageCodecSourceChanged  (11-739) 

Notifies  your  codec  that  one  of  the  data  sources  has  changed  when  an 
application  calls  CDSequenceSetSourceData  (1-86)  or 
CDSequenceChangedSourceData  (1-76). 


SUM 


Using  Data  Codec  Components 


Data  codec  components  enable  you  to  compress  and  decompress  data  using  a 
specified  compressor  component. 


Data  Codec  Functions 


Data  compressor  components  have  a  component  type  of 
DataCompressorComponentType  and  data  decompressor  components  have  a 
component  type  of  DataDecompressorComponentType.  Each  component  has  a  unique 
component  subtype. 

With  DataCodecCompress  (1-167)  and  Data  Codec  Decompress  (1-170),  you  can  compress 
and  decompress  data  using  a  specified  compressor  component.  You  can  also 
compress  and  decompress  sprites  and  3D  media  samples.  Your  software  calls  the 
DataCodecBeginlnterruptSafe  (1-166)  function  before  performing  a  compression  or 
decompression  operation  during  interrupt  time.  When  your  software  has  finished 
a  compression  or  decompression  operation  that  must  be  performed  during 
interrupt  time,  it  can  release  any  memory  of  other  resources  used  to  make  the 
operation  safe  by  calling  the  DataCodecEndlnterruptSafe  (1-172)  function. 
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Functions 


DataCodecCompress  (1-167) 

Compresses  data  using  the  specified  compressor  component. 
DataCodecDecompress  (1-170) 

Decompresses  data  using  the  specified  compressor  component. 
DataCodecBeginlnterruptSafe  (1-166) 

Called  before  performing  a  compression  or  decompression  operation  during 
interrupt  time. 

DataCodecEndlnterruptSafe  (1-172) 

Releases  resources  used  by  DataCodecBeginlnterruptSafe  (1-166). 


Sequence  Grabbing 


Sequence  grabber  components  allow  applications  to  obtain  digitized  data  from 
sources  that  are  external  to  a  Macintosh  computer.  For  example,  you  can  use  a 
sequence  grabber  component  to  record  video  data  from  a  video  digitizer.  Your 
application  can  then  request  that  the  sequence  grabber  store  the  captured  video 
data  in  a  QuickTime  movie. 


Sequence  Grabber  Data  Structures 

Sequence  grabber  components  use  two  data  structures  to  communicate  with 
applications  and  other  components. 

The  SGCompress  Info  (IV-2432)  structure  defines  the  characteristics  of  a  buffer  that 
contains  a  captured  image  that  has  been  compressed.  Callback  functions  use 
compression  information  structures  to  exchange  information  about  compressed 
images.  The  SeqGrabFramelnfo  (IV-2430)  structure  defines  a  frame  for  a  sequence 
grabber  component  and  sequence  grabber  channel  components.  You  need  to  know 
about  this  structure  only  if  you  are  creating  a  sequence  grabber  component. 
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Data  Structures 


SGCompressInfo  (IV-2432) 

Defines  the  characteristics  of  a  buffer  that  contains  a  captured  image  that  has 
been  compressed. 

SeqGrabFramelnfo  (IV-2430) 

Provides  information  about  a  frame  for  a  sequence  grabber  component  and  its 
sequence  grabber  channel  components. 


Configuring  Sequence  Grabber  Components 

Sequence  grabber  components  provide  a  number  of  functions  that  allow  you  to 
establish  the  environment  for  grabbing  or  previewing  digitized  data.  Before  you 
can  start  a  record  or  a  preview  operation,  you  must  initialize  the  sequence  grabber 
component,  establish  the  channels  that  will  be  used,  define  the  display  environment 
for  the  operation,  and  determine  the  optimum  screen  position  for  the  sequence 
grabber.  In  addition,  if  you  are  performing  a  record  operation,  you  must  define  a 
destination  movie  file. 

You  use  SGInitialize  (III— 1752)  to  initialize  a  sequence  grabber  component.  Then 
SGNewChannel  (III— 1753)  allows  you  to  create  channels  for  the  sequence  grabber  for 
an  operation.  You  can  use  SGNewChannel  FromComponent  (III— 1756)  to  create  a  new 
channel  using  a  specified  channel  component.  Use  SGDi  sposeChannel  (III— 1695)  to 
dispose  of  those  channels  that  you  are  no  longer  using.  Y  ou  can  useSGGetlndChannel 
(III— 1720)  to  retrieve  information  about  the  channels  that  are  currently  in  use  by  the 
sequence  grabber. 

You  can  use  SGSetGWorl  d  (III— 1792)  and  SGGetGWorl  d  (III— 1719)  to  establish  the 
display  environment  for  the  sequence  grabber.  These  functions  affect  only  those 
channels  that  work  with  data  that  has  visual  information. 

SGSetDataOutput  (III— 1785)  and  SGGetDataOutput  (III— 1711)  allow  you  to  identify  the 
movie  file  that  is  currently  assigned  to  the  sequence  grabber.  You  only  use  these 
functions  when  you  are  performing  a  record  operation. 

SGSetDataProc  (III— 1787)  allows  you  to  assign  a  data  function  to  a  channel.  The 
sequence  grabber  calls  your  data  function  whenever  it  writes  movie  data  to  the 
output  file.  SGGetAl  i  gnmentProc  (III— 1698)  allows  you  to  determine  a  sequence 
grabber's  optimum  screen  position  to  ensure  the  best  performance  and  appearance. 
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Functions 


SGIni  1 1  a  1  i  ze  (III — 1 752) 

Initializes  the  sequence  grabber  component. 

SGNewChannel  (III — 1 753) 

Creates  a  sequence  grabber  channel  and  assigns  a  channel  component  to  the 
channel. 

SGNewChannel  FromComponent  (III — 1 756) 

Creates  a  sequence  grabber  channel  and  assigns  a  channel  component  to  the 
channel. 

SGDi sposeChannel  (III — 1695) 

Removes  a  channel  from  a  sequence  grabber  component. 

SGGetlndChannel  (III — 1 720) 

Collects  information  about  all  of  the  channel  components  currently  in  use  by  a 
sequence  grabber  component. 

SGSetGWorld  (III — 1 792) 

Establishes  the  graphics  port  and  device  for  a  sequence  grabber  component. 
SGGetGWorld  (III — 1 719) 

Determines  the  graphics  port  and  device  for  a  sequence  grabber  component. 
SGSetDataOutput  (III — 1 785) 

Specifies  the  movie  file  and  options  for  a  sequence  grabber  record  operation. 
SGGetDataOutput  (III — 1 711) 

Determines  the  movie  file  that  is  currently  assigned  to  a  sequence  grabber 
component  and  the  control  flags  that  would  govern  a  record  operation. 

SGSetDataProc  (III— 1787) 

Specifies  a  data  function  for  use  by  the  sequence  grabber. 

SGSetDataRef  (III— 1787) 

Specifies  the  destination  data  reference  for  a  record  operation. 

SGGetDataRef  (III— 1716) 

Determines  the  data  reference  currently  assigned  to  a  sequence  grabber 
component  and  the  control  flags  that  would  govern  a  record  operation. 

SGGetAl  i  gnmentProc  (III — 1 698) 

Obtains  information  about  the  best  screen  positions  for  a  sequence  grabber's 
video  image  in  terms  of  appearance  and  maximum  performance. 
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Controlling  Sequence  Grabber  Components 


Sequence  grabber  components  provide  a  full  set  of  functions  that  allow  your 
application  to  control  the  preview  or  record  operation.  You  can  use  these  functions 
to  start  and  stop  the  operation,  to  pause  data  collection,  and  to  retrieve  a  reference 
to  the  movie  that  is  created  during  a  record  operation. 

Use  SGStartPrevi  ew  (III— 1818)  to  start  a  preview  operation.  SGStartRecord  (III— 1819) 
lets  you  start  a  record  operation.  SGStop  (III— 1819)  allows  you  to  stop  a  sequence 
grabber  component.  You  can  instruct  the  sequence  grabber  to  pause  by  calling 
SGPause  (III— 1771).  You  can  determine  whether  the  sequence  grabber  is  paused  by 
calling  SGGetPause  (III— 1730). 

You  grant  processing  time  to  the  sequence  grabber  by  calling  SGI  die  (III— 1751).  Be 
sure  to  call  this  function  often  during  record  and  preview  operations.  If  your 
application  receives  an  update  event  during  a  record  or  preview  operation,  you 
should  call  SGUpdate  (III— 1821). 

You  can  prepare  the  sequence  grabber  for  an  upcoming  preview  or  record  operation 
by  calling  SGPrepare  (III— 1772).  This  function  also  allows  the  sequence  grabber  to 
verify  that  it  can  support  the  parameters  you  have  specified.  By  verifying  the 
parameters  you  want  to  use,  you  can  improve  the  startup  of  preview  and  record 
operations.  Use  SGRel  ease  (III— 1773)  to  release  system  resources. 

You  can  retrieve  a  reference  to  the  movie  created  by  a  record  operation  by  calling 
SGGetMovie  (III— 1724).  You  can  determine  the  resource  ID  value  assigned  to  the  last 
movie  resource  created  by  the  sequence  grabber  by  calling  SGGetLastMovi  e  Res  ID 
(III— 1722).  You  can  extract  a  picture  from  the  video  source  data  by  calling 
SGGrabPict  (III — 1748). 


SUM 


Functions 

SGStartPrevi  ew  (III — 1 818) 

Instructs  the  sequence  grabber  to  begin  processing  data  from  its  channels. 
SGStartRecord  (III — 18 1 9) 

Instructs  the  sequence  grabber  component  to  begin  collecting  data  from  its 
channels. 

SGStop  (III— 1819) 

Stops  a  preview  or  record  operation. 
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SGPause  (III— 1771) 

Suspends  or  restarts  a  sequence  grabber  record  or  preview  operation. 
SGGetPause  (III— 1730) 

Determines  whether  the  sequence  grabber  is  paused. 

SGIdl  e  (III— 1 751) 

Provides  processing  time  for  sequence  grabber  components. 

SGUpdate  (III— 1821) 

Informs  your  component  about  update  events,  to  update  its  display. 

SGPrepare  (III— 1772) 

Instructs  a  sequence  grabber  to  get  ready  to  begin  a  preview  or  record 
operation. 

SGRelease (HI-1773) 

Instructs  the  sequence  grabber  to  release  any  system  resources  it  allocated 
when  you  called  SGPrepare  (III— 1772). 

SGGetMovi  e  (III— 1724) 

Returns  a  reference  to  the  movie  that  contains  the  data  collected  during  a  record 
operation. 

SGGetLastMovi  e Res  ID  (III— 1722) 

Retrieves  the  last  resource  ID  used  by  the  sequence  grabber  component. 
SGGrabPi  ct  (III— 1748) 

Lets  your  application  obtain  a  Picture  (IV-2331)  structure  from  a  sequence 
grabber  component. 

SGGetMode  (III— 1723) 

Determines  whether  a  sequence  grabber  component  is  in  preview  mode  or 
record  mode. 


Working  With  Sequence  Grabber  Settings 

Sequence  grabber  components  can  work  with  channel  components  and  panel 
components  to  collect  configuration  settings  from  the  user.  Five  functions  allow  you 
to  direct  the  sequence  grabber  to  display  its  settings  dialog  box  to  the  user  and  to 
work  with  the  configuration  of  each  of  the  grabber's  channels. 

Use  SGSetti  ngsDi  al  og  (III— 1808)  to  instruct  the  sequence  grabber  to  display  its 
settings  dialog  box  to  the  user.  SGSetSetti  ngs  (III— 1801)  and  SGGetSetti  ngs 
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(Ill— 1731)  allow  you  to  retrieve  or  set  the  sequence  grabber's  configuration. 
SGSetChannel  Setti  ngs  (III— 1781)  and  SGGetChannel  Setti  ngs  work  with  the 
configuration  of  an  individual  channel. 


Functions 

SGSetti  ngsDi  al  og  (III — 1 808) 

Causes  a  sequence  grabber  to  display  its  settings  dialog  box  to  the  user. 
SGSetSetti ngs  (III — 1801) 

Configures  a  sequence  grabber  and  its  channels. 

SGGetSetti ngs  (III— 1731) 

Retrieves  the  current  settings  of  all  channels  used  by  the  sequence  grabber. 

SGSetChannel  Setti  ngs  (III — 1 781) 

Configures  a  sequence  grabber  channel. 

SGGetChannel  Setti  ngs  (III — 1707) 

Retrieves  the  current  settings  of  a  channel  used  by  the  sequence  grabber. 
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Working  With  Sequence  Grabber  Characteristics 

Sequence  grabber  components  provide  a  number  of  functions  for  working  with 
characteristics  that  apply  to  the  sequence  grabber  component  itself. 

Use  SGSetMaxi  mumRecordT i  me  (III— 1796)  to  limit  the  duration  of  a  record  operation. 
You  can  retrieve  this  time  limit  by  calling  SGGetMaxi mumRecordT ime  (III— 1723). 
SGSetFl  ags  allows  you  to  set  control  flags  that  govern  an  operation.  Use  SGGetFl  ags 
(III— 1718)  to  retrieve  those  flags.  You  can  obtain  information  about  the  progress  of 
a  record  operation  by  calling  SGGetStorageSpaceRemaining  (III— 1736)  and 
SGGetT i  meRemai  ni  ng.  You  can  retrieve  a  reference  to  the  time  base  used  by  a 
sequence  grabber  component  by  calling  SGGetTi  meBase  (ill-1738). 


Functions 


SGSetMaxi  mumRecordTi  me  (III — 1 796) 

Limits  the  duration  of  a  record  operation 

SGGetMaxi  mumRecordTi  me  (III —  1 723) 

Determines  the  time  limit  you  have  set  for  a  record  operation. 
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SGSetFl  ags  (III— 1789) 

Passes  control  information  about  the  current  operation  to  the  sequence  grabber 
component. 

SGGetFl  ags  (III— 1718) 

Retrieves  a  sequence  grabber's  control  flags. 

SGGetStorageSpaceRemai ni ng  (III — 1736) 

Monitors  the  amount  of  space  remaining  for  use  during  a  record  operation. 

SGGetTimeRemaining  (III — 1 739) 

Obtains  an  estimate  of  the  amount  of  recording  time  that  remains  for  the 
current  record  operation. 

SGGetTimeBase  (III— 1738) 

Retrieves  a  reference  to  the  time  base  that  is  being  used  by  a  sequence  grabber 
component. 

See  Also 

The  characteristics  that  govern  a  sequence  grabber  operation  fall  into  two  main 
categories:  those  that  apply  to  the  sequence  grabber  component,  and  those  that 
apply  to  an  individual  channel  that  has  been  created  for  the  sequence  grabber.  This 
section  describes  functions  that  apply  to  the  sequence  grabber  component.  See 
"Working  With  Channel  Characteristics"  (V-2815)  for  programming  information 
about  functions  that  apply  to  a  single  channel. 


Working  With  Sequence  Grabber  Outputs 

A  sequence  grabber  output  ties  a  sequence  grabber  channel  to  a  specified  data 
reference  for  the  output  of  captured  data.  It  lets  you  capture  to  more  than  one  data 
reference  at  a  time. 

If  you  want  to  capture  movie  data  into  several  different  files  or  data  references,  you 
must  use  the  functions  listed  below  to  do  so.  Even  if  you  are  using  outputs,  you 
must  still  use  SGSetDataOutput  (III — 1785)  or  SGSetDataRef  (III — 1787)  to  identify 
where  the  sequence  grabber  should  create  the  movie  resource. 


Functions 

SGNewOutput  (III— 1757) 

Creates  a  new  sequence  grabber  output. 

SGDi sposeOutput  (III — 1 696) 

Disposes  of  an  existing  sequence  grabber  output. 
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SGSetChannel  Output  (III — 1 778) 

Assigns  an  output  to  a  channel. 

SGSetOutputFl  ags  (ID-1797) 

Configures  an  existing  sequence  grabber  output. 

SGGetDataOutputStorageSpaceRemai ni ng  (III-1713) 

Returns  the  amount  of  space  remaining  in  the  data  reference  associated  with  an 
output. 

SGSetOutputNextOutput  (III-1800) 

Specifies  the  order  in  which  sequence  grabber  outputs  should  be  used. 
SGGetOutputNextOutput  (III-1729) 

Returns  the  next  sequence  grabber  output  for  the  specified  output. 
SGSetOutputMaxi mumOf f set  (III-1799) 

Specifies  the  maximum  offset  for  data  written  to  a  specified  sequence  grabber 
output. 

SGGetOutputMaxi mumOf f set  (III-1728) 

Returns  the  maximum  offset  for  data  written  to  the  specified  sequence  grabber 
output. 

SGGetOut  put  Data  Reference  (III-1727) 

Returns  information  about  the  data  reference  associated  with  the  specified 
sequence  grabber  output. 
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Working  With  Channel  Characteristics 

Sequence  grabber  components  use  channel  components  to  obtain  digitized  data 
from  external  media.  After  you  create  a  channel  for  a  sequence  grabber  component, 
you  must  configure  that  channel  before  you  start  a  preview  or  record  operation.  The 
sequence  grabber  component  provides  a  number  of  functions  that  allow  you  to 
configure  the  characteristics  of  a  channel  component. 

Use  SGSetChannel  Usage  (III-1782)  to  specify  how  a  channel  is  to  be  used.  You  can 
restrict  a  channel  to  use  during  record  or  preview  operations.  In  addition,  this 
function  allows  you  to  specify  whether  a  channel  plays  during  a  record  operation. 
SGGetChannel  Usage  (III-1709)  enables  you  to  determine  a  channel's  usage. 
SGGetChannel  Info  (III-1702)  allows  you  to  determine  whether  a  channel  has  a  visual 
or  an  audio  representation. 
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SGSetChannel  PI  ay  FI  ags  (III— 1779)  allows  you  to  influence  the  speed  and  quality 
with  which  the  sequence  grabber  displays  captured  data.  SGGetChannelPlayFlags 
(III— 1705)  lets  you  determine  these  flag  settings.  SGSetChannel  MaxFrames  (III— 1777) 
establishes  a  limit  on  the  number  of  frames  that  the  sequence  grabber  will  capture 
from  a  channel.  SGGetChannel  MaxFrames  (III— 1704)  allows  you  to  determine  that 
limit. 

SGSetChannel  Bounds  (III— 1774)  allows  you  to  set  the  display  boundary  rectangle  for 
a  channel.  Use  SGGetChannel  Bounds  (III— 1700)  to  determine  a  channel's  boundary 
rectangle.  SGSetChannel  Vol  ume  (III— 1783)  allows  you  to  control  a  channel's  sound 
volume.  Use  SGGetChannel  Vol  ume  (III— 1710)  to  determine  a  channel's  volume. 

SGSetChannelRefCon  (III— 1781 )  allows  you  to  set  the  value  of  a  reference  constant  that 
is  passed  to  your  callback  functions.  Use  SGGetChannel  Sampl  eDescri  pti  on  (III— 1706) 
to  retrieve  a  channel's  sample  description.  SGGetChannelTimeScale  (III— 1708)  allows 
you  to  obtain  the  channel's  time  scale.  You  can  modify  or  retrieve  the  channel's 
clipping  region  by  calling  SGSetChannel  Cl  i  p  (III-1775)  or  SGGetChannel  Cl  i  p 
(III— 1700),  respectively.  You  can  work  with  a  channel's  transformation  matrix  by 
calling  SGSetChannel  Matri x  (III— 1776)  and  SGGetChannel  Matri x. 


Functions 

SGSetChannel  Usage  (III — 1 782) 

Specifies  how  a  channel  is  to  be  used  by  the  sequence  grabber  component. 
SGGetChannel  Usage  (III — 1 709) 

Determines  how  the  sequence  grabber  component  is  using  a  channel. 
SGGetChannel  Info  (III — 1 702) 

Determines  how  a  channel's  data  is  represented  to  the  user:  as  visual  data  or 
audio  data,  or  both. 

SGSetChannel  PI  ay  FI  ags  (III — 1 779) 

Adjusts  the  speed  and  quality  with  which  the  sequence  grabber  displays  data 
from  a  channel. 

SGGetChannel  PI  ay  FI  ags  (III — 1 705) 

Retrieves  the  playback  control  flags  that  you  set  with  SGSetChannel  PI  ayFl  ags 
(III— 1779). 

SGSetChannel  MaxFrames  (III — 1777) 

Limits  the  number  of  frames  that  the  sequence  grabber  will  capture  from  a 
specified  channel. 
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SGGetChannel  MaxFrames  (III — 1 7 04 ) 

Determines  the  number  of  frames  left  to  be  captured  from  a  specified  channel. 

SGSetChannel  Bounds  (III — 1 774) 

Specifies  a  channel's  display  boundary  rectangle. 

SGGetChannel  Bounds  (III — 1 700) 

Determines  a  channel's  display  boundary  rectangle. 

SGSetChannel  Vol  ume  (III — 1 783) 

Sets  a  channel's  sound  volume. 

SGGetChannel  Vol  ume  (III — 1 710) 

Determines  a  channel's  sound  volume  setting. 

SGSetChannel  RefCon  (III — 1 7811 

Sets  the  value  of  a  reference  constant  that  is  passed  to  your  callback  functions 
for  channel  components. 

SGGetChannel  Sampl  eDescri  pti  on  (III — 1 706) 

Retrieves  a  channel's  sample  description  structure. 

SGGetChannel  Ti meScal  e  (III — 1 708) 

Lets  the  sequence  grabber  retrieve  a  channel's  time  scale. 

SGSetChannel  Cl  i  p  (III — 1 775) 

Sets  a  channel's  clipping  region. 

SGGetChannel  Cl  i  p  (III — 1 700) 

Retrieves  a  channel's  clipping  region. 

SGSetChannel  Matrix  (III — 1 776) 

Sets  a  channel's  display  transformation  matrix. 

SGGetChannel  Matri x  (III — 1 703) 

Retrieves  a  channel's  display  transformation  matrix. 

See  Also 

The  characteristics  that  govern  a  sequence  grabber  operation  fall  into  two  main 
categories:  those  that  apply  to  the  sequence  grabber  component,  and  those  that 
apply  to  an  individual  channel  that  has  been  created  for  the  sequence  grabber.  This 
section  describes  functions  that  apply  to  individual  channels.  See  "Working  With 
Sequence  Grabber  Characteristics"  (V-2813)  for  programming  information  about 
functions  that  apply  to  the  sequence  grabber  component  itself. 

Besides  the  generic  channel  functions  listed  here,  sequence  grabber  components 
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provide  functions  that  are  specific  to  the  channel  type.  See  "Working  With  Video 
Channels"  (V-2819)  for  information  about  the  sequence  grabber  configuration 
functions  that  work  only  with  video  channels.  See  "Working  With  Sound 
Channels"  (V-2821)  for  information  about  the  sequence  grabber  configuration 
functions  that  work  only  with  sound  channels. 


Working  With  Channel  Devices 

Sequence  grabbers  provide  a  number  of  functions  that  allow  you  to  determine  the 
device  that  is  attached  to  a  given  sequence  grabber  channel.  These  devices  allow  the 
channel  component  to  control  the  digitizing  equipment.  For  example,  video 
channels  use  video  digitizer  components,  and  sound  channels  use  sound  input 
drivers.  Your  application  can  use  these  routines  to  present  a  list  of  available  devices 
to  the  user,  allowing  the  user  to  select  a  specific  device  for  each  channel. 

You  may  use  SGGetChannel  DeviceList  (III— 1701)  to  retrieve  a  list  of  devices  that  may 
be  used  with  a  specified  channel.  You  dispose  of  this  device  list  by  calling 
SGDi  sposeDevi  ceLi  st  (III— 1696).  You  can  place  one  or  more  device  names  into  a 
menu  by  calling  SGAppendDevi ceLi  stToMenu  (III— 1685).  You  can  use 
SGSetChannel  Devi  ce  (III— 1776)  to  assign  a  device  to  a  channel. 

Some  of  these  functions  use  a  SGDevi  ceLi  stRecord  (IV-2433)  structure  to  pass 
information  about  one  or  more  channel  devices. 


Functions 

SGGetChannel  Devi  ceLi  st  (III — 1 701) 

Retrieves  a  list  of  the  devices  that  are  valid  for  a  specified  channel. 

SGDi  sposeDevi  ceLi  st  (III — 1 696) 

Disposes  of  a  device  list. 

SGAppendDevi  ceLi  stToMenu  (III — 1 685) 

Places  a  list  of  device  names  into  a  specified  menu. 

SGSetChannel  Devi  ce  (III — 1 776) 

Assigns  a  device  to  a  channel. 

Data  Structure 

SGDevi  ceLi  stRecord  (IV-2433) 

Passes  information  about  one  or  more  channel  devices. 
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Working  With  Video  Channels 


Sequence  grabber  components  provide  a  number  of  functions  that  allow  you  to 
configure  the  grabber's  video  channels.  You  can  use  these  functions  only  with  video 
channels.  You  can  determine  whether  a  channel  has  a  visual  representation  by 
calling  SGGetChannel  Info  (III — 1702). 

SGGetSrcVi  deoBounds  (III— 1735)  allows  you  to  determine  the  coordinates  of  the 
source  video  boundary  rectangle.  This  rectangle  defines  the  size  of  the  source  video 
image  being  captured  by  the  video  channel.  You  can  use  SGSetVi  deoRect  (III— 1816) 
to  specify  a  part  of  the  source  video  boundary  rectangle  to  be  captured  by  the 
channel.  SGGetVi  deoRect  (III— 1746)  allows  you  to  determine  the  active  source  video 
rectangle. 

Typically,  the  sequence  grabber  component  uses  the  Image  Compression  Manager 
to  compress  the  video  data  it  captures.  You  can  control  many  aspects  of  this 
image-compression  process.  Use  SGSetVi  deoCompressorType  (III— 1814)  to  specify  the 
type  of  image  compressor  to  use.  You  can  determine  the  type  of  image  compressor 
currently  in  use  by  calling  SGGetVi  deoCompressorType  (III— 1744).  You  can  specify  a 
particular  image  compressor  and  set  many  image-compression  parameters  by 
calling  SGSetVi  deoCompressor  (III— 1812).  You  can  determine  which  image 
compressor  is  being  used  and  its  parameter  settings  by  calling 
SGGetVi  deoCompressor  (III — 1742). 

Sequence  grabber  components  provide  functions  that  allow  you  to  work  with  a 
channel's  video  digitizer  component.  You  can  use  SGGetVi  deoDigi  ti  zerComponent 
(III— 1745)  to  determine  which  video  digitizer  component  is  supplying  data  to  a 
specified  channel  component.  You  can  set  a  channel's  video  digitizer  by  calling 
SGSetVi  deoDi  gi  ti  zerComponent  (III— 1815).  If  you  change  any  video  digitizer  settings 
by  calling  the  video  digitizer  component  directly,  you  should  inform  the  sequence 
grabber  component  by  calling  SGVi  deoDi  gi  ti  zerChanged  (III— 1822). 

Some  video  source  data  may  contain  unacceptable  levels  of  visual  noise  or  artifacts. 
One  technique  for  removing  this  noise  is  to  capture  the  image  and  then  reduce  it  in 
size.  During  the  size  reduction  process,  the  noise  can  be  filtered  out. 
SGSetCompressBuf  f  er  (III— 1784)  sets  a  filter  buffer  for  a  video  channel. 
SGGetCompressBuf  f  er  (III— 1711)  returns  information  about  your  filter  buffer. 

You  can  work  with  a  video  channel's  frame  rate  by  calling  SGSet  Frame  Rate  (III— 1792) 
and  SGGetFrameRate  (III— 1719).  You  can  control  whether  a  channel  uses  an  offscreen 
buffer  by  calling  SGSetUseScreenBuffer  (III— 181 1)  and  SGGetUseScreenBuf  fer. 


SUM 


Inside  QuickTime:  Programming  Summary 


V-2819 


Programming  Summary 


Functions 


SGGetSrcVi  deoBounds  (III — 1 735) 

Determines  the  size  of  the  source  video  boundary  rectangle. 

SGSetVi  deoRect  (III— 1816) 

Specifies  a  part  of  the  source  video  image  that  is  to  be  captured  by  a  sequence 
grabber  component. 

SGGetVi  deoRect  (III— 1746) 

Determines  the  portion  of  the  source  video  image  that  is  to  be  captured. 
SGSetVi  deoCompressorType  (III — 1814) 

Specifies  the  type  of  image  compression  to  be  applied  to  captured  video 
images. 

SGGetVi  deoCompressorType  (III — 1 744) 

Determines  the  type  of  image  compression  that  is  being  applied  to  a  channel's 
video  data. 

SGSetVi  deoCompressor  (III — 18 1 2) 

Specifies  many  of  the  parameters  that  control  image  compression  of  the  video 
data  captured  by  a  video  channel. 

SGGetVi  deoCompressor  (III — 1 742) 

Determines  a  channel's  current  image  compression  parameters. 

SGGetVi  deoDi  gi  ti  zer Component  (III — 1745) 

Determines  the  video  digitizer  component  that  is  providing  source  video  to  a 
video  channel  component. 

SGSetVi  deoDi  giti  zer  Component  (III — 1 815) 

Assigns  a  video  digitizer  component  to  a  video  channel. 

SGVi  deoDi  gi  ti  zerChanged  (III — 1822) 

Notifies  the  sequence  grabber  component  whenever  you  change  the 
configuration  of  a  video  channel's  video  digitizer. 

SGSetCompressBuffer  (III — 1 784) 

Allows  the  sequence  grabber  component  to  direct  your  component  to  create  a 
filter  buffer  for  your  video  channel. 

SGGetCompressBuffer  (III — 1 711) 

Returns  information  about  the  filter  buffer  established  for  a  video  channel. 
SGSetFrameRate  (III— 1792) 

Specifies  a  video  channel's  frame  rate  for  recording. 
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SGGetFrameRate  (ID-1719) 

Retrieves  a  video  channel's  frame  rate  for  recording. 

SGSetUseScreenBuf fer  (III — 181 1 ) 

Controls  whether  a  video  channel  uses  an  offscreen  buffer. 

SGGetUseScreenBuf f er  (III — 1 740) 

Determines  whether  a  video  channel  is  allowed  to  use  an  offscreen  buffer. 


Working  With  Video  Fields 
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Three  functions  let  you  work  with  compressed  fields  of  video  data. 

The  ImageFieldSequenceBegin  (11-746)  function  initiates  an  image  field  sequence 
operation;  the  ImageFiel  dSequenceExtractCombi ne  (11-747)  function  performs  the 
desired  operations;  and  the  ImageFieldSequenceEnd  (11-747)  function  terminates  the 
operation. 


Functions 

ImageFi  el  dSequenceBegi  n  (11-746) 

Initiates  an  image  field  sequence  operation  and  specifies  the  input  and  output 
data  format. 

ImageFi  el  dSequenceExtractCombi  ne  (11-747) 

Performs  field  operations  on  video  data. 

ImageFieldSequenceEnd  (11-747) 

Ends  an  image  field  sequence  operation. 


Working  With  Sound  Channels 

Sequence  grabber  components  provide  a  number  of  functions  that  allow  you  to 
configure  the  grabber's  sound  channels.  You  can  use  these  functions  only  with 
sound  channels.  You  can  determine  whether  a  channel  has  a  sound  representation 
by  calling  SGGetChannel  Info  (III— 1702). 

Use  SGSetSoundlnputDri  ver  (III— 1802)  to  specify  a  channel's  sound  input  device. 
You  can  determine  a  channel's  sound  input  device  by  calling 
SGGetSoundlnputDri  ver  (III— 1732).  If  you  change  any  attributes  of  the  sound  input 
device,  you  should  notify  the  sequence  grabber  component  by  calling 
SGSoundlnputDriverChanged  (III— 1 8 1 7) .  By  default,  the  sequence  grabber  component 
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uses  the  sound  driver's  best  settings.  You  can  control  the  amount  of  sound  data  the 
sequence  grabber  works  with  at  one  time  by  calling  SGSetSoundRecordChunkSi  ze 
(III— 1805).  You  can  determine  this  value  by  calling  SGGetSoundRecordChunkSi  ze 
(III— 1734). 

You  can  control  the  rate  at  which  the  sound  channel  samples  the  input  data  by 
calling  SGSetSoundlnputRate  (III— 1804).  You  can  determine  the  sample  rate  by 
calling  SGGetSoundlnputRate  (III— 1734).  You  can  control  other  sound  input 
parameters  by  using  SGSetSoundlnputParameters  (III— 1803)  and 
SGGet Sound  Input Parameters. 


Functions 

SGSetSoundlnputDri  ver  (III — 1802) 

Assigns  a  sound  input  device  to  a  sound  channel. 

SGGetSoundlnputDri  ver  (III — 1 732) 

Determines  the  sound  input  device  currently  in  use  by  a  sound  channel 
component. 

SGSoundlnputDriverChanged  (III — 1817) 

Notifies  the  sequence  grabber  component  whenever  you  change  the 
configuration  of  a  sound  channel's  sound  input  device. 

SGSetSoundRecordChunkSi  ze  (III — 1805) 

Controls  the  amount  of  sound  data  in  each  group  of  sound  samples  during  a 
record  operation. 

SGGetSoundRecordChunkSi  ze  (III — 1 734) 

Determines  the  amount  of  sound  data  the  sequence  grabber  component  works 
with  at  a  time. 

SGSetSoundlnputRate  (III — 1804) 

Sets  the  rate  at  which  the  sound  channel  obtains  its  sound  data. 
SGGetSoundlnputRate  (III — 1 7 34) 

Determines  the  rate  at  which  the  sound  channel  is  collecting  sound  data. 

SGSetSoundlnputParameters  (III — 1803) 

Sets  various  parameters  that  relate  to  sound  recording. 

SGGet  Sound  Input  Parameters  (III — 1 733) 

Retrieves  various  parameters  that  relate  to  sound  recording. 
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Sequence  grabber  components  allow  you  to  define  a  number  of  callback  functions 
in  your  application.  The  sequence  grabber  calls  your  functions  at  specific  points  in 
the  process  of  collecting,  compressing,  and  displaying  the  source  video  data.  By 
defining  callback  functions,  you  can  control  the  process  more  precisely  or  customize 
the  operation  of  the  sequence  grabber  component. 

SGSetVi  deoBottl  enecks  (III— 1811)  lets  you  assign  callback  functions  to  a  video 
channel.  You  can  use  SGGetVi  deoBottl  enecks  (III— 1741)  to  determine  the  callback 
functions  that  have  been  assigned  to  a  video  channel.  The  Vi  deoBottl  es  (IV-2501) 
structure  identifies  the  callback  functions  to  be  assigned  to  the  channel. 

Your  SGGrabBottl  eProc  (III— 2142)  callback  is  used  by  the  sequence  grabber 
component  to  begin  the  capture  of  a  frame  of  video  data.  Your 
SGGrabCompl  eteBottl  eProc  (III— 2143)  callback  allows  the  sequence  grabber 
component  to  determine  whether  the  current  frame-capture  operation  is  complete. 

Your  SGDi  spl  ayBottl  eProc  (III— 2140)  callback  enables  the  sequence  grabber 
component  to  move  a  captured  video  image  in  an  offscreen  buffer  into  the 
destination  buffer  for  the  video  channel.  The  sequence  grabber  component  uses 
your  SGCompressBottl  eProc  (III— 2137)  callback  to  commence  the  compression  of  a 
captured  video  image.  Your  SGCompressCompl  eteBottl  eProc  (III— 2138)  callback 
helps  the  sequence  grabber  component  to  find  out  if  the  current  frame-compression 
operation  is  finished.  Your  SGAddFrameBottl  eProc  (III— 2136)  callback  lets  the 
sequence  grabber  component  add  a  frame  to  a  movie. 

The  sequence  grabber  component  uses  your  SGT ransferFrameBottl  eProc  (III— 2145) 

callback  to  move  a  video  frame  from  the  capture  buffer  into  the  channel's  filter 

buffer.  You  may  provide  two  functions  for  use  with  compressed-source  devices. 

Your  SGGrabCompressCompl  eteBottl  eProc  (III— 2143)  callback  determines  when  the 

current  capture  and  compress  operation  is  complete.  Your 

SGDi  spl  ayCompressBottl  eProc  (III— 2141)  callback  decompresses  and  displays  a 

frame. 
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Functions 


SGSetVi  deoBottl  enecks  (III — 1811) 

Assigns  callback  functions  to  a  video  channel. 

SGGetVi  deoBottl  enecks  (III — 1741) 

Determines  the  callback  functions  that  have  been  assigned  to  a  video  channel. 
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Data  Structures 


VideoBottles  (IV-2501) 

Identifies  the  callback  functions  to  be  assigned  to  a  sequence  grabber  channel. 


Using  Sequence  Grabber  Channels 


Sequence  grabber  components  use  sequence  grabber  channel  components  to  obtain 
data  from  audio-  or  video-digitizing  equipment.  These  components  isolate  the 
sequence  grabber  component  from  the  details  of  working  with  the  various  types  of 
data  that  can  be  collected.  The  functionality  provided  by  a  sequence  grabber 
component  depends  upon  the  services  provided  by  sequence  grabber  channel 
components.  The  channel  components,  in  turn,  may  use  other  components  to 
interact  with  the  digitizing  equipment. 


Configuring  Sequence  Grabber  Channel  Components 

Sequence  grabber  components  use  two  functions  to  establish  the  environment  for 
grabbing  or  previewing  digitized  data. 

The  sequence  grabber  component  uses  SGInitChannel  (III— 1751)  to  initialize  your 
channel  prior  to  a  record  or  preview  operation.  SGSetGWorl  d  (III— 1 792)  allows  the 
sequence  grabber  component  to  assign  a  graphics  world  to  your  component. 


Functions 


SGInitChannel  (III — 1 751) 

Initializes  a  channel  component. 

SGSetGWorl  d  (III— 1792) 

Establishes  the  graphics  port  and  device  for  a  sequence  grabber  component. 


Controlling  Sequence  Grabber  Channel  Components 

Sequence  grabber  channel  components  must  provide  a  full  set  of  functions  that 
allow  the  sequence  grabber  component  to  control  the  preview  or  record  operation. 
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The  sequence  grabber  component  can  use  these  functions  to  start  and  stop  the 
operation,  to  pause  data  collection,  and  to  write  captured  data  to  a  movie. 

The  sequence  grabber  component  uses  SGStartPrevi  ew  (III— 1818)  to  start  a  preview 
operation.  SGStartRecord  (III— 1819)  starts  a  record  operation.  SGStop  (III— 1819)  stops 
your  channel  component  after  a  preview  or  record  operation.  The  sequence  grabber 
component  grants  processing  time  to  your  channel  component  by  calling  SGIdl  e 
(III— 1751).  The  sequence  grabber  notifies  you  of  update  events  by  calling  SGUpdate 
(III— 1821).  The  sequence  grabber  pauses  the  current  operation  by  calling  SGPause 
(III— 1771). 
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The  sequence  grabber  component  calls  SGWri  teSampl  es  (III— 1825)  to  write  captured 
data  to  a  movie  file  after  a  record  operation.  The  sequence  grabber  component 
prepares  your  channel  component  for  an  upcoming  preview  or  record  operation  by 
calling  SGPrepare  (III— 1772).  This  function  also  allows  the  sequence  grabber 
component  to  verify  that  your  component  can  support  the  parameters  an 
application  has  specified.  SGRel  ease  (III— 1773)  releases  system  resources  allocated. 


Functions 

SGStartPrevi  ew  (III — 1 818) 

Instructs  the  sequence  grabber  to  begin  processing  data  from  its  channels. 
SGStartRecord  (III — 18 1 9) 

Instructs  the  sequence  grabber  component  to  begin  collecting  data  from  its 
channels. 

SGStop  (III— 1819) 

Stops  a  preview  or  record  operation. 

SGIdl  e  (III— 1751) 

Provides  processing  time  for  sequence  grabber  components. 

SGUpdate  (III— 1821) 

Informs  your  component  about  update  events,  to  update  its  display. 

SGPause  (III— 1771) 

Suspends  or  restarts  a  sequence  grabber  record  or  preview  operation. 

SGWri  teSampl  es  (III — 1825) 

Called  by  a  sequence  grabber  component  when  it  is  ready  to  add  recorded  data 
to  a  movie. 
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SGPrepare  (III— 1772) 

Instructs  a  sequence  grabber  to  get  ready  to  begin  a  preview  or  record 
operation. 

SGRelease  (III— 1773) 

Instructs  the  sequence  grabber  to  release  any  system  resources  it  allocated 
when  you  called  SGPrepare  (III— 1772). 

See  Also 

See  "Controlling  Sequence  Grabber  Components"  (V-2811). 


Configuration  Functions  for  All  Channel  Components 

A  sequence  grabber  component  must  provide  a  number  of  functions  that  allow  the 
sequence  grabber  to  configure  the  characteristics  of  your  channel.  Several  of  these 
functions  work  on  any  channel  component. 

SGSetChannel  Usage  (III— 1782)  specifies  how  your  channel  is  to  be  used.  The  sequence 
grabber  component  can  restrict  a  channel  to  use  during  record  or  preview 
operations.  In  addition,  this  function  allows  the  sequence  grabber  component  to 
specify  whether  your  channel  plays  during  a  record  operation.  SGGetChannel  Usage 
(III— 1709)  allows  the  sequence  grabber  component  to  determine  a  channel's  usage. 
SGGetChannel  Info  (III— 1702)  allows  the  sequence  grabber  component  to  determine 
some  of  the  characteristics  of  your  channel.  For  example,  this  function  returns 
information  indicating  whether  your  channel  has  a  visual  or  an  audio 
representation. 

SGSetChannel  PI  ay  FI  ags  (III— 1779)  lets  the  sequence  grabber  component  influence 
the  speed  and  quality  with  which  your  channel  plays  captured  data. 

SGGetChannel  PI  ay  FI  ags  (III— 1705)  allows  the  sequence  grabber  component  to 
determine  these  flag  settings.  SGSetChannel  MaxFrames  (III— 1777)  establishes  a  limit 
on  the  number  of  frames  that  your  channel  component  will  capture  from  a  channel. 
SGGetChannel  MaxFrames  (III— 1704)  enables  the  sequence  grabber  component  to 
determine  that  limit. 

SGSetChannel  RefCon  (III— 1781)  allows  the  sequence  grabber  component  to  set  the 
value  of  a  reference  constant  that  your  component  passes  to  its  callback  functions. 
SGGet  Data  Rate  (III— 1715)  allows  the  sequence  grabber  component  to  determine  how 
many  bytes  of  captured  data  your  channel  is  collecting  each  second. 

SGGetChannel  Sampl  eDescri  pti  on  (III— 1706)  allows  the  sequence  grabber  to  retrieve 
your  channel's  sample  description. 
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SGGetChannel  T i meScal  e  (III— 1708)  allows  it  to  obtain  your  channel's  time  scale.  The 
sequence  grabber  can  modify  or  retrieve  your  channel's  clipping  region  by  calling 
SGSetChannel  Cl  i  p  (III— 1775)  or  SGGetChannel  Cl  i  p  (III— 1 700),  respectively.  The 
sequence  grabber  can  work  with  your  channel's  transformation  matrix  by  calling 
SGSetChannel  Matrix  (III — 1776)  and  SGGetChannel  Matrix. 


Functions 

SGSetChannel  Usage  (III — 1 782) 

Specifies  how  a  channel  is  to  be  used  by  the  sequence  grabber  component. 
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SGGetChannel  Usage  (III — 1 709) 

Determines  how  the  sequence  grabber  component  is  using  a  channel. 
SGGetChannel  Info  (III— 1702) 

Determines  how  a  channel's  data  is  represented  to  the  user:  as  visual  data  or 
audio  data,  or  both. 

SGSetChannel  PI  ayFl  ags  (III — 1 779) 

Adjusts  the  speed  and  quality  with  which  the  sequence  grabber  displays  data 
from  a  channel. 

SGGetChannel  PI  ayFl  ags  (III — 1 705) 

Retrieves  the  playback  control  flags  that  you  set  with  SGSetChannel  PI  ayFl  ags 
(III— 1779). 

SGSetChannel  MaxFrames  (III — 1777) 

Limits  the  number  of  frames  that  the  sequence  grabber  will  capture  from  a 
specified  channel. 

SGGetChannel  MaxFrames  (III — 1 7 04 ) 

Determines  the  number  of  frames  left  to  be  captured  from  a  specified  channel. 
SGSetChannel  RefCon  (III — 1 781) 

Sets  the  value  of  a  reference  constant  that  is  passed  to  your  callback  functions 
for  channel  components. 

SGGetDataRate  (III— 1715) 

Determines  for  a  sequence  grabber  how  much  recording  time  is  left. 

SGGetChannel  Sampl  eDescri  pti  on  (III — 1 706) 

Retrieves  a  channel's  sample  description  structure. 

SGGetChannel  Ti meScal  e  (III — 1 708) 

Lets  the  sequence  grabber  retrieve  a  channel's  time  scale. 
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SGSetChannel  Cl  i  p  (III — 1 775) 

Sets  a  channel's  clipping  region. 

SGGetChannel  Cl  i  p  (III — 1 7001 

Retrieves  a  channel's  clipping  region. 

SGSetChannel  Matrix  (III — 1 776) 

Sets  a  channel's  display  transformation  matrix. 

SGGetChannel  Matri  x  (III — 1 703) 

Retrieves  a  channel's  display  transformation  matrix. 


Managing  Channel  Devices 

Sequence  grabbers  provide  two  functions  that  allow  applications  to  determine  the 
devices  that  can  be,  or  the  device  that  is,  attached  to  a  given  sequence  grabber 
channel.  These  devices,  in  turn,  allow  the  channel  component  to  control  the 
digitizing  equipment. 

The  sequence  grabber  may  use  SGGetChannel  Devi  ceLi  st  (III— 1701)  to  retrieve  a  list 
of  devices  that  may  be  used  by  your  channel.  The  sequence  grabber  can  use 
SGSetChannel  Devi  ce  (III— 1776)  to  assign  a  device  to  your  channel.  This  function  uses 
a  SGDevi  ceLi  stRecord  (IV-2433)  structure  to  pass  information  about  one  or  more 
channel  devices. 


Functions 

SGGetChannel  Devi  ceLi  st  (III — 1 701) 

Retrieves  a  list  of  the  devices  that  are  valid  for  a  specified  channel. 

SGSetChannel  Devi  ce  (III — 1 776) 

Assigns  a  device  to  a  channel. 

Data  Structure 

SGDevi  ceLi  stRecord  (IV-2433) 

Passes  information  about  one  or  more  channel  devices. 


Configuration  Functions  for  Video  Channel  Components 

Video  channel  components  provide  a  number  of  functions  that  allow  the  sequence 
grabber  to  configure  the  channel's  video  characteristics.  The  sequence  grabber 
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component  uses  these  video  channel  configuration  functions  only  with  video 
channels. 


SGSetChannel  Bounds  (III— 1774)  allows  the  sequence  grabber  to  set  the  display 
boundary  rectangle  for  a  video  channel.  SGGetChannel  Bounds  (III— 1700)  determines 
a  channel's  boundary  rectangle.  The  sequence  grabber  component  uses 
SGGetSrcVi  deoBounds  (III— 1735)  to  determine  the  coordinates  of  the  source  video 
boundary  rectangle.  This  rectangle  defines  the  size  of  the  source  video  image  being 
captured  by  a  video  channel.  SGSetVi  deoRect  (III— 1816)  specifies  a  part  of  the  source 
video  boundary  rectangle  to  be  captured  by  the  channel.  SGGetVi  deoRect  (III— 1746) 
retrieves  this  active  source  video  rectangle. 

Typically,  video  channel  components  use  the  Image  Compression  Manager  to 
compress  the  video  data  they  capture.  The  sequence  grabber  component  can  control 
many  aspects  of  this  image-compression  process.  SGSetVi  deoCompressorType 
(III— 1814)  specifies  the  type  of  image  compressor  to  use.  The  sequence  grabber  can 
determine  the  type  of  image  compressor  currently  in  use  by  calling 
SGGetVi  deoCompressorType  (III— 1744).  The  sequence  grabber  component  can  specify 
a  particular  image  compressor  and  set  many  image-compression  parameters  by 
calling  SGSetVi  deoCompressor  (III— 1812).  The  sequence  grabber  component  can 
determine  which  image  compressor  is  being  used  and  its  parameter  settings  by 
calling  SGGetVi  deoCompressor  (III— 1742). 

Sequence  grabber  components  provide  functions  that  allow  an  application  to  work 
with  a  channel's  video  digitizer  component.  Video  channel  components,  in  turn, 
must  provide  support  for  these  functions.  The  sequence  grabber  component  uses 
SGGetVi  deoDi  gi  ti  zerComponent  (III— 1745)  to  determine  which  video  digitizer 
component  is  supplying  data  to  your  video  channel  component.  The  sequence 
grabber  component  sets  a  channel's  video  digitizer  component  by  calling 
SGSetVi  deoDi  gi  ti  zerComponent  (III— 1815).  If  an  application  changes  any  video 
digitizer  settings  by  calling  the  video  digitizer  component  directly,  the  sequence 
grabber  component  informs  your  video  channel  component  by  calling 
SGVi  deoDi  gi  ti  zerChanged  (III — 1822). 

Some  video  source  data  may  contain  unacceptable  levels  of  visual  noise  or  artifacts. 
One  technique  for  removing  this  noise  is  to  capture  the  image  and  then  reduce  it  in 
size.  During  the  size  reduction  process,  the  noise  can  be  filtered  out.  Some  video 
channel  components  may  provide  functions  that  allow  the  sequence  grabber 
component  to  filter  the  input  video  data.  SGSetCompressBuffer  (III— 1784)  sets  a  filter 
buffer  for  a  video  channel.  SGGetCompressBuffer  (III— 1711)  returns  information 
about  your  filter  buffer. 
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The  sequence  grabber  can  work  with  a  video  channel's  frame  rate  by  calling 

SGSetFrameRate  (III— 1792)  and  SGGetFrameRate  (III— 1 719).  The  sequence  grabber  can 

control  whether  your  channel  uses  an  offscreen  buffer  by  calling 

SGSet Us eScreen Buffer  (III — 1811)  and  SGGetUseScreenBuffer.  SGA1 1  gnChannel  Rect 

(III— 1684)  allows  the  sequence  grabber  to  determine  a  channel's  optimum  screen 

position. 


Functions 

SGSetChannel  Bounds  (III — 1 774) 

Specifies  a  channel's  display  boundary  rectangle. 

SGGetChannel  Bounds  (III — 1 700 ) 

Determines  a  channel's  display  boundary  rectangle. 

SGGetSrcVi  deoBounds  (III — 1 735) 

Determines  the  size  of  the  source  video  boundary  rectangle. 

SGSetVi  deoRect  (III— 1816) 

Specifies  a  part  of  the  source  video  image  that  is  to  be  captured  by  a  sequence 
grabber  component. 

SGGetVi  deoRect  (III— 1746) 

Determines  the  portion  of  the  source  video  image  that  is  to  be  captured. 
SGSetVi  deoCompressorType  (III — 1 814) 

Specifies  the  type  of  image  compression  to  be  applied  to  captured  video 
images. 

SGGetVi  deoCompressorType  (III — 1 744) 

Determines  the  type  of  image  compression  that  is  being  applied  to  a  channel's 
video  data. 

SGSetVi  deoCompressor  (III — 1 812) 

Specifies  many  of  the  parameters  that  control  image  compression  of  the  video 
data  captured  by  a  video  channel. 

SGGetVi  deoCompressor  (III — 1 742) 

Determines  a  channel's  current  image  compression  parameters. 

SGGetVi  deoDi  gi  ti  zerComponent  (III — 1745) 

Determines  the  video  digitizer  component  that  is  providing  source  video  to  a 
video  channel  component. 
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SGSetVi  deoDi  gi  ti  zerComponent  (III — 1 815) 

Assigns  a  video  digitizer  component  to  a  video  channel. 

SGVi  deoDi  gi  ti  zerChanged  (III — 1822) 

Notifies  the  sequence  grabber  component  whenever  you  change  the 
configuration  of  a  video  channel's  video  digitizer. 

SGSetCompressBuf f er  (III — 1 784) 

Allows  the  sequence  grabber  component  to  direct  your  component  to  create  a 
filter  buffer  for  your  video  channel. 

SGGetCompressBuf f er  (111-1711) 

Returns  information  about  the  filter  buffer  established  for  a  video  channel. 
SGSetFrameRate  (III— 1792) 

Specifies  a  video  channel's  frame  rate  for  recording. 

SGGetFrameRate  (III— 1719) 

Retrieves  a  video  channel's  frame  rate  for  recording. 

SGSetUseScreenBuf f er  (III — 1811) 

Controls  whether  a  video  channel  uses  an  offscreen  buffer. 

SGGetUseScreenBuf fer  (III — 1 740) 

Determines  whether  a  video  channel  is  allowed  to  use  an  offscreen  buffer. 
SGA1  i  gnChannel  Rect  (III — 1 684) 

Determines  whether  or  not  a  channel  prefers  to  draw  at  a  particular  screen 
location. 
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Configuration  Functions  for  Sound  Channel  Components 

Sound  channel  components  provide  a  number  of  functions  that  allow  sequence 
grabber  components  to  configure  the  component's  sound  channel.  The  sequence 
grabber  component  uses  these  functions  only  with  sound  channels. 

SGSetChannel  Vol  ume  (III— 1783)  allows  the  sequence  grabber  component  to  control  a 
channel's  sound  volume.  The  sequence  grabber  component  uses 
SGGetChannel  Vol  ume  (III— 1710)  to  determine  a  channel's  volume. 
SGSetSoundlnputDrl  ver  (III— 1802)  specifies  a  channel's  sound  input  device.  The 
sequence  grabber  component  can  determine  a  channel's  sound  input  device  by 
calling  SGGet  Sound  Input  Dr  i  ver  (III— 1732).  If  an  application  changes  any  attributes  of 
the  sound  input  device,  the  sequence  grabber  component  notifies  your  sound 
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component  by  calling  SGSoundlnputDri  verChanged  (III— 1817). 

The  sequence  grabber  component  can  control  the  amount  of  sound  data  your 
channel  works  with  at  one  time  by  calling  SGSetSoundRecordChunkSi  ze  (III— 1805). 
The  sequence  grabber  component  can  determine  this  value  by  calling 
SGGetSoundRecordChunkSi  ze  (III— 1734).  The  sequence  grabber  component  controls 
the  rate  at  which  your  sound  channel  samples  the  input  data  by  calling 
SGSetSoundlnputRate  (III— 1804).  The  sequence  grabber  component  can  determine 
the  sample  rate  by  calling  SGGet  Sound  Input  Rate  (III— 1734).  The  sequence  grabber  can 
control  other  sound  input  parameters  by  using  SGSetSoundlnputParameters 
(III — 1803)  and  SGGetSoundlnputParameters. 


Functions 

SGSetChannel  Vol  ume  (III — 1 783) 

Sets  a  channel's  sound  volume. 

SGGetChannel  Vol  ume  (III — 1 710) 

Determines  a  channel's  sound  volume  setting. 

SGSetSoundlnputDri  ver  (III — 1802) 

Assigns  a  sound  input  device  to  a  sound  channel. 

SGGetSoundlnputDri  ver  (III — 1 732) 

Determines  the  sound  input  device  currently  in  use  by  a  sound  channel 
component. 

SGSoundlnputDri  verChanged  (III — 1817) 

Notifies  the  sequence  grabber  component  whenever  you  change  the 
configuration  of  a  sound  channel's  sound  input  device. 

SGSetSoundRecordChunkSi  ze  (III — 1805) 

Controls  the  amount  of  sound  data  in  each  group  of  sound  samples  during  a 
record  operation. 

SGGetSoundRecordChunkSi  ze  (III — 1 7 34) 

Determines  the  amount  of  sound  data  the  sequence  grabber  component  works 
with  at  a  time. 

SGSetSoundlnputRate  (III — 1804) 

Sets  the  rate  at  which  the  sound  channel  obtains  its  sound  data. 
SGGetSoundlnputRate  (III — 1 7 34) 

Determines  the  rate  at  which  the  sound  channel  is  collecting  sound  data. 
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SGSet  Sound  In  put  Parameters  (III — 1803) 

Sets  various  parameters  that  relate  to  sound  recording. 

SGGet  Sound  In  put  Parameters  (III — 1 733) 

Retrieves  various  parameters  that  relate  to  sound  recording. 


Utility  Functions  for  Sequence  Grabber  Channel  Components 

Sequence  grabber  components  provide  several  utility  functions  that  your  channel 
component  can  use. 

SGAddMovi  eData  (III— 1682)  lets  you  add  data  and  sample  references  to  a  movie. 
Alternatively,  you  can  use  SGWri  teMovi  eData  (III— 1824)  to  add  data  to  a  movie,  and 
SGAddFrameReference  (III— 1681)  and  SGGetNextFrameRef  erence  to  keep  track  of 
sample  references  prior  to  creating  a  QuickTime  movie  from  recorded  data.  These 
functions  take  a  pointer  to  a  SeqGrabFramelnfo  (IV-2430)  structure  as  a  parameter. 

SGSortDevi  ceLi  st  allows  you  to  sort  entries  in  the  device  list.  SGChangedSource 
(III— 1686)  allows  you  to  tell  the  sequence  grabber  that  you  have  changed  your 
source  device. 
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Functions 

SGAddMovi  eData  (III— 1682) 

Lets  a  channel  component  add  data  to  a  movie. 

SGWri  teMovi  eData  (III — 1 824) 

Lets  a  channel  component  add  data  to  a  movie. 

SGAddFrameReference  (III — 1 681 ) 

Stores  sample  references  for  a  channel  component. 

SGGet  Next  Frame  Ref  erence  (III — 1 726) 

Lets  a  channel  component  retrieve  the  sample  references  that  were  stored  by 
calling  SGAddMovi  eData  (III— 1682)  or  SGAddFrameReference  (III— 1681). 

SGSortDevi  ceLi  st  (III — 1817) 

Sorts  a  device  list  alphabetically. 

SGChangedSource  (III — 1 686) 

Informs  the  sequence  grabber  that  a  component  is  now  using  a  different  device. 

SGAdd  Extended  Frame  Ref  erence  (III — 1 677) 

Stores  extended  sample  references  for  a  channel  component. 
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SGAddExtendedMovi  eData  (III — 1 678) 

Adds  data  to  a  movie  without  writing  data  to  a  movie  file. 

SGAddOutputDataRefToMedi  a  (III — 1 683) 

Manages  capture  sessions  that  involve  multiple  data  references. 

SGChannel  GetDataSourceName  (III — 1687) 

Returns  the  data  source  name  for  a  track. 

SGChannel  GetRequestedDataRate  (III — 1 688) 

Returns  the  current  maximum  data  rate  requested  for  a  channel. 

SGChannel  Set  Da  taSourceName  (III — 1 690) 

Sets  the  data  source  name  for  a  track. 

SGChannel  Set  Requested  Data  Rate  (III — 1691) 

Specifies  the  maximum  requested  data  rate  for  a  channel. 

SGGetAddi  ti  onal  SoundRates  (III — 1697) 

Returns  the  additional  sound  sample  rates  added  to  a  specified  sequence 
grabber  sound  channel. 

SGGet  Next  Ext  ended  Frame  Reference  (III-1725) 

Allows  a  channel  component  to  retrieve  the  sample  references  stored 
previously  by  SGAddExtendedMovi  eData  (III— 1678)  or 
SGAdd  Ext  ended  Frame  Reference  (III — 1677). 

SGGet P ref  erredPacketSi  ze  (III — 1 730) 

Returns  the  preferred  packet  size  for  the  sequence  grabber  component. 

SGGetUserVi  deoCompressorLi  st  (III — 1 740) 

Returns  the  video  compression  formats  to  be  displayed  by  the  specified 
sequence  grabber  video  channel. 

SGSetAddi  ti  onal  SoundRates  (III — 1 774) 

Specifies  a  list  of  sound  sample  rates  to  be  included  in  the  sequence  grabber's 
sound  settings  dialog  box. 

SGSetPreferredPacketSi ze  (III — 180 1) 

Sets  the  preferred  packet  size  for  the  sequence  grabber  channel  component. 

SGSetUserVi  deoCompressorLi  st  (III — 1 810) 

Specifies  the  list  of  video  compression  formats  to  be  included  in  the  sequence 
grabber's  video  settings  dialog  box. 
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SGWri  teExtendedMovi  eData  (III — 1822) 

Allows  your  channel  component  to  add  data  to  a  movie. 

Data  Structure 

SeqGrabFramelnfo  (IV-2430) 

Provides  information  about  a  frame  for  a  sequence  grabber  component  and  its 
sequence  grabber  channel  components. 


Using  Sequence  Grabber  Panels 


SUM 


Sequence  grabber  components  create  a  settings  dialog  box  that  includes  items  that 
are  managed  by  sequence  grabber  panel  components  and  sequence  grabber  channel 
components.  Sequence  grabber  panel  components  allow  sequence  grabber 
components  to  obtain  configuration  information  from  the  user  for  a  particular 
sequence  grabber  channel  component.  Applications  never  call  sequence  grabber 
panel  components  directly;  application  developers  use  panel  components  only  by 
calling  the  sequence  grabber  component. 


Managing  Your  Panel  Component 

Sequence  grabber  components  load,  configure,  and  unload  your  panel  component. 
As  part  of  this  process,  the  sequence  grabber  installs  your  panel's  dialog  items  into 
the  settings  dialog  box  and  may  open  your  component's  resource  file.  Panel 
components  provide  a  number  of  functions  that  allow  the  sequence  grabber  to 
manage  its  relationship  with  panel  components. 

After  opening  a  connection  to  your  panel  component,  the  sequence  grabber 
identifies  itself  to  your  component  by  calling  your  SGPanel  SetGrabber  (III— 1767) 
function.  The  sequence  grabber  then  tries  to  determine  whether  your  component 
can  work  with  its  associated  channel  component  by  calling  your  SGPanel  CanRun 
(III— 1759)  function.  The  sequence  grabber  calls  this  function  only  if  you  have  set  the 
channel  FI  agHasDependency  component  flag  to  1. 

Once  the  sequence  grabber  has  determined  that  your  panel  component  can  work 
with  its  channel  component,  the  sequence  grabber  may  open  your  component's 
resource  file  (unless  you  have  set  the  channel  FI  agDontOpenResFi  1  e  component  flag 
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to  1).  Once  it  has  opened  the  resource  file,  it  passes  the  file's  reference  number  to 
you  by  calling  your  SGPanel  SetResFi  1  e  (III— 1768)  function. 

Next,  the  sequence  grabber  prepares  to  add  your  component's  items  to  the  settings 
dialog  box.  The  sequence  grabber  obtains  your  item  list  by  calling  your 
SGPanel  GetDi  tl  (III— 1761)  function.  Once  it  has  installed  the  items,  it  calls  your 
SGPanel  Instal  1  (III— 1764)  function,  giving  you  an  opportunity  to  set  initial  values. 

Before  the  sequence  grabber  removes  your  items  from  the  settings  dialog  box,  it 
calls  your  SGPanel  Remove  (III— 1766)  function. 


Functions 

SGPanel  SetGrabber  (III — 1 767) 

Identifies  a  sequence  grabber  component  to  a  panel  component. 

SGPanel  CanRun  (III— 1759) 

Lets  a  sequence  grabber  component  determine  whether  a  panel  component  can 
work  with  the  current  sequence  grabber  channel  component. 

SGPanel  SetResFi  1  e  (III — 1 768) 

Lets  the  sequence  grabber  pass  a  resource  file's  reference  number. 

SGPanel  GetDi  tl  (III— 1761) 

Lets  a  sequence  grabber  component  determine  the  dialog  items  managed  by 
your  panel  component. 

SGPanel  GetTi tie  (III— 1763) 

Gets  the  displayed  title  of  a  sequence  grabber  panel. 

SGPanel  Install  (III— 1764) 

Installs  added  items  in  a  sequence  grabber  settings  dialog  box  before  the  dialog 
box  is  displayed  to  the  user. 

SGPanel  Remove  (III — 1 766) 

Removes  a  panel  from  the  sequence  grabber  settings  dialog  box. 


Processing  Your  Panel's  Events 

When  your  panel  component  is  loaded  into  the  settings  dialog  box  and  active,  you 
may  receive  and  process  dialog  events  and  mouse  clicks. 
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Your  component's  SGPanel  Event  (III— 1760)  function  acts  like  a  modal-dialog  filter 
function,  allowing  you  to  process  individual  dialog  events.  The  sequence  grabber 
calls  your  SGPanel  Item  (III— 1765)  function  whenever  the  user  clicks  a  dialog  item. 

Whenever  the  user  clicks  the  OK  button,  the  sequence  grabber  calls  your 

SG  Panel  Validatelnput  (III— 1770)  function.  Your  panel  component  may  then  validate 

the  user's  settings. 


Functions 

SGPanel  Item  (III— 1765) 

Receives  and  processes  mouse  clicks  in  the  sequence  grabber  settings  dialog 
box. 

SGPanel  Event  (III— 1760) 

Lets  a  component  receive  and  process  dialog  events. 

SGPanel  SetEventFi  1  ter  (III — 1767) 

Sets  the  event  filter  callback  for  a  sequence  grabber  panel  component. 

SGPanel  Validatelnput  (III — 1 770) 

Validates  the  contents  of  the  user  dialog  box  for  a  sequence  grabber  component. 
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Managing  Your  Panel's  Settings 

Sequence  grabber  components  store  their  configuration  information  in  Movie 
Toolbox  user  data  items.  This  configuration  information  includes  settings  for  each 
of  the  channels  used  by  the  sequence  grabber.  Because  your  panel  component 
configures  sequence  grabber  channels,  your  panel  component  is  responsible  for 
creating  and  formatting  the  contents  of  its  user  data  items.  The  sequence  grabber 
component  calls  your  component  whenever  it  wants  to  retrieve  these  settings.  The 
sequence  grabber  may  also  use  previously  stored  settings  to  restore  your  panel's 
settings. 

The  sequence  grabber  calls  your  SGPanel  GetSetti  ngs  (III— 1762)  function  in  order  to 
retrieve  your  panel's  current  settings.  The  sequence  grabber  uses  your 
SGPanel  SetSetti  ngs  (III— 1769)  function  to  restore  those  settings  to  some  previous 
values. 


Functions 


SGPanel  GetSetti  ngs  (III — 1 762) 

Retrieves  a  panel's  current  settings  for  a  sequence  grabber  component. 
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SGPanel SetSetti ngs  (III — 1 769) 

Restores  a  panel's  current  settings  for  a  sequence  grabber  component. 


Working  With  Data  Handlers 


Data  handler  components  allow  QuickTime  to  retrieve  time-based  data  from 
external  storage  devices  and,  in  some  cases,  store  time-based  data  on  those  devices. 
In  most  cases,  you  do  not  need  to  create  a  data  handler  or  use  one  directly,  because 
QuickTime  takes  care  of  data  storage  and  retrieval  for  you  through  its  built-in 
media  handlers.  However,  you  may  need  to  create  a  data  handler  component  to 
read  or  write  to  a  non-Macintosh  storage  medi  um. 


Selecting  a  Data  Handler 

So  client  programs  can  choose  the  best  data  handler  component  for  a  data  reference, 
several  functions  allow  applications  to  interrogate  a  data  handler's  capabilities. 

DataHGetVol  umeLi  st  (1-207)  allows  an  application  to  obtain  a  list  of  the  volumes  your 
data  handler  can  support.  DataHCanUseDataRef  (1-175)  allows  your  data  handler  to 
examine  a  specific  data  reference  and  indicate  its  ability  to  work  with  the  associated 
container.  DataHGetDevi  celndex  (1-193)  allows  applications  to  determine  whether 
different  data  references  identify  containers  that  reside  on  the  same  device. 


Functions 


DataHGetVol  umeLi  st  (1-207) 

Returns  a  list  of  the  volumes  your  component  can  access,  along  with  flags 
indicating  your  component's  capabilities  for  each  volume. 

DataHCanUseDataRef  (1-175) 

Reports  whether  a  data  handler  can  access  the  data  associated  with  a  specified 
data  reference. 

DataHGetDevi  celndex  (1-193) 

Returns  a  value  that  identifies  the  device  on  which  a  data  reference  resides. 


V-2838 


Inside  QuickTime:  Programming  Summary 


Identifying  Data  References 


All  data  handler  components  use  data  references  to  identify  and  locate  a  movie's 
container.  Different  types  of  containers  may  require  different  types  of  data 
references.  Client  programs  can  correlate  data  references  with  data  handlers  by 
matching  the  component's  subtype  value  with  the  data  reference  type.  The  subtype 
value  indicates  the  type  of  data  reference  the  component  supports.  All  data 
handlers  with  the  same  subtype  value  must  support  the  same  data  reference  type. 

DataHSetDataRef  (1-224)  and  DataHGetDataRef  (1-189)  allow  applications  to  assign 
your  data  handler's  current  data  reference.  DataHCompareDataRef  (1-178)  asks  your 
component  to  compare  a  data  reference  against  the  current  data  reference  and 
indicate  whether  the  references  are  equivalent  (that  is,  refer  to  the  same  container). 
DataHResol  veDataRef  (1-218)  permits  your  component  to  locate  a  data  reference's 
container. 
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Functions 

DataHSetDataRef  (I — 224) 

Assigns  a  data  reference  to  your  data  handler  component. 

DataHGetDataRef  (1-189) 

Retrieves  your  component's  current  data  reference. 

DataHCompareDataRef  (1-178) 

Compares  a  supplied  data  reference  against  its  current  data  reference  and 
returns  a  Bool  ean  value  indicating  whether  the  data  references  are  equivalent 
(that  is,  the  two  data  references  identify  the  same  container). 

DataHResol  veDataRef  (1-218) 

Locates  the  container  associated  with  a  given  data  reference. 


Reading  Movie  Data 

Data  handler  components  support  several  functions  that  help  applications  and 
other  components  read  movie  data. 

DataHGetData  (1-186)  provides  a  fully  synchronous  read  operation,  while 
DataHSchedul  eData  (1-220)  is  asynchronous.  By  calling  DataHFi  ni  shData  (1-182), 
applications  can  force  your  component  to  process  queued  read  requests. 
Applications  may  call  DataHGetSchedul  eAheadTi  me  (1-206)  in  order  to  determine  how 
far  in  advance  your  component  prefers  to  get  read  requests.  Before  any  application 
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can  read  data  from  a  data  reference,  it  must  open  read  access  to  that  reference  by 
calling  DataHOpenForRead  (1-209).  DataHCl  oseForRead  closes  that  read  access  path. 


Functions 

DataHGetData  (1-186) 

Reads  data  from  its  current  data  reference,  which  is  a  synchronous  read 
operation. 

DataHSchedul  eData  (1-220) 

Reads  data  from  its  current  data  reference,  which  can  be  a  synchronous  read 
operation  or  an  asynchronous  read  operation. 

DataHFi ni shData  (1-182) 

Completes  or  cancels  one  or  more  queued  read  requests. 

DataHGetScheduleAheadTime  (1-206) 

Reports  how  far  in  advance  it  prefers  clients  to  issue  read  requests. 

DataHOpenForRead  (1-209) 

Opens  a  data  handler's  current  data  reference  for  read-only  access. 

DataHCl  oseForRead  (1-176) 

Closes  read-only  access  to  its  data  reference. 


Writing  Movie  Data 

As  they  do  with  reading  movie  data,  data  handlers  provide  facilities  for  writing 
both  synchronous  and  asynchronous  data. 

DataHPutData  (1-216)  is  a  simple  synchronous  interface  that  allows  applications  to 
append  data  to  the  end  of  a  container.  DataHWrite  (1-232)  is  a  more  capable, 
asynchronous  write  function  that  is  suitable  for  movie  capture  operations.  The 
component  calls  the  application's  data-handler  completion  function  when  you  are 
done  with  the  write  request. 

DataHCreateFi  1  e  (1-180)  asks  the  component  to  create  a  new  container. 
DataHSetFileSize  (1-227)  and  DataHGetFi  1  eSi  ze  (1-194)  work  with  a  container's  size, 
in  bytes.  DataHGetFreeSpace  (1-198)  allows  applications  to  determine  when  to  make 
a  container  larger.  DataHPreextend  (1-214)  asks  your  component  to  make  a  container 
larger. 

Applications  may  call  DataHGetPreferredBlockSize  (1-204)  in  order  to  determine 
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how  best  to  interact  with  your  data  handler.  Before  writing  data  to  a  data  reference, 
applications  must  call  DataHOpenForWri  te  (1-210)  to  open  a  write  path  to  the 
container.  DataHCl  oseForWri  te  (1-177)  closes  that  write  path. 


Functions 

DataHPutData  (1-216) 

Writes  data  to  a  component's  current  data  reference. 

DataHWri  te  (1-232) 

Writes  data  to  its  current  data  reference. 

DataHCreateFi 1 e  (1-180) 

Creates  a  new  container  that  meets  the  specifications  of  the  current  data 
reference. 

DataHSetFileSize  (1-227) 

Sets  the  size,  in  bytes,  of  the  current  data  reference. 

DataHGetFi  1  eSi  ze  (1-194) 

Returns  the  size,  in  bytes,  of  the  current  data  reference. 

DataHGetFreeSpace  (1-198) 

Reports  the  number  of  bytes  available  on  the  device  that  contains  the  current 
data  reference. 

DataHPreextend  (1-214) 

Allocates  new  space  for  the  current  data  reference,  enlarging  the  container. 
DataHGetPreferredBI  ockSi  ze  (1-204) 

Reports  the  block  size  that  it  prefers  to  use  when  accessing  the  current  data 
reference. 

DataHOpenForWri  te  (1-210) 

Opens  your  component's  current  data  reference  for  write-only  access. 

DataHCl  oseForWri  te  (1-177) 

Closes  write-only  access  to  its  data  reference. 


SUM 


Managing  Data  Handler  Components 

Data  handler  components  provide  a  number  of  functions  that  applications  can  use 
to  manage  their  connections  to  them. 
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The  most  important  among  these  is  DataHTask  (1-231),  which  provides  processor 
time  to  the  handler.  Applications  should  call  this  function  often  so  that  the  handler 
has  enough  time  to  do  its  work.  Applications  may  call  DataHPlaybackHints  (1-211) 
in  order  to  provide  the  handler  with  some  guidelines  about  how  those  applications 
plan  to  use  the  current  data  reference.  DataHFl  ushData  (1-184)  and  DataHFl  ushCache 
(1-184)  allow  applications  to  influence  how  your  component  manages  its  stored 
data. 


Functions 

DataHTask  (1-231) 

Cedes  processor  time  to  your  data  handler. 

DataHPlaybackHints  (1-211) 

Provides  additional  information  to  your  component  that  you  may  use  to 
optimize  the  operation  of  your  data  handler. 

DataHFl  ushData  (1-184) 

Forces  any  data  in  your  component's  write  buffers  to  be  written  to  the  device 
that  contains  the  current  data  reference. 

DataHFl  ushCache  (1-184) 

Discards  the  contents  of  any  cached  read  buffers. 


Using  Video  Digitizers 


Video  digitizer  components  convert  a  video  input  into  a  digitized  color  image  that 
is  compatible  with  the  graphics  system  of  the  computer. 


Video  Digitizer  Data  Structures 

Video  digitizer  components  and  applications  that  use  video  digitizer  components 
communicate  through  two  primary  data  structures. 

The  contents  of  the  Digi  tizerlnfo  (IV-2234)  structure  fully  define  the  capabilities 
and  current  status  of  the  video  digitizer  component.  You  specify  video  output 
buffers  in  a  Vdi  gBufferRecLi  st  (IV-2499)  structure.  Note  that  all  the  output  buffers 
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must  be  the  same  size  and  must  accommodate  output  rectangles  of  the  same 
dimensions. 

Data  Structures 

Di  gi  ti  zerlnfo  (TV-2234) 

Contains  information  about  the  capabilities  and  current  status  of  a  video 
digitizer  component. 

Vdi  gBufferRecLi  st  (IV — 2499) 

Contains  a  list  of  Vdi  gBufferRec  (IV-2498)  structures. 


SUM 


Getting  Information  About  Video  Digitizer  Components 

Two  functions  allow  applications  to  obtain  information  about  the  capabilities  and 
current  state  of  video  digitizer  components. 

You  can  use  VDGetDi  gi  ti  zerlnfo  (III— 1998)  in  your  application  to  retrieve 
information  about  the  capabilities  of  a  video  digitizer  component.  You  can  use 
VDGetCurrentFl  ags  (III— 1996)  to  obtain  current  status  information  from  a  video 
digitizer  component. 


Functions 

VDGetDi  gi  ti  zerlnfo  (III — 1 998) 

Returns  capability  and  status  information  about  a  specified  video  digitizer 
component. 

VDGetCurrentFl  ags  (III — 1 996) 

Returns  status  information  about  a  specified  video  digitizer  component. 


Setting  Source  Characteristics 

Several  video  digitizer  component  functions  allow  applications  to  set  the  spatial 
characteristics  of  the  source  video  signal.  You  can  use  these  functions  in  your 
application  to  set  and  retrieve  information  about  the  maximum  source  rectangle, 
the  active  source  rectangle,  the  vertical  blanking  rectangle,  and  the  digitizer 
rectangle. 

You  can  use  VDGetMaxSrcRect  (III— 2012)  in  your  application  to  get  the  size  and 
location  of  the  maximum  source  rectangle.  Similarly,  VDGetActi  veSrcRect  (III— 1989) 
allows  you  to  get  this  information  about  the  active  source  rectangle,  and 
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VDGetVBl  ankRect  (III— 2021)  enables  you  to  obtain  information  about  the  vertical 
blanking  rectangle.  You  can  use  VDSetDi  gi  ti  zerRect  (III— 2038)  to  set  the  size  and 
location  of  the  digitizer  rectangle.  VDGetDi  gi  ti  zerRect  (III — 1999)  lets  you  retrieve 
the  size  and  location  of  this  rectangle. 


Functions 

VDGetMaxSrcRect  (III— 2012) 

Returns  the  maximum  source  rectangle. 

VDGetActi  veSrcRect  (III — 1 989) 

Obtains  size  and  location  information  for  the  active  source  rectangle  used  by  a 
video  digitizer  component. 

VDGetVBl  ankRect  (III— 2021) 

Returns  the  vertical  blanking  rectangle. 

VDSetDi  gi  ti  zerRect  (III — 2038) 

Sets  the  current  video  digitizer  rectangle. 

VDGetDi  gi  ti  zerRect  (III — 1 999) 

Returns  the  current  digitizer  rectangle. 


Selecting  an  Input  Source 

Several  video  digitizer  component  functions  allow  applications  to  select  an  input 
video  source. 

Applications  can  use  VDGetNumberOflnputs  (III— 2013)  to  determine  the  number  of 
video  inputs  supported  by  the  digitizer  component.  VDGetlnputFormat  (III— 2005) 
function  allows  applications  to  find  out  the  video  format  (composite,  s-video,  or 
component)  employed  by  a  specified  input.  You  can  use  VDSetlnput  (III-2042)  in 
your  application  to  specify  the  input  to  be  used  by  the  digitizer  component. 
VDGetlnput  (III— 2003)  returns  the  currently  selected  input.  VDSetlnputStandard 
(III— 2045)  allows  you  to  specify  the  video  signaling  standard  to  be  used  by  the  video 
digitizer  component. 


Functions 


VDGetNumberOflnputs  (III — 2013) 

Returns  the  number  of  input  video  sources  that  a  video  digitizer  component 
supports. 
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VDGetlnputFormat  (III — 2005) 

Determines  the  format  of  the  video  signal  provided  by  a  specified  video  input 
source. 

VDSetlnput  (III— 2042) 

Selects  the  input  video  source  for  a  video  digitizer  component. 

VDGetlnput  (III— 2003) 

Returns  data  that  identifies  the  currently  active  input  video  source. 

VDSetlnputStandard  (III — 2045) 

Specifies  the  input  signaling  standard  to  digitize. 
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Setting  Video  Destinations 

Video  digitizer  components  provide  several  functions  that  allow  applications  to 
specify  the  destination  for  the  digitized  video  stream  produced  by  the  digitizer 
component.  Applications  have  two  options  for  specifying  the  destination  for  the 
video  data  stream.  The  first  option  requires  that  the  video  be  digitized  as  RGB  pixels 
and  placed  into  a  destination  pixel  map.  This  option  allows  the  video  to  be  placed 
either  onscreen  or  offscreen,  depending  upon  the  placement  of  the  pixel  map.  The 
second  option  uses  a  global  boundary  rectangle  to  define  the  destination  for  the 
video.  This  option  is  useful  only  with  digitizers  that  support  hardware  DMA. 

You  can  use  VDSetPl  ayThruDesti  nati  on  (III— 2048)  in  your  application  to  set  the 
characteristics  for  video  digitized  as  RGB  pixels  and  placed  into  a  destination  pixel 
map.  VDPref  1  i  ghtDesti  nati  on  (III— 2026)  lets  you  determine  the  capabilities  of  the 
digitizer  in  your  application.  All  video  digitizer  components  must  support  this 
option.  VDGetPl  ayThruDesti  nati  on  (III— 2014)  lets  you  get  data  about  the  current 
video  destination. 

You  can  use  VDSetPl  ayThruGl  obal  Rect  (III— 2049)  in  your  application  to  set  the 
characteristics  for  a  global  boundary  rectangle  defining  the  destination  for  the 
video.  You  can  use  VDPref  1  i  ghtGl  obal  Rect  (III— 2028)  in  your  application  to 
determine  the  capabilities  of  the  digitizer.  Not  all  video  digitizer  components 
support  this  option.  VDGetMaxAuxBuffer  (III— 201 1 )  returns  information  about  a  buffer 
that  may  be  located  on  some  special  hardware. 


Functions 


VDSetPl  ayThruDesti  nati  on  (III — 2048) 

Establishes  the  destination  settings  for  a  video  digitizer  component. 
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VDPreflightDesti  nation  (III — 2026) 

Verifies  that  a  video  digitizer  component  can  support  a  set  of  destination 
settings  intended  for  use  with  VDSetPl  ayThruDesti  nati  on  (III— 2048). 

VDGetPl  ayThruDesti  nati  on  (III — 20 14) 

Obtains  information  about  the  current  video  destination. 

VDSetPl  ayThruGl  obal  Rect  (III — 2049) 

Establishes  the  destination  settings  for  a  video  digitizer  component  that  is  to 
digitize  into  a  global  rectangle. 

VDPref  1  i  ghtGl  obal  Rect  (III — 2028) 

Verifies  that  a  video  digitizer  component  can  support  a  set  of  destination 
settings  intended  for  use  with  VDSetPl  ayThruGl  obal  Rect  (III— 2049). 

VDGetMaxAuxBuffer  (III — 2 011) 

Obtains  access  to  buffers  that  are  located  on  special  hardware. 


Controlling  Compressed  Source  Devices 

Some  video  digitizer  components  may  provide  functions  that  allow  applications  to 
work  with  digitizing  devices  that  can  provide  compressed  image  data  directly.  Such 
devices  allow  applications  to  retrieve  compressed  image  data  without  using  the 
Image  Compression  Manager.  However,  in  order  to  display  images  from  the 
compressed  data  stream,  there  must  be  an  appropriate  decompressor  component 
available  to  decompress  the  image  data.  Video  digitizers  that  can  support 
compressed  source  devices  set  the  di  gi  OutDoesCompress  flag  to  1  in  their  capability 
flags. 

All  of  these  digitizing  functions  support  only  asynchronous  digitization.  That  is,  the 
video  digitizer  works  independently  to  digitize  each  frame.  Applications  are  free  to 
perform  other  work  while  the  digitizer  works  on  each  frame.  The  video  digitizer 
component  manages  its  own  buffer  pool  for  use  with  these  functions.  In  this  respect, 
these  functions  differ  from  the  other  video  digitizer  functions  that  support 
asynchronous  digitization. 

Applications  can  use  VDGetCompressionTypes  (III— 1994)  to  determine  the 
image-compression  capabilities  of  a  video  digitizer.  VDSetCompressi  on  (III— 2034) 
allows  applications  to  set  some  parameters  that  govern  image  compression. 

Applications  control  digitization  by  calling  VDCompressOneFrameAsync  (III— 1988), 
which  instructs  the  video  digitizer  to  create  one  frame  of  compressed  image  data. 
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Functions 


VDCompressDone  (III— 1986)  returns  that  frame.  When  an  application  is  done  with  a 
frame,  it  calls  VDRel  easeCompressBuffer  (III— 2030)  to  free  the  buffer.  An  application 
can  force  the  digitizer  to  place  a  key  frame  into  the  sequence  by  calling 
VDResetCompressSequence  (III— 2030).  Applications  can  turn  compression  on  and  off 
by  calling  VDSetCompressi  onOnOff  (III— 2035). 

Applications  can  obtain  the  digitizer's  image  description  structure  by  calling 
VDGetlmageDescri  pti  on  (III— 2002).  Applications  can  set  the  digitizer's  time  base  by 
calling  VDSetTimeBase  (III— 2054). 


VDGetCompressi  onTypes  (III — 1 994) 

Determines  the  image-compression  capabilities  of  the  video  digitizer. 
VDGetCompressi  onT i me  (III — 1 993) 

Confirms  or  quantifies  a  video  digitizer's  compression  settings. 

VDSetCompressi  on  (III — 2034) 

Specifies  certain  compression  parameters. 

VDCompressOneFrameAsync  (III — 1 988) 

Instructs  the  video  digitizer  to  digitize  and  compress  a  single  frame  of  image 
data. 

VDCompressDone  (III — 1 986) 

Determines  whether  the  video  digitizer  has  finished  digitizing  and 
compressing  a  frame  of  image  data. 

VDRel  easeCompressBuffer  (III — 2030) 

Frees  abutter  received  from  VDCompressDone  (III— 1986). 

VDResetCompressSequence  (III — 2030) 

Forces  the  video  digitizer  to  insert  a  key  frame  into  a  temporally  compressed 
image  sequence. 

VDSetCompressi  onOnOff  (III — 2035) 

Allows  an  application  to  start  and  stop  compression  by  video  digitizers  that  can 
deliver  either  compressed  or  uncompressed  image  data. 

VDGetlmageDescri  pti  on  (III — 2002) 

Retrieves  an  ImageDescri  pti  on  (IV-2285)  structure  from  a  video  digitizer. 
VDSetTimeBase  (ID-2054) 

Establishes  the  video  digitizer's  time  coordinate  system. 
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VDSetDataRate  (III— 2037) 

Instructs  your  video  digitizer  component  to  limit  the  rate  at  which  it  delivers 
compressed,  digitized  video  data. 

VDGetSoundlnputSource  (III — 20 19) 

Instructs  your  video  digitizer  component  to  return  the  sound  input  source 
associated  with  a  particular  video  input. 


Controlling  Digitization 

Several  video  digitizer  component  functions  allow  applications  to  control  video 
digitization.  Video  digitizer  components  allow  applications  to  start  and  stop  the 
digitizing  process.  Your  application  can  request  continuous  digitization  or 
single-frame  digitization.  When  a  digitizer  component  is  operating  continuously,  it 
automatically  places  successive  frames  of  digitized  video  into  the  specified 
destination.  When  a  digitizer  component  works  with  a  single  frame  at  a  time,  the 
application  and  other  software,  such  as  an  image  compressor  component,  control 
the  speed  at  which  the  digitized  video  is  processed. 

You  can  use  VDSetPl  ayThruOnOff  (III— 2050)  in  your  application  to  enable  or  disable 
digitization.  When  digitization  is  enabled,  the  video  digitizer  component  places 
digitized  video  frame  into  the  specified  destination  continuously.  The  application 
stops  the  digitizer  by  disabling  digitization.  This  function  can  be  used  with  both 
destination  options.  Alternatively,  your  application  can  control  digitization  on  a 
frame-by-frame  basis.  VDGrabOneFrame  (III— 2024)  and  VDGrabOneFrameAsync  (III— 2025) 
digitize  a  single  video  frame.  VDDone  (III— 1988)  helps  you  to  determine  when 
VDGrabOneFrameAsync  (III— 2025)  is  finished  with  a  video  frame.  Your  application  can 
define  the  buffers  for  use  with  asynchronous  digitization  by  calling  VDSetupBuffers 
(III— 2055).  Free  the  buffers  by  calling  VDRel  easeAsyncBuf  f  ers  (III— 2029). 
VDSetFrameRate  allows  applications  to  control  the  digitizer's  frame  rate. 
VDGetDataRate  (III— 1997)  returns  the  digitizer's  current  data  rate. 


Functions 

VDSetPl  ayThruOnOff  (III— 2050) 

Controls  continuous  digitization. 

VDGrabOneFrame  (III — 2024) 

Instructs  the  video  digitizer  component  to  digitize  a  single  frame  of  source 
video. 
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VDGrabOneFrameAsync  (III — 2025) 

Instructs  the  video  digitizer  component  to  start  to  digitize  asynchronously  a 
single  frame  of  source  video. 

VDDone  (III— 1988) 

Determines  if  VDGrabOneFrameAsync  (III— 2025)  is  finished  with  a  specific  output 
buffer. 

VDSetupBuf fers  (III— 2055) 

Defines  output  buffers  for  use  with  asynchronous  grabs. 

VDRel  easeAsyncBuf  fers  (III — 2029) 

Releases  the  buffers  that  were  allocated  with  VDSetupBuf  fers  (III— 2055). 
VDSetFrameRate  (III — 2041) 

Indicates  an  application's  desired  frame  rate  to  the  video  digitizer. 
VDGetDataRate  (III— 1997) 

Retrieves  information  that  describes  the  performance  capabilities  of  a  video 
digitizer. 

VDSetPreferredPacketSi ze  (III — 2052) 

Sets  the  preferred  packet  size  for  video  digitizing. 

VDGetT i meCode  (III— 2020) 

Instructs  your  video  digitizer  component  to  return  timecode  information  for 
the  incoming  video  signal. 
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Controlling  Color 

Video  digitizer  components  support  color  digitization.  Therefore,  these 
components  provide  several  functions  that  allow  applications  to  control  the  color 
digitization  process. 

You  can  useVDSetlnputColorSpaceMode  (III— 2043)  in  your  application  to  enable  and 
disable  color  digitization;  you  can  use  VDGetlnputColorSpaceMode  (III— 2004)  to 
determine  whether  color  digitization  is  enabled.  VDUseThi  sCLUT  (III— 2057)  allows 
you  to  specify  a  color  lookup  table  to  be  used  by  the  video  digitizer  component.  In 
cases  where  the  component  cannot  accommodate  a  particular  lookup  table,  your 
application  canuseVDGetCLUTInUse  (III— 1992)  to  retrieve  the  color  lookup  table  used 
by  the  digitizer  component.  Your  application  can  determine  a  digitizer's  supported 
pixel  depths  by  calling  VDGetDMADepths  (III— 1999). 
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Functions 


VDSetlnputColorSpaceMode  (III — 2043) 

Chooses  between  color  and  grayscale  digitized  video. 

VDGetlnputCol  orSpaceMode  (III — 2004) 

Determines  whether  a  digitizer  is  operating  in  color  or  grayscale  mode. 

VDUseThi sCLUT  (III— 2057) 

Specifies  the  lookup  table  for  color  digitization. 

VDGetCLUTInUse  (III— 1992) 

Obtains  the  color  lookup  table  used  by  a  video  digitizer  component. 
VDGetDMADepths  (III— 1999) 

Determines  which  pixel  depths  a  digitizer  supports. 


Controlling  Analog  Video 

Some  video  digitizer  components  may  provide  functions  that  allow  applications  to 
control  the  characteristics  of  the  input  analog  video  signal. 

VDGetVi  deoDefaul  ts  (III— 2022)  returns  the  suggested  default  values  for  the  analog 
video  parameters  that  can  be  affected  by  functions  described  below.  You  can  use 
VDSetlnputGammaVal  ue  (III-2044)  and  VDGetlnputGammaVal  ue  to  allow  your 
application  to  set  particular  gamma  values.  The  VDSetBl  ackLevel Val  ue  (III— 2031), 
VDGetBl  ackLevel  Value,  VDSetWhi  te  Level  Value  (HI-2055),  and  VDGetWhi  te  Level  Value 
functions  allow  applications  to  work  with  black  levels  and  white  levels  in  the  source 
video.  VDSetContrast  (III — 2036),  VDGetContrast  (III — 1995),  VDSetSharpness  (III — 2053), 
and  VDGetSharpness  (III— 2018)  allow  applications  to  work  with  contrast  and 
sharpness  values  in  the  source  video.  VDGetBri  ghtness  (III— 1991)  and 
VDSetBrightness  (III— 2032)  allow  applications  to  work  with  the  image  brightness 
setting.  VDSetHue  (III— 2041),  VDGetHue  (III-2002),  VDSetSaturati  on  (III— 2053),  and 
VDGetSaturation  (III— 2017)  allow  applications  to  work  with  hue  and  saturation 
settings  in  the  source  video. 


Functions 

VDGetVi  deoDefaul  ts  (III— 2022) 

Returns  the  recommended  values  for  many  of  the  analog  video  parameters  that 
may  be  set  by  applications. 

VDSetlnputGammaVal  ue  (III — 2044) 

Sets  the  gamma  values. 
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VDGetlnputGammaVal  lie  (III — 2006) 

Returns  the  current  gamma  values. 

VDSetBl  ackLevel  Value  (III — 2031) 

Sets  the  current  black  level  value. 

VDGetBl  ackLevel  Value  (III — 1 990) 

Returns  the  current  black  level  value. 

VDSetWhi  teLevel  Value  (III — 2055) 

Sets  the  white  level  value. 

VDGetWhi  teLevel  Value  (III-2024) 

Returns  the  current  white  level  value. 

VDSetContrast  (III — 2036) 

Sets  the  current  contrast  value. 

VDGetContrast  (III — 1 995) 

Returns  the  current  contrast  value. 

VDSetSharpness  (III — 2053) 

Sets  the  sharpness  value. 

VDGetSharpness  (III — 2 018) 

Returns  the  current  sharpness  value. 

VDGetBri  ghtness  (III — 19911 

Returns  the  current  brightness  value. 

VDSetBri  ghtness  (III — 2032) 

Sets  the  current  brightness  value. 

VDSetHue  (III— 2041 ) 

Sets  the  current  hue  value. 

VDGetHue  (III— 2002) 

Returns  the  current  hue  value. 

VDSetSaturati  on  (III — 2053) 

Sets  the  saturation  value. 

VDGetSaturati  on  (III — 20 17) 

Returns  the  current  saturation  value. 
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Selectively  Displaying  Video 

Video  digitizer  components  may  support  one  of  three  methods  of  selectively 
displaying  video:  key  colors,  alpha  channels,  and  blend  masks. 

Your  applications  can  use  VDSetKeyCol  or  (III— 2046),  VDAddKeyCol  or  (III— 1985),  and 
VDSetKeyCol  orRange  (III— 2046)  to  set  one  or  more  key  colors  for  a  video  digitizer 
component.  VDGetKeyCol  or  (III— 2008),  VDGetNextKeyCol  or  (III— 2013),  and 
VDGetKeyCol  orRange  (III— 2009)  allow  your  application  to  retrieve  information  about 
the  currently  active  key  colors.  Your  applications  can  use  VDGetMaskandValue 
(III— 2009)  to  determine  the  appropriate  mask  value  for  a  desired  blend  level. 
VDSetMasterBlendLevel  (III-2047)  allows  applications  to  set  a  blend  level  that 
applies  to  the  entire  source  video  image.  VDGetMaskPixMap  (III— 201 1)  allows 
applications  to  retrieve  the  pixel  map  that  defines  the  blend  mask. 


Functions 

VDSetKeyCol  or  (III— 2046) 

Sets  the  key  color  for  video  digitizing. 

VDAddKeyCol  or  (III— 1985) 

Adds  a  key  color  to  a  component's  list  of  active  key  colors. 

VDSetKeyCol  orRange  (III — 2046) 

Defines  a  key  color  range  for  video  digitizing. 

VDGetKeyCol  or  (III— 2008) 

Obtains  the  index  value  of  the  active  key  color. 

VDGetNextKeyCol  or  (III— 2013) 

Obtains  the  index  value  of  the  active  key  colors  in  cases  where  the  digitizer 
component  supports  multiple  key  colors. 

VDGetKeyCol  orRange  (III — 2009) 

Obtains  the  currently  defined  key  color  range. 

VDGetMaskandVal  ue  (III — 2009) 

Obtains  the  appropriate  alpha  channel  or  blend  mask  value  for  a  desired  level 
of  video  blending. 

VDSetMasterBlendLevel  (III — 2047) 

Sets  the  blend  level  value  for  the  input  video  signal. 

VDGetMaskPixMap  (III— 2011) 

Retrieves  the  pixel  map  data  for  a  component's  blend  mask. 
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Video  Clipping 


Some  video  digitizer  components  can  clip  the  output  video  image  based  on  an 
arbitrary  clipping  region.  The  functions  that  manipulate  clipping  and  clipping  state 
operate  on  a  clipping  region  in  addition  to  the  one  specified  by  the  mask  passed  by 
VDSetPl  ayThruDesti  nati  on  (III— 2048)  and  VDSetUpBuff  ers.  To  determine  the  final 
clipping  regions,  intersect  these  two  clippings. 

Applications  can  use  VDSetCl  i  pState  (III— 2033)  and  VDGetCl  i  pState  (III— 1991)  to 
enable  and  disable  clipping,  and  to  determine  whether  clipping  is  enabled. 
Applications  can  use  VDSetCl  i  pRgn  (III— 2032)  and  VDC1  earCl  i  pRgn  (III— 1986)  to 
manipulate  the  clipping  region.  Applications  can  use  these  functions  only  during  an 
active  grab  sequence.  Applications  set  the  initial  clipping  settings  by  calling  either 
VDSetPl  ayThruDesti  nati  on  (III — 2048)  or  VDSetPl  ayThruGl  obal  Rect. 
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Functions 

VDSetCl  i  pState  (III— 2033) 

Controls  whether  clipping  is  enabled. 

VDGetCl  i  pState  (III— 1991) 

Determines  whether  clipping  is  enabled. 

VDSetCl  i  pRgn  (III— 2032) 

Defines  a  clipping  region  for  a  video  digitizer. 

VDC1  earCl  i pRgn  (III — 1 986) 

Disables  all  or  part  of  a  clipping  region  that  was  previously  set  with 
VDSetCl  i  pRgn  (III — 2032). 

VDSetPl  ayThruDesti  nati  on  (III — 2048) 

Establishes  the  destination  settings  for  a  video  digitizer  component. 

VDSetPl  ayThruGl  obal  Rect  (III — 2049) 

Establishes  the  destination  settings  for  a  video  digitizer  component  that  is  to 
digitize  into  a  global  rectangle. 

See  Also 

See  "Setting  Video  Destinations"  (V-2845). 


Video  Digitizer  Utilities 

Certain  utility  functions  may  be  supported  by  some  video  digitizer  components. 
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VDSetPLLFi  1  terType  (III— 205 1 )  and  VDGetPLLFi  1  terType  allow  applications  to  control 
which  phase-locked  loop  (PLL)  is  used  by  a  video  digitizer  component  that 
supports  multiple  PLLs.  VDSetFi  el  dPreference  (III— 2040)  and  VDGetFi  el  dPreference 
allow  applications  to  control  which  field  is  used  for  some  vertical  scaling 
operations.  VDSetDi gl  ti zerllserlnterrupt  (III— 2039)  allows  applications  to  install 
custom  interrupt  functions  that  are  called  by  the  video  digitizer  component. 
VDGetSoundlnputDri  ver  (III— 2019)  allows  an  application  to  retrieve  information 
about  a  digitizer's  sound  input  driver.  VDGet  Preferred!  i  meScal  e  (III— 2017)  allows  an 
application  to  determine  a  digitizer's  preferred  time  scale. 

Applications  can  provide  a  custom  interrupt  function  by  calling 
VDSetDi  giti  zerllserlnterrupt  (III — 2039). 


Functions 

VDSetPLLFi  1  terType  (III— 2051) 

Specifies  which  phase  locked  loop  (PLL)  is  to  be  active. 

VDGetPLLFi  1  terType  (III— 2015) 

Determines  which  phase  locked  loop  (PLL)  mode  is  currently  active  for  a  video 
digitizer. 

VDSetFi  el  dPreference  (III — 2040) 

Specifies  which  field  to  use  in  cases  where  the  vertical  scaling  is  less  than  half 
size. 

VDGetFi  el  dPreference  (III — 2 001) 

Determines  which  field  is  being  used  in  cases  where  the  image  is  vertically 
scaled  to  half  its  original  size. 

VDSetDi  giti  zerllserlnterrupt  (III — 2039) 

Sets  custom  interrupt  functions. 

VDGetSoundlnputDri  ver  (III — 20 1 9) 

Retrieves  information  about  a  video  digitizer's  sound  input  driver. 

VDGet P ref erredT i  meScal  e  (III — 2 017) 

Determines  a  digitizer's  preferred  time  scale. 

VDSetDi  giti  zerllserlnterrupt  (III — 2039) 

Sets  custom  interrupt  functions. 
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Callback 


Vdi  glntProc  (III — 2 154) 

An  interrupt  callback  called  by  the  video  digitizer  component  each  time  it  starts 
to  display  a  field. 


Exchanging  Movie  Data 


Movie  data  exchange  components  allow  applications  to  place  various  types  of  data 
into  a  QuickTime  movie  or  extract  data  from  a  movie  in  a  specified  format. 
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Importing  Movie  Data 

Movie  data  import  components  may  provide  functions  that  allow  the  Movie 
Toolbox  to  request  a  data  conversion  operation.  Before  the  Movie  Toolbox  calls  one 
of  these  functions,  a  requesting  application  may  call  one  or  more  of  your 
component's  configuration  functions.  However,  your  component  should  work 
properly  even  if  none  of  these  configuration  functions  is  called. 

Movi elmportHandl  e  (11-950)  instructs  your  component  to  retrieve  the  data  that  is  to 
be  imported  from  a  specified  handle.  Movi  elmportFi  1  e  (11-942)  instructs  you  to 
retrieve  the  data  from  a  file.  You  should  set  the  appropriate  flags  in  your 
component's  componentFlags  field  to  indicate  which  of  these  functions  your 
component  supports.  Note  that  your  component  may  support  both  functions.  Other 
functions  are  listed  below. 


Functions 

Movi  elmportHandl  e  (11-950) 

Imports  data  from  a  handle,  using  a  movie  data  import  component. 

Movi  elmportFi  1  e  (II — 942 ) 

Imports  data  from  a  file,  using  a  movie  data  import  component. 

Movi elmportGetFi  1  eType  (11-946) 

Allows  your  movie  data  import  component  to  tell  the  Movie  Toolbox  the 
appropriate  file  type  for  the  most-recently  imported  movie  file. 
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Movi  elmportGetAuxi  1  i  aryDataType  (11-944) 

Returns  the  type  of  the  auxiliary  data  that  a  component  can  accept. 

MovielmportGetMIMETypeList  (11-948) 

Returns  a  list  of  MIME  types  supported  by  the  movie  import  component. 

Movi  elmportVal  i  date  (11-964) 

Allows  your  movie  data  import  component  to  validate  the  data  to  be  passed  to 
your  component. 

MovielmportValidateDataRef  (11-965) 

Validates  the  data  file  indicated  by  the  data  reference. 

Movi  elmportSetOffsetAndLi  mi  t  (11-959) 

Specifies  location  and  size  of  data  that  should  be  imported. 

Movi  elmportSetOffsetAndLi  mi  t64  (11-960) 

Specifies  location  and  size  of  data  that  should  be  imported  from  a  file. 

MovielmportGetSetti  ngsAsAtomContai  ner  (11-949) 

Retrieves  the  current  settings  from  the  movie  import  component. 

MovielmportSetSetti  ngsFromAtomContai  ner  (11-963) 

Sets  the  movie  import  component's  current  configuration  from  the  passed 
settings  data. 

See  Also 

See  also  "Using  Graphics  Importers"  (V-2876). 


Configuring  Movie  Data  Import  Components 

Your  component  may  provide  one  or  more  configuration  functions  that  allow 
applications  to  configure  your  component  before  the  Movie  Toolbox  calls  your 
component  to  start  the  import  process.  Note  that  applications  may  call  these 
functions  directly.  All  of  these  functions  are  optional.  If  your  component  receives  a 
request  that  it  does  not  support,  you  should  return  the  badComponentSel  ector  error 
code.  In  addition,  your  component  should  work  properly  even  if  none  of  these 
functions  is  called. 

Movi  elmportSetSampl  eDurati  on  (11-962)  allows  an  application  to  set  your 
component's  sample  duration.  Use  Movi  elmportSetDurati  on  (11-957)  to  control  the 
duration  of  the  imported  data.  Applications  can  use  Movi  elmportSetDi mensi  ons 
(11-955)  to  specify  the  spatial  dimensions  of  a  new  track.  Use 
MovielmportSetSampleDescription  (11-961)  to  supply  a  sample  description  structure 
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to  your  movie  data  import  component. 


Movi  elmportSetMedi  aFi  1  e  (11-958)  allows  applications  to  direct  your  component's 
output  to  a  specific  media  file.  Applications  can  provide  additional  data  to  your 
component  by  calling  Movi  elmportSetAuxi  1  iaryData  (11-954). 

Movi  elmportSetChunkSi  ze  allows  applications  to  control  the  chunk  size  in  the  new 
media.  Applications  can  inform  you  that  the  source  data  came  from  the  scrap  by 
calling  Movi  elmportSetFromScrap  (11-957).  Applications  can  specify  a  progress 
function  for  use  by  your  component  by  calling  Movi  elmportSetProgressProc 
(11-961).  Applications  can  instruct  your  component  to  display  its  user  dialog  box  by 
calling  Movi  elmportDollserDi  al  og  (11-940). 


Functions 

Movi  elmportSetSampl  eDurati  on  (11-962) 

Sets  the  sample  duration  for  new  samples  to  be  created  with  a  component. 

Movi  elmportSetDurati  on  (11-957) 

Controls  the  duration  of  the  data  that  a  component  pastes  into  the  target  movie. 

Movi elmportSetDi mensi ons  (11-955) 

Specifies  a  new  track's  spatial  dimensions. 

Movi  elmportSetSampl  eDescri  pti  on  (11-961) 

Provides  a  Sampl  eDescri  pti  on  (IV-2414)  structure  to  a  movie  data  import 
component. 

Movi  elmportSetMedi  aFi  1  e  (11-958) 

Specifies  a  media  file  that  is  to  receive  the  imported  movie  data. 

Movi  elmportSetAuxi  1  i  aryData  (II — 954) 

Provides  additional  data  to  a  component. 

Movi  elmportSetChunkSi  ze  (11-954) 

The  amount  of  data  a  component  works  with  at  a  time. 

Movi  elmportSetFromScrap  (11-957) 

Indicates  that  the  source  data  resides  on  the  scrap. 

Movi  elmportSetProgressProc  (11-961) 

Assigns  a  movie  progress  function. 

Movi  elmportDollserDi  al  og  (11-940) 

Requests  that  a  component  display  its  user  dialog  box. 
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Exporting  Movie  Data 


Movie  data  export  components  may  provide  one  or  two  functions  that  allow  the 
Movie  Toolbox  to  request  a  data  conversion  operation.  Before  the  Movie  Toolbox 
calls  one  of  these  functions,  a  requesting  application  may  call  one  or  more  of  your 
component's  configuration  functions.  However,  your  component  should  work 
properly  even  if  none  of  these  configuration  functions  is  called. 

MovieExportToHandle  (11-936)  instructs  your  component  to  place  the  converted  data 
into  a  specified  handle.  Movi eExportToFi 1  e  (11-934)  instructs  you  to  put  the  data  into 
a  file.  You  should  set  the  appropriate  flags  in  your  component's  componentFl  ags 
field  to  indicate  which  of  these  functions  your  component  supports.  Note  that  your 
component  may  support  both  functions.  Additional  functions  are  listed  below. 


Functions 

MovieExportToHandle  (11-936) 

Exports  data  from  a  movie,  using  a  movie  data  export  component. 

Movi  eExportToFi  1  e  (11-934) 

Exports  data  to  a  file,  using  a  movie  data  export  component. 

Movi  eExportGetAuxi  1  i  aryData  (11-923) 

Retrieves  additional  data  from  a  component. 

Movi  e  Expo  rt  Set  Samp  1  eDescription  (11-931) 

Requests  the  format  of  the  exported  data. 

Movi  eExportVal  i  date  (11-937) 

Determines  whether  a  movie  export  component  can  export  all  the  data  for  a 
specified  movie  or  track. 

Movi  e  Export  Add  Data  Source  (11-919) 

Defines  a  data  source  for  use  with  an  export  operation  performed  by 
Movi eExportFromProceduresToDataRef  (11-922). 

Movi  eExportFromProceduresToDataRef  (11-922) 

Exports  data  provided  by  Movi  eExportAddDataSource  (11-919)  to  a  specified 
location. 

Movi  eExportSetGetMovi  ePropertyProc  (11-929) 

Specifies  the  procedure  that  the  export  component  should  call  to  retrieve  movie 
level  properties  during  Movi  eExportFromProceduresToDataRef  (11-922). 
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MovieExportToDataRef  (11-933) 

Allows  an  application  to  request  that  data  be  exported  to  a  data  reference 
instead  of  to  a  file. 

Movi  eExportGetSetti  ngsAsAtomContai  ner  (11-925) 

Retrieves  the  current  settings  from  the  movie  export  component. 

Movi  eExportSetSetti  ngsFromAtomContai  ner  (11-932) 

Sets  the  movie  export  component's  current  configuration  from  passed  settings 
data. 

Movi eExportNewGetDataAndProperti esProcs  (11-927) 

Returns  Movi  eExportGetPropertyProc  (III— 2102)  and  Movi  eExportGetDataProc 
(III— 2101)  callbacks  that  can  be  passed  to  Movi  eExportAddDataSource  (11-919)  to 
create  a  new  data  source. 

Movi  eExportDi  sposeGetDataAndProperti  esProcs  (11-920) 

Disposes  of  the  memory  associated  with  the  procedures  returned  by 
Movi  eExportNewGetDataAndProperti  esProcs  (11-927). 

See  Also 

See  also  "Using  Graphics  Exporters"  (V-2883). 
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Configuring  Movie  Data  Export  Components 

Your  component  may  provide  one  or  more  configuration  functions.  These  functions 
allow  applications  to  configure  your  component  before  the  Movie  Toolbox  calls 
your  component  to  start  the  export  process.  Note  that  applications  may  call  these 
functions  directly.  All  of  these  functions  are  optional.  If  your  component  receives  a 
request  that  it  does  not  support,  you  should  return  the  badComponentSelector  error 
code.  In  addition,  your  component  should  work  properly  even  if  none  of  these 
functions  is  called. 

Applications  can  retrieve  additional  data  from  your  component  by  calling 
Movi  eExportGetAuxi  1  i  ary  Data  (11-923).  Applications  can  specify  a  progress  function 
for  use  by  your  component  by  calling  Movi  eExportSetProgressProc  (11-930). 
Applications  can  instruct  your  component  to  display  its  user  dialog  box  by  calling 
Movi  eExportDoUserDi  al  og  (11-921). 


Functions 


Movi  eExportGetAuxi  1  i  aryData  (11-923) 

Retrieves  additional  data  from  a  component. 
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Movi  e  Expo  r  t  Se  t  Prog  res  sP  roc  (11-930) 

Assigns  a  movie  progress  function. 

Movi  eExportDoUserDi  al  og  (II — 921) 

Requests  that  a  component  display  its  user  dialog  box. 


Exporting  Text 

The  text  export  and  import  components  provide  make  it  easy  to  work  with  the  data 
in  a  text  track  in  a  QuickTime  movie.  Text  descriptors  are  formatting  commands 
that  you  can  embed  within  a  text  file.  Time  stamps  describe  a  text  sample's  starting 
time  and  duration.  When  you  export  text  from  a  text  track,  you  can  optionally 
export  text  descriptors  and  time  stamps  for  the  text.  You  can  open  the  text  file  in  a 
word  processor  and  make  changes  to  the  text,  style,  color,  and  time  stamps.  You  can 
then  import  the  edited  text  to  a  text  track  where  all  the  timing,  style,  color  and  time 
stamp  information  will  be  present. 

The  functions  listed  below  support  text  exporting. 


Functions 


TextExportGetDi  spl  ayData  (III — 1 928) 

Retrieves  text  display  information  for  the  current  sample  in  the  specified  text 
export  component. 

Text  Expo  rtGetT i  meFracti  on  (III — 1 929) 

Retrieves  the  time  scale  the  specified  text  export  component  uses  to  calculate 
time  stamps. 

Text  Expo  rtSetT  i  meFracti  on  (III — 1931) 

Sets  the  time  scale  the  specified  text  export  component  uses  to  calculate  time 
stamps. 

TextExportGetSetti ngs  (III — 1 928) 

Retrieves  the  value  of  the  text  export  option  for  the  specified  text  export 
component. 

TextExportSetSetti ngs  (III — 1 930) 

Sets  the  value  of  the  text  export  option  for  the  specified  text  export  component. 
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Using  Derived  Media  Handlers 


Derived  media  handler  components  allow  the  Movie  Toolbox  to  play  the  data  in  a 
media.  These  components  isolate  the  Movie  Toolbox  from  the  details  of  how  or 
where  a  particular  media  is  stored.  This  not  only  frees  the  Movie  Toolbox  from 
reading  and  writing  media  data,  but  also  makes  QuickTime  extensible  to  new  data 
formats.  These  components  are  referred  to  as  derived  components  because  they  rely 
on  the  services  of  a  common  base  media  handler  component,  which  is  supplied  by 
Apple.  The  base  media  handler  component  handles  most  of  the  duties  that  must  be 
performed  by  all  media  handlers.  Your  derived  media  handler  component  extends 
the  services  provided  by  the  base  media  handler. 
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Managing  Your  Media  Handler  Component 

Derived  media  handlers  provide  three  functions  that  allow  the  Movie  Toolbox  to 
manage  its  relationship  with  the  media  handler. 

The  Movie  Toolbox  calls  Medi  a  Ini  ti  al  i  ze  (11-877)  in  order  to  give  you  an 
opportunity  to  prepare  to  provide  access  to  your  media.  The  Movie  Toolbox  grants 
processing  time  to  your  handler  by  calling  Medi  a  I  dl  e  (11-874).  Calling 
Medi  aGGetStatus  (11-869)  then  allows  the  Movie  Toolbox  to  retrieve  status 
information. 


Functions 

Medi  a  Ini  ti  al  i  ze  (11-877) 

Prepares  a  derived  media  handler  component  to  provide  access  to  its  media. 
Medi  a  Idl  e  (11-874) 

Provides  processing  time  to  a  derived  media  handler  during  movie  playback. 

Medi  aGGetStatus  (11-869) 

Reports  error  conditions  to  the  Movie  Toolbox. 


General  Data  Management 


While  the  base  media  handler  isolates  your  component  from  the  details  of  media 
data  access,  your  derived  media  handler  still  needs  to  keep  track  of  certain 
information  in  order  to  support  movie  playback  and  creation. 
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Your  media  handler  may  store  proprietary  information  in  its  media.  The  Movie 
Toolbox  calls  two  media  handler  functions  in  order  to  give  you  an  opportunity  to 
retrieve  or  store  this  information.  MediaPutMedialnfo  (11-884)  allows  you  to  store 
your  special  information  in  your  media.  Medi  aGetMedi  a  Info  (11-853)  delivers  that 
data  to  your  media  handler. 

The  Movie  Toolbox  tells  your  media  handler  when  its  track  has  been  enabled  or 
disabled  by  calling  Medi  aSetActi  ve  (11-889).  The  Movie  Toolbox  prepares  your 
handler  for  playback  by  calling  Medi  aPrerol  1  (11-883).  Whenever  your  media's 
playback  rate  changes,  the  Movie  Toolbox  calls  Medi  a  Set  Rate  (11-903).  Whenever  the 
track  that  uses  your  media  is  edited,  the  Movie  Toolbox  calls  Medi  aT rackEdi  ted 
(11-914). 

If  the  Movie  Toolbox  has  called  SetMedi  aSampl  eDescri  pti  on  (III— 1606)  on  a  sample 
description,  it  uses  Medi  aSampl  eDescri  pti  onChanged  (11-887)  to  notify  your  media 
handler  of  the  change. 

The  Movie  Toolbox  allows  tracks  to  be  identified  by  various  characteristics.  For 
instance,  it  is  possible  to  request  that  all  tracks  containing  audio  information  be 
searched.  To  determine  whether  a  track  has  a  given  characteristic,  the  Movie 
Toolbox  queries  the  media  handler  for  each  track.  The  Movie  Toolbox  calls 
Medi aHasCharacteri sti c  (11-872)  with  the  specified  characteri  sti  c. 

The  Movie  Toolbox  uses  two  functions  to  inform  you  about  changes  to  your  media's 
time  environment.  MediaSetMediaTimeScal  e  (11-898)  allows  the  Movie  Toolbox  to 
change  your  media's  time  scale.  Medi  aSetMovi  eT i meScal  e  (11-899)  allows  the  Movie 
Toolbox  to  tell  you  when  the  movie's  time  scale  has  changed.  Other  functions  are 
listed  below. 


Functions 

MediaPutMedialnfo  (11-884) 

Lets  a  derived  media  handler  store  proprietary  information  in  its  media. 
Medi  aGetMedialnfo  (11-853) 

Lets  a  derived  media  handler  obtain  the  private  data  stored  in  its  media. 

Medi  aSetActi  ve  (11-889) 

Enables  and  disables  media. 

MediaPreroll  (11-883) 

Prepares  a  media  handler  for  playback. 
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Med  1  aSetRate  (11-903) 

Sets  a  media's  playback  rate. 

Medi  aTrackEdi  ted  (11-914) 

Informs  a  derived  media  handler  about  edits  to  its  track. 

Medi  aSampl  eDescri  pti  onChanged  (11-887) 

Informs  a  media  handler  that  SetMedi  aSampl  eDescri  pti  on  (III— 1606)  has  been 
called  for  a  specified  sample  description. 

Medi  aHasCharacteri  sti  c  (11-872) 

C  ailed  by  Movie  Toolbox  with  a  specified  characteristic  to  allow  tracks  to  be 
identified  by  various  attributes. 

Medi  aSetMedi  aT i meScal  e  (11-898) 

Informs  a  media  handler  that  its  media's  time  scale  has  been  changed. 

Medi  aSetMovi  eT i meScal  e  (11-899) 

Informs  a  media  handler  that  the  movie's  time  scale  has  been  changed. 

Medi  aGSetActi  veSegment  (11-870) 

Informs  your  derived  media  handlers  of  the  current  active  segment. 

Medi  a  Inval  i  dateRegi  on  (11-879) 

Updates  the  invalidated  display  region  the  next  time  Medi  a  Idl  e  is  called. 

Medi  aGetNextStepTime  (11-856) 

Searches  for  the  next  forward  or  backward  step  time  from  the  given  media  time. 
Medi  aT rackReferencesChanged  (11-915) 

Notifies  the  derived  media  handler  whenever  the  track  references  in  the  movie 
change. 

Medi  aTrackPropertyAtomChanged  (11-915) 

Notifies  the  derived  media  handler  whenever  its  media  property  atom  has 
changed. 

Medi  aSetTracklnputMapReference  (11-908) 

Provides  a  derived  media  handler  with  an  updated  input  map. 

Medi  aGetSampl  eDataPoi  nter  (11-859) 

Allows  a  derived  media  handler  to  obtain  a  pointer  to  the  sample  data  for  a 
particular  sample  number,  the  size  of  that  sample,  and  the  index  of  the  sample 
description  associated  with  that  sample. 
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Medi  aRel  easeSampl  eDataPoi  nter  (11-886) 

Balances  calls  to  Medi  aGetSampl  eDataPoi  nter  (11-859)  to  release  allocated 
memory. 

MediaCompare  (11-844) 

Lets  a  media  handler  determine  whether  the  Movie  Toolbox  should  allow  one 
track  to  be  pasted  into  another. 

Medi  aSetVi  deoParam  (11-910) 

Lets  you  dynamically  adjust  the  bri  ghtness,  contrast,  hue,  sharpness, 
saturation,  black  level,  and  white  level  of  a  video  image. 

Medi  aGetVi  deoParam  (11-868) 

Retrieves  the  value  of  the  brightness,  contrast,  hue,  sharpness,  saturation,  black 
level,  or  white  level  of  a  video  image. 

Medi  aSetNonPrimary  Source  Data  (11-899) 

Allows  a  media  handler  to  support  receiving  media  data  from  other  media 
handlers. 

Medi aGetOffscreenBufferSi ze  (11-858) 

Determines  the  dimensions  of  the  offscreen  buffer. 

Medi aSetHi nts  (11-896) 

Implements  the  appropriate  behavior  for  the  various  media  hints  such  as  scrub 
mode  and  high-quality  mode. 

Medi aGetName  (11-855) 

Returns  the  name  of  the  media  type. 


Managing  Graphics  Data 

If  your  media  handler  draws  media  data  on  the  screen,  you  need  to  manage  your 
media's  graphics  environment.  The  Movie  Toolbox  uses  a  number  of  functions  to 
inform  you  about  changes  to  the  graphics  environment.  The  Movie  Toolbox  only 
calls  these  functions  if  you  have  set  the  handlerHasSpatial  flag  to  1  when  calling 
Medi  aSetHandl  erCapabi  1  i  ti  es  (11-894). 

The  Movie  Toolbox  calls  Medi  aSetGWorl  d  (11-893)  whenever  your  media's  graphics 
port  or  graphics  device  has  changed.  Medi  aSetDi  mensi  ons  (11-891)  allows  the  Movie 
Toolbox  to  inform  your  handler  about  changes  to  its  spatial  dimensions.  Whenever 
either  the  movie  or  track  matrix  changes,  the  Movie  Toolbox  calls  MediaSetMatrix 
(11-897).  Similarly,  if  your  media's  clipping  region  changes,  the  Movie  Toolbox  calls 
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Med  1  aSetCl  i  p  (11-890). 


When  it  is  building  up  a  movie's  image  from  its  component  tracks,  the  Movie 
Toolbox  must  be  able  to  determine  which  tracks  are  transparent.  The  Movie 
Toolbox  calls  Medi  aGetT rackOpaque  (11-865)  to  retrieve  this  information  about  your 
media. 

The  Movie  Toolbox  calls  Medi  aGetNextBoundsChange  (11-855)  so  that  it  can  learn 
when  your  media  will  next  change  its  display  shape.  When  the  Movie  Toolbox 
wants  to  find  out  the  shape  of  the  region  into  which  you  draw  your  media,  it  calls 
Medi  aGetSrcRgn  (11-865).  Other  functions  are  listed  below. 


Functions 
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Medi  aSetGWorl  d  (11-893) 

Lets  a  derived  media  handler  learn  about  changes  to  its  media's  graphic 
environment. 

Medi  aSetDimensi  ons  (11-891) 

Informs  a  media  handler  when  its  media's  spatial  dimensions  change. 

Medi  aSetMatri x  (11-897) 

Tells  a  media  handler  about  changes  to  either  the  movie  matrix  or  the  track 
matrix. 

Medi  aSetCl  i  p  (11-890) 

Specifies  changes  to  a  derived  media  handler's  clipping  region. 

Medi  aGetT  rackOpaque  (11-865) 

Determines  whether  a  media  is  transparent  or  opaque  when  displayed. 

Medi  aGetNextBoundsChange  (11-855) 

Determines  when  a  media  causes  a  spatial  change  to  a  movie. 

Medi  aGetSrcRgn  (11-865) 

Specifies  an  irregular  destination  display  region  to  the  Movie  Toolbox. 

Medi  aGetDrawi  ngRgn  (11-849) 

Specifies  a  portion  of  the  screen  that  must  be  redrawn,  defined  in  the  movie's 
display  coordinate  system. 

Medi  aGetGraphi  csMode  (11-852) 

Obtains  the  graphics  mode  and  blend  color  values  currently  in  use  by  any 
media  handler. 
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Med i  aSetGraphi  csMode  (11-892) 

Sets  the  graphics  mode  and  blend  color  of  any  media  handler. 

Managing  Sound  Localization 

If  you  are  creating  a  media  handler  that  plays  sound  and  wish  to  support  3D  sound 
capabilities,  you  need  to  implement  the  function  listed  below. 

The  required  function  is  Medi  aSetSoundLocal  i zati  onData  (11-907). 

Function 

Medi  aSetSoundLocal  i  zati  onData  (11-907) 

Supports  3D  sound  capabilities  in  a  media  handler  that  plays  sound. 

Making  a  Progressive  Download  Time  Table 

When  an  application  or  other  software  calls  any  of  the  Movie  Toolbox's  functions  to 
create  a  time  table  for  progressive  downloads,  the  base  media  handler  calls  your 
derived  media  handler  to  create  the  time  table 

The  required  function  is  Medi  aMakeMedi  aTimeTabl  e  (11-879). 

Function 

Medi  aMakeMedi  aT i  meTabl  e  (11-879) 

Called  by  the  base  media  handler  to  create  a  media  time  table. 

Reporting  Capabilities  to  the  Base  Media  Handler 

Apple's  base  media  handler  component  provides  a  utility  function  that  allows  you 
to  tell  the  base  handler  what  your  derived  handler  can  do. 

This  function,  Medi  aSetHandl  erCapabi  1  i  ti  es  (11-894),  is  listed  below. 

Function 

Medi  aSetHandl  erCapabi  li  ties  (11-894) 

Lets  a  derived  media  handler  report  its  capabilities  to  the  base  media  handler. 
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Using  Clock  Components 


Clock  components  provide  two  basic  services:  they  generate  time  information  and 
schedule  time-based  callback  events.  In  QuickTime,  the  Movie  Toolbox  is  the 
primary  user  of  clock  components.  Specifically,  the  Movie  Toolbox  uses  clock 
components  to  provide  basic  timing  to  time  bases.  In  general,  clock  components 
derive  their  timing  information  from  some  external  source. 


Getting  the  Current  Time 

Clock  components  provide  a  single  function  that  allows  the  Movie  Toolbox  to 
obtain  the  current  time. 

This  function  is  listed  below. 
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Function 


Cl  ockGetT i me  (1-95) 

Obtains  the  current  time  according  to  a  specified  clock. 


Using  Callback  Functions 

Applications  that  use  QuickTime  time  bases  may  define  callback  functions  that  are 
associated  with  a  specific  time  base.  Applications  can  then  use  these  callback 
functions  to  perform  activities  that  are  triggered  by  temporal  events,  such  as  a 
certain  time  being  reached  or  a  specified  rate  being  achieved.  The  time  base 
functions  of  the  Movie  Toolbox  interact  with  clock  components  to  schedule  the 
invocation  of  these  callback  functions,  and  your  clock  component  is  responsible  for 
calling  the  callback  function  at  its  scheduled  time. 

Cl  ockNewCall  Back  (1-96)  allows  your  clock  component  to  allocate  the  memory  to 
support  a  new  callback  event.  When  an  application  discards  a  callback  event,  the 
Movie  Toolbox  calls  ClockDisposeCallBack  (1-94).  The  Movie  Toolbox  calls 
Cl  ockCal  1  MeWhen  (1-91)  when  an  application  wants  to  schedule  a  callback  event. 
When  the  callback  function  is  to  be  invoked  to  service  the  event,  the  Movie  Toolbox 
calls  Cl  ockCancel  Cal  1  Back  (1-93)  so  that  you  can  remove  the  callback  event  from  the 
list  of  scheduled  events. 
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Functions 


Cl  ockNewCal  1  Back  (1-96) 

In  a  clock  component,  allocates  memory  for  a  new  callback  event. 

Cl  ockDi  sposeCal  1  Back  (1-94) 

In  a  clock  component,  disposes  of  the  memory  associated  with  the  specified 

callback  event. 

Cl  ockCal  1  MeWhen  (1-91) 

In  a  clock  component,  schedules  a  callback  event  for  invocation. 

Cl  ockCancel  Call  Back  (1-93) 

In  a  clock  component,  removes  the  specified  callback  event  from  the  list  of 
scheduled  callback  events  for  a  time  base. 


Managing  the  Time 

Clock  components  provide  several  functions  that  allow  the  Movie  Toolbox  to  alert 
your  component  to  changes  in  its  environment. 

Three  of  these  functions.  Cl  ockT i meChanged  (1-100),  Cl  ockRateChanged,  and 
Cl  ockStartStopChanged  (1-99),  are  associated  with  application  callback  functions 
and  help  your  component  determine  whether  to  invoke  the  callback  function.  The 
fourth.  Cl  ockSetTimeBase  (1-98),  tells  your  clock  component  about  the  time  base  it  is 
supporting. 


Functions 


Cl  ockTi  meChanged  (I — 1 00) 

In  a  clock  component,  is  called  whenever  the  callback's  time  base  time  value  is 
set. 

Cl  ockRateChanged  (1-97) 

In  a  clock  component,  is  called  whenever  the  callback's  time  base  rate  changes. 
Cl  ockStartStopChanged  (1-99) 

In  a  clock  component,  is  called  whenever  the  start  or  stop  time  of  the  callback's 
time  base  changes. 

Cl  ockSetTi  meBase  (1-98) 

In  a  clock  component,  is  called  when  an  application  creates  a  time  base  that  uses 
the  clock  component. 
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Movie  Toolbox  Clock  Support  Functions 


The  Movie  Toolbox  provides  a  number  of  support  functions  for  clock  components. 
All  of  these  functions  help  your  component  manage  its  associated  callback 
functions.  Your  clock  component  may  call  any  of  these  functions  at  interrupt  time. 
These  functions  should  only  be  called  by  clock  components. 

Use  AddCal  1  BackToTimeBase  (1-21)  to  add  a  callback  event  to  the  list  of  scheduled 
callback  events  maintained  by  the  Movie  Toolbox.  You  should  use 
RemoveCal  1  BackFromTimeBase  (III— 1456)  to  remove  a  callback  event  from  the  list. 
When  your  clock  component  determines  that  it  is  time  to  invoke  a  callback  function, 
you  should  use  ExecuteCal  1  Back  (1-339)  to  cause  the  Movie  Toolbox  to  call  the 
function.  If  your  clock  component  needs  to  scan  all  its  associated  callback  events, 
you  can  use  GetFi  rstCal  1  Back  (1-411)  and  GetNextCal  1  Back  (1-501). 
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Functions 

AddCal  1  BackToTimeBase  (1-21) 

Places  a  callback  event  into  the  list  of  scheduled  callback  events. 

RemoveCal  1  BackFromT imeBase  (III — 1456) 

Removes  a  callback  event  from  the  list  of  scheduled  callback  events. 

ExecuteCal  1  Back  (1-339) 

Called  by  a  clock  component  when  it  determines  that  it  is  time  to  execute  a 
callback  function. 

GetFi  rstCal  1  Back  (1-411) 

Returns  the  first  callback  event  associated  with  a  specified  time  base. 
GetNextCal  1  Back  (1-501) 

Returns  the  next  callback  event  associated  with  a  specified  time  base. 


Using  the  Timecode  Media  Handler 


The  timecode  media  handler  allows  QuickTime  movies  to  store  timing  information 
that  is  not  created  by  or  for  QuickTime.  This  additional  timing  information  would 
typically  be  derived  from  the  original  source  material  (for  example,  as  a  SMPTE 
timecode).  In  essence,  you  can  think  of  the  timecode  media  handler  as  providing  a 
link  between  the  digital  QuickTime-specific  timing  information  and  the  original 
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analog  timing  information  from  the  source  material. 


A  movie's  timecode  is  stored  in  a  timecode  track.  Timecode  tracks  contain  source 
identification  information,  timecode  format  information,  and  frame  numbers. 
Apple  Computer  has  defined  the  information  that  is  stored  in  the  track  in  a  manner 
that  is  independent  of  any  specific  timecode  standard.  The  format  of  this 
information  is  sufficiently  flexible  to  accommodate  all  known  timecode  standards, 
including  SMPTE  timecoding. 

One  key  timecode  attribute  relates  to  the  dropframe  technique  used  to  synchronize 
timecode  values  with  video  frames.  There  is  a  flag  in  the  timecode  definition 
structure  that  indicates  whether  the  timecode  uses  the  dropframe  technique. 


Working  With  the  Timecode  Media  Handler 

You  can  create  a  timecode  track  and  media  in  the  same  manner  that  you  create  any 
other  track.  Call  NewMovi  eTrack  (11-1092)  to  create  the  timecode  track,  and  use 
NewT rackMedi  a  (11-1120)  to  create  the  track's  media.  Be  sure  to  specify  a  media  type 
value  of  T  i  meCodeMedi  aType  when  you  call  NewT  rackMedi  a  (11-1120). 

You  can  make  the  toolbox  display  the  timecode  when  a  movie  is  played.  Use 
TCSetTimeCodeFlags  (III— 1923)  to  turn  the  timecode  display  on  and  off.  Note  that  the 
timecode  track  must  be  enabled  for  this  display  to  work. 

You  can  define  the  relationship  between  a  timecode  track  and  one  or  more  movie 
tracks  using  track  reference  functions;  see  "Working  With  Track  References" 
(V-2737).  You  then  add  samples  to  the  track  as  appropriate.  Each  sample  in  the 
timecode  track  provides  timecode  information  for  a  span  of  movie  time.  The  sample 
includes  duration  information.  As  a  result,  you  typically  add  each  timecode  sample 
after  you  have  created  the  corresponding  content  track  or  tracks. 

The  T i meCodeDescri  pti  on  (IV-2483)  structure  contains  control  information  that 
allows  QuickTime  to  interpret  the  samples.  This  includes  the  timecode  format 
information.  The  actual  sample  data  contains  a  frame  number  that  identifies  one  or 
more  content  frames  that  use  this  timecode.  This  value  identifies  the  first  frame  in 
the  group  of  frames  that  use  this  timecode.  In  the  case  of  a  movie  made  from  source 
material  that  contains  no  edits,  you  would  only  need  one  sample.  When  the  source 
material  contains  edits,  you  typically  need  one  sample  for  each  edit,  so  that 
QuickTime  can  resynchronize  the  timecode  information  with  the  movie.  Those 
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samples  contain  the  frame  numbers  of  the  frames  that  begin  each  new  group  of 
frames. 


Functions 

TCSetTimeCodeFl  ags  (III — 1 923) 

Changes  the  flag  that  affects  how  the  toolbox  handles  timecode  information. 

TCGet  TimeCode  FI  ags  (ID-1921) 

Retrieves  the  timecode  control  flags. 

TCGetCurrentTimeCode  (III-1917) 

Retrieves  the  timecode  and  source  identification  information  for  the  current 
movie  time. 

TCGetTi meCodeAtT i me  (III-1920) 

Returns  a  track's  timecode  information  corresponding  to  a  specific  media  time. 
TCGetDi  spl  ayOpti  ons  (III-1918) 

Retrieves  the  text  characteristics  that  apply  to  timecode  information  displayed 
in  a  movie. 

TCSetDi  spl  ayOpti  ons  (III-1922) 

Sets  the  text  characteristics  that  apply  to  timecode  information  displayed  in  a 
movie. 

TCGetSourceRef  (III-1919) 

Retrieves  the  source  information  from  the  timecode  media  sample  reference. 
TCSetSourceRef  (III-1922) 

Changes  the  source  information  in  the  timecode  media  sample  reference. 
TCFrameNumberToT i  meCode  (III-1916) 

Converts  a  frame  number  into  its  corresponding  timecode  time  value. 

TCT i meCodeToFrameN umber  (III-1924) 

Converts  a  timecode  time  value  into  its  corresponding  frame  number. 

TCTimeCodeToString  (III-1925) 

Converts  a  time  value  into  a  text  string  (HH:MM:SS:FF). 

Data  Structures 

TimeCodeDescri  ption  (IV-2483) 

Defines  the  format  and  content  of  a  timecode  media  sample  description. 
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T i  meCodeT i  me  (IV-2485) 

Provides  time  information  for  a  T i  meCodeRecord  (IV-2484)  structure. 


Using  Preview  Components 


Preview  components  are  used  by  the  Image  Compression  Manager's  standard  file 
preview  functions  to  display  and  create  visual  previews  for  files.  Previews  usually 
consist  of  a  single  image,  but  they  may  contain  many  kinds  of  data,  including 
sound.  The  Image  Compression  Manager  is  the  primary  client  of  preview 
components.  Rarely,  if  ever,  do  applications  call  preview  components  directly. 


Displaying  Previews 

The  preview  component  supplies  a  single  function  for  displaying  movie  previews. 

If  your  preview  component  does  not  handle  events  (that  is,  does  not  contain 
time-based  data),  you  should  use  Previ  ewShowData  (11-1146). 


Functions 

Previ  ewShowData  (11-1146) 

Displays  a  preview  if  it  does  not  handle  events. 


Handling  Preview  Events 

A  function  is  provided  so  that  your  preview  component  can  do  standard  event 
filtering. 

If  your  preview  component  handles  events,  Previ  ewEvent  (11-1144)  is  called  as 
appropriate. 


Functions 


Previ  ewEvent  (11-1144) 

May  be  called  as  appropriate  if  a  preview  component  handles  events. 
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Creating  Previews 

Two  functions  are  available  for  use  in  creating  previews. 

Previ  ewMakePrevi  ew  (11-1145)  creates  previews  by  allocating  a  handle  to  data  to  be 
added  to  the  file.  On  the  other  hand,  Previ  ewMakePrevi  ewReference  (11-1145)  makes 
previews  by  returning  the  type  and  identification  number  of  a  resource  within  the 
file  to  be  used  as  the  preview  for  the  file. 


Functions 

Previ  ewMakePrevi  ew  (11-1145) 

Creates  previews  by  allocating  a  handle  to  data  that  is  to  be  added  to  a  file. 
Previ  ewMakePrevi  ewReference  (11-1145) 

Returns  the  type  and  identification  number  of  a  resource  within  a  file  to  be  used 
as  the  preview  for  a  file. 
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Transcoding  Images 


For  some  types  of  compressed  image  data,  it  is  possible  to  convert  directly  from  one 
compressed  format  to  another.  This  direct  conversion  process  is  called  image 
transcoding.  Transcoding  has  two  distinct  advantages  over  the 
decompress-then-recompress  approach  to  converting  the  format  of  compressed 
data.  The  first  advantage  is  that  the  operation  is  usually  substantially  faster,  since 
much  of  the  data  can  be  copied  directly  from  the  source  image  data  format  to  the 
destination  image  data  format.  The  second  advantage  is  that  the  operation  is 
usually  more  accurate  because  decompressing  and  recompressing  provides  two 
steps  for  introducing  rounding  and  quantization  errors.  By  directly  transcoding, 
opportunities  for  small  errors  are  substantially  reduced. 


Image  Transcoder  Support 


QuickTime  provides  several  image  transcoder  component  functions. 
These  functions  are  listed  below. 
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Functions 


ImageTranscoderBeg inSequence  (II — 7 51) 

Initiates  an  image  transcoding  sequence  and  specifies  the  input  data  format. 

ImageT ranscodeSequenceBegi n  (11-754) 

Initiates  an  image  transcoder  sequence  operation. 

ImageTranscoderConvert  (11-752) 

Performs  image  transcoding  operations. 

ImageTranscodeFrame  (11-750) 

Transcodes  a  frame  of  image  data. 

ImageTranscoderDisposeData  (11-753) 

Disposes  of  transcoded  data. 

ImageTranscodeDisposeFrameData  (11-749) 

Disposes  transcoded  image  data. 

ImageTranscoderEndSequence  (11-754) 

Ends  an  image  transcoding  sequence. 

ImageTranscodeSeq uence End  (11-755) 

Ends  an  image  transcoder  sequence  operation. 


Using  Text  Channel  Components 


Just  as  video  digitizer  components  obtain  digitized  video  from  an  analog  video 
source,  text  digitizer  components  obtain  text  from  an  external  source.  A  text  channel 
component  is  a  sequence  grabber  channel  component.  A  text  digitizer  is  a  new  kind 
of  component.  The  text  channel  component  uses  the  services  of  text  digitizer 
components. 


Text  Channel  Support 

The  text  channel  component  provides  several  functions  for  formatting  text  to  be 
previewed  or  added  to  a  text  track  of  a  movie. 

These  functions  are  listed  below. 
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Functions 


SGSetFontName  (III— 1790) 

Sets  the  name  of  the  font  to  be  used  to  display  text  for  a  text  channel  component. 
SGSetFontSize (HI-1791) 

Sets  the  font  size  to  be  used  to  display  text  for  a  text  channel  component. 

SGSetTextForeCol  or  (III — 1807) 

Sets  the  color  to  be  used  to  display  text. 

SGSetTextBackCol  or  (III — 1806) 

Sets  the  background  color  to  be  used  for  the  text  box. 

SGSetJusti  f  i  cati  on  (III — 1 795) 

Sets  the  alignment  to  be  used  to  display  text  for  a  text  channel  component. 
SGGetTextReturnToSpaceVal  ue  (III — 1 737) 

Indicates  whether  the  text  channel  component  should  replace  return  characters 
with  spaces. 

SGSetTextReturnToSpaceVal  ue  (III — 1807) 

Determines  whether  the  text  channel  component  should  replace  return 
characters  with  spaces. 

See  Also 

See  "Sequence  Grabbing"  (V-2808). 
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Tweening 


A  tween  media  handler  lets  you  use  tween  data  stored  in  a  tween  track  to  modify 
the  presentation  of  other  tracks  algorithmically.  When  a  movie  includes  a  tween 
track,  the  tween  media  handler  invokes  the  tween  component  (or  native  QuickTime 
code)  needed  to  process  the  tween  data  and  delivers  the  resulting  values  to  one  or 
more  other  media  handlers. 

A  tween  component  algorithmically  generates  an  output  value  for  any  point  in  a 
time  interval.  The  input  for  a  tween  is  a  small  number  of  values,  often  as  few  as  one 
or  two,  from  which  a  range  of  values  can  be  derived. 
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Tween  Component  Requirements 

You  must  provide  certain  functions  to  implement  a  tween  component.  QuickTime 
calls  these  functions  when  it  uses  your  component. 

These  functions  are  listed  below. 


Functions 

Tweenerlnitialize  (III — 1977) 

Initializes  your  tween  component  for  a  single  tween  operation. 
TweenerReset  (III — 1 978) 

Cleans  up  when  the  tween  operation  is  finished. 

TweenerDoTween  (III — 1 976) 

Performs  a  tween  operation. 


Using  Graphics  Importers 


Graphics  importer  components  provide  a  standard  method  for  opening  and 
displaying  still  images  contained  within  graphics  documents  and  for  working  with 
any  type  of  image  data,  regardless  of  the  file  format  or  compression  used  in  the 
graphics  document. 


Managing  Graphis  Importers 

QuickTime  provides  several  functions  to  manage  graphics  import  components. 
These  functions  are  listed  below. 


Functions 

GraphicsImportGetlmageCount  (1-637) 

Returns  the  number  of  images  in  an  imported  image  file. 

GraphicsImportSetlrriagelndex  (1-661) 

Specifies  the  image  index  for  an  imported  image. 
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Graphi  csImportGetlmagelndex  (1-638) 

Returns  the  current  image  index  for  an  imported  image. 

Graphi  cs  ImportGetDataOf  f  set  And  Si  ze  (1-624) 

Returns  the  offset  and  size  of  the  compressed  image  data  within  an  imported 
image  file. 

Graphi  cs  ImportGetDataOf  f  set  And  Si  ze64  (1-625) 

Provides  a  64-bit  version  of  Graphi  cs  ImportGetDataOff  setAndSi  ze. 

Graphi  cs  ImportReadData  (1-645) 

Reads  imported  image  data. 

Graphics  Import  ReadData64  (1-646) 

Provides  a  64-bit  version  of  Graphi  cs  ImportReadData  (1-645). 

Graphi  cs  ImportSetDataReferenceOf  f  set  And  Li  mi  t  (1-654) 

Specifies  the  data  reference  starting  offset  and  data  size  limit  for  an  imported 
image. 

Graphi  cs  ImportSetDataReferenceOf  f  set  And  Li  mi  t64  (1-656) 

Provides  a  64-bit  version  of  Graphi  cs  ImportSetDataReferenceOff  setAndLi mi  t 
(1-654). 

Graphi  cs  I  mportGet  Data  Ref  erenceOff  setAndLi  mi  t  (1-627) 

Returns  the  data  reference  starting  offset  and  data  size  limit  for  an  imported 
image. 

Graphi  cs  I  mportGet  Data  Ref  erenceOff  setAndLi  mi  t64  (1-628) 

Provides  a  64-bit  version  of  Graphi  cs  ImportGetDataReferenceOff  setAndLi  mi  t 
(1-627). 

Graphi  cs  ImportGetDef  aul  tMatrix  (1-630) 

Returns  the  default  matrix  for  an  imported  image,  if  one  is  stored  there. 

Graphi  cs  ImportGetDef  aul  tCl  i  p  (1-629) 

Returns  the  default  clipping  region  for  an  imported  image,  if  one  is  stored 
there. 

Graphi  cs  ImportGetDef  aul  tGraphi  csMode  (1-630) 

Returns  the  default  graphics  mode  for  an  imported  image,  if  one  is  stored  there. 

Graphi  cs  ImportGetDef  aul  tSourceRect  (1-631) 

Returns  the  default  source  rectangle  for  an  imported  image,  if  one  is  stored 
there. 
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GraphicsImportGetColorSyncProfile  (1-621) 

Returns  a  ColorSync  profile  for  an  imported  image,  if  one  is  embedded  in  the 
image  file. 

GraphicsImportSetDestRect  (1-657) 

Sets  the  destination  rectangle  for  a  graphics  import  operation. 

Graph IcsImportGetDestRect  (1-632) 

Returns  the  destination  rectangle  for  an  imported  image. 

Graphi  csImportSetFl  ags  (1-658) 

Sets  the  flags  for  a  graphics  importer  component. 

Graphi  csImportGetFl  ags  (1-634) 

Returns  the  current  flags  of  a  graphics  importer  component. 

Obtaining  a  Graphics  Importer  Instance 

There  are  three  functions  you  can  call  to  get  a  graphics  importer  instance. 

These  functions  are  listed  below. 


Functions 


GetGraphicsImporterForFile  (1-414) 

Locates  and  opens  a  graphics  importer  component  that  can  be  used  to  draw  a 
specified  file. 

GetGraphicsImporterFor  Data  Ref  (1-412) 

Locates  and  opens  a  graphics  importer  component  that  can  be  used  to  draw  the 
image  from  specified  data  reference. 

Ge  tGraphi  csImporterFor  Data  RefWithFl  ags  (1-413) 

Locates  and  opens  a  graphics  importer  component  for  a  data  reference  with 
flags  that  control  the  search  process. 


Getting  Image  Characteristics 

Certain  functions  are  called  by  applications  to  obtain  information  about  images. 
Format-specific  graphics  importers  always  implement 

GraphicsImportGetlmageDescri  pti  on  (1-638)  and  may  optionally  implement  the 
remaining  functions  listed  below. 
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Functions 


Graphi  cs  ImportGetNatural  Bounds  (1-642) 

Returns  the  bounding  rectangle  of  an  imported  image. 

Graphi  cs  ImportGetlmageDescri  pti  on  (1-638) 

Returns  image  description  information  for  an  imported  image. 

Graphi  cs  ImportGetDataOf  f  setAndSi  ze  (1-624) 

Returns  the  offset  and  size  of  the  compressed  image  data  within  an  imported 
image  file. 

Graphi  cs  ImportVal  i  date  (1-665) 

Validates  image  data  for  a  data  reference  to  an  imported  image. 

Graphi  cs  ImportGetMetaData  (1-640) 

Extracts  user  data  from  an  imported  image  file. 

Graphi  cs  ImportDoesDrawAl  1  Pixel  s  (1-613) 

Asks  whether  the  graphics  importer  expects  to  draw  every  pixel. 

Setting  Drawing  Parameters 

Certain  graphics  importer  functions  allow  you  to  specify  various  parameters  for 
drawing  operations,  such  as  clipping,  scaling,  graphics  mode,  and  decompression 
quality.  All  of  these  functions  are  based  on  corresponding  routines  in  the  Image 
Compression  Manager  for  working  with  image  decompression  sequences. 

These  functions  are  listed  below. 


Functions 

Graphi  csImportSetBoundsRect  (1-649) 

Defines  the  rectangle  in  which  to  draw  an  imported  image. 

Graphi  csImportGetBoundsRect  (1-619) 

Returns  the  bounding  rectangle  for  drawing  an  imported  image. 

Graphi  cs  ImportSetMatri x  (1-661) 

Defines  the  transformation  matrix  to  use  for  drawing  an  imported  image. 
Graphi  cs  ImportGetMatri x  (1-639) 

Returns  the  transformation  matrix  to  be  used  for  drawing  an  imported  image. 
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GraphicsImportSetClip  (1-650) 

Defines  the  clipping  region  for  drawing  an  imported  image. 

GraphicsImportGetClip  (1-620) 

Returns  the  current  clipping  region  for  an  imported  image. 

GraphicsImportSetGraphicsMode  (1-659) 

Sets  the  graphics  transfer  mode  for  an  imported  image. 

GraphicsImportGetGraphicsMode  (1-635) 

Returns  the  graphics  transfer  mode  for  an  imported  image. 

Graphi csImportSetQual  i  ty  (1-663) 

Sets  the  image  quality  value  for  an  imported  image. 

Graphi  csImportGetQuality  (1-643) 

Returns  the  image  quality  value  for  an  imported  image. 

Graphi  csImportSetSourceRect  (1-664) 

Sets  the  source  rectangle  to  use  for  an  imported  image. 

Graphi  csImportGetSourceRect  (1-645) 

Returns  the  current  source  rectangle  for  an  imported  image. 

Graphi  csImportSetProgressProc  (1-662) 

Installs  a  progress  procedure  to  call  while  drawing  an  imported  image. 

Graphi  csImportGetProgressProc  (1-643) 

Returns  the  current  progress  function  for  a  graphics  import  operation. 

Drawing  Imported  Images 

Functions  are  provided  to  determine  the  graphics  world  for  an  imported  graphics 
image  and  to  draw  it. 

These  functions  are  listed  below. 


Functions 

Graphi  csImportSetGWorl  d  (1-660) 

Sets  the  graphics  port  and  device  for  drawing  an  imported  image. 

Graphi  csImportGetGWorl  d  (1-636) 

Returns  the  current  graphics  port  and  device  for  drawing  an  imported  image. 
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Graphics  Import  Draw  (1-616) 

Draws  an  imported  image. 


Saving  Image  Files 

Graphics  import  components  can  save  data  in  several  formats,  including 
QuickDraw  pictures  and  QuickTime  Image  files.  This  capability  is  only  needed  by 
applications  that  perform  file  format  translation.  Applications  that  only  wish  to 
draw  the  image  can  use  Graphi  csImportDraw  (1-616). 
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Graphics  import  functions  for  saving  image  files  are  listed  below. 


Functions 

Graphi  csImportSaveAsPi  cture  (1-647) 

Creates  a  QuickDraw  picture  file  for  an  imported  image. 

Graphi  cs  Import SaveAsQui  ckTimelmageFi  1  e  (1-648) 

Creates  a  QuickTime  Image  file  of  an  imported  image. 

Graphi  csImportGetAsPi  cture  (1-618) 

Creates  a  QuickDraw  picture  handle  to  an  imported  image. 

Graphi  cs  Import  Export  ImageFi  1  e  (1-616) 

Saves  an  imported  image  in  a  foreign  file  format. 

Graphi  cs  ImportGetExportlmageTypeLi  st  (1-632) 

Returns  information  about  available  export  formats  for  a  graphics  importer. 

Graphi  cs  Import  Do  Export  ImageFi  1  eDi  a  1  og  (1-614) 

Presents  a  dialog  box  letting  the  user  save  an  imported  image  in  a  foreign  file 
format. 

Graphi cs I mportGet Export Sett i ngsAsAtomContai  ner (1-633) 

Retrieves  settings  for  image  files  exported  by  the  graphics  importer. 

Graphi cs Import Set Export Sett i ngsFromAtomContai  ner (1-657) 

Determines  settings  for  the  export  of  imported  image  files. 

Getting  MIME  Types 

Your  graphics  import  component  can  support  MIME  types  that  correspond  to 

graphics  formats  it  supports. 
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To  make  a  list  of  these  MIME  types  available  to  applications  or  other  software,  it 
must  implement  Graphi  cs  ImportGetMIMETypeLi  st  (1-641). 


Functions 

Graphi  csImportGetMIMETypeLi  st  (1-641) 

Returns  a  list  of  MIME  types  supported  by  the  graphics  importer  component. 


Specifying  a  Graphics  Import  Data  Source 

Graphics  importer  components  use  QuickTime  data  handler  components  to  obtain 
their  data.  Applications,  however,  will  use  the  graphics  importer  component 
functions  described  in  this  section,  rather  than  directly  calling  a  data  handler.  These 
functions  allow  the  data  source  to  be  a  file,  a  handle,  or  a  QuickTime  data  reference. 

You  do  not  need  to  call  the  functions  in  this  section  if  you  use  one  of  the 
GetGraphi  cslmporter  functions.  The  GetGraphi  cslmporter  functions  automatically 
set  the  graphics  importer  component's  data  source.  You  only  need  to  use  these 
functions  if  you  open  the  graphics  importer  component  directly. 


Functions 

Graphi  csImportSet  Da  taFile  (1-651) 

Specifies  the  file  that  contains  imported  graphics  data. 

Graphi  csImportGetDataFile  (1-621) 

Returns  the  file  containing  the  graphics  data  for  an  imported  image. 

Graphi csImportSetDataHandle  (1-652) 

Specifies  the  handle  that  references  imported  graphics  data. 

Graphi  csImportGetDataHandle  (1-623) 

Returns  a  handle  to  imported  graphics  data. 

Graphi  csImportSet  Data  Reference  (1-653) 

Specifies  the  data  reference  for  imported  graphics  data. 

Graphi  cslmport  Get  Data  Reference  (1-626) 

Returns  a  data  reference  to  imported  graphics  data. 

Graphi  csImportSetDataReferenceOffsetAndLi  mi  t  (I — 654) 

Specifies  the  data  reference  starting  offset  and  data  size  limit  for  an  imported 
image. 
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Graphi  cs  ImportGetDataReferenceOf  f  set  And  Li  mi  t  (1-627) 

Returns  the  data  reference  starting  offset  and  data  size  limit  for  an  imported 
image. 


Retrieving  Graphics  Import  Image  Data 

A  function  is  used  by  format-specific  graphics  import  components  to  read  data  from 
the  data  source.  It  is  implemented  by  the  base  graphics  importer. 

This  function  is  listed  below. 


Function 


Graphi  cs  ImportReadData  (1-645) 
Reads  imported  image  data. 


SUM 


Using  Graphics  Exporters 


Graphics  exporter  components  provide  a  standard  interface  for  exporting  graphics 
to  image  files  in  a  variety  of  formats. 

Setting  the  Input  and  Output  of  a  Graphics  Exporter  Instance 

One  function  is  used  to  perform  an  export  operation. 

This  function  is  listed  below. 


Function 


Graphi  csExportDoExport  (1-554) 

Performs  a  graphics  export  operation. 


Internal  Graphics  Export  Routines 

Certain  functions  are  used  for  internal  communication  between  the  base  and 
format-specific  graphics  exporter.  Applications  will  not  usually  need  to  call  them. 
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These  functions  are  listed  below. 


Functions 

Graph i  csExportCanT ranscode  (1-552) 

Asks  whether  the  current  graphics  export  operation  should  be  performed  by 
transcoding. 

Graph i  csExportDoT ranscode  (1-555) 

Performs  a  graphics  export  operation  by  transcoding. 

Graph i  csExportCanUseCompressor  (1-553) 

Asks  whether  to  use  a  compressor  in  a  graphics  export  operation. 

Graph i  csExportDoUseCompressor  (1-556) 

Performs  a  graphics  export  operation  with  compression. 

Graph  i  csExportDoStandal  one  Export  (1-554) 

Performs  a  standalone  graphics  export  operation. 

Finding  Out  About  Graphics  Export  Image  Formats 

Certain  functions  return  information  about  the  image  format  supported  by  a 
graphics  exporter.  Format-specific  exporters  must  implement  all  three  of  these 
functions. 

These  functions  are  listed  below. 

Functions 

Graph i  csExportGetDefaul  t  F 1 1  eTypeAndCreator  (1-561) 

Returns  the  suggested  file  type  and  creator  for  a  graphics  export  operation. 

Graph  i  csExportGetDefaul  t  F  i  1  e  Name  Ext  en  si  on  (1-560) 

Returns  the  suggested  file  name  extension  for  a  graphics  export  operation. 

Graph i  csExportGetMIMETypeLi  st  (1-577) 

Returns  MIME  types  and  other  information  about  the  graphics  format  in  a 
graphics  export  operation. 


V-2884 


Inside  QuickTime:  Programming  Summary 


Obtaining  Graphics  Exporter  Settings 


Certain  functions  are  used  for  obtaining  graphics  exporter  settings  and  displaying 
a  settings  dialog  box. 

These  functions  are  listed  below. 


Functions 


Graphi  csExportRequestSetti  ngs  (1-588) 

Displays  a  dialog  for  the  user  to  configure  graphics  exporter  settings,  if 
applicable. 

Graphi  csExportSetSetti ngsFromAtomContai ner  (1-610) 

Sets  the  graphics  exporter  component's  current  configuration  to  match  the 
settings  in  a  passed  atom  container. 

Graphi  csExportGetSetti ngsAsAtomContai ner  (1-583) 

Retrieves  the  current  settings  from  a  graphics  exporter  component. 

Graphi  csExportGetSetti  ngsAsText  (1-584) 

Retrieves  the  current  settings  from  the  graphics  export  component  in  a 
user-readable  format. 
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Accessing  Graphics  Exporter  Settings 

Graphics  exporters  may  implement  some  or  none  of  the  functions  listed  below. 

To  determine  whether  a  particular  setting  is  available,  use  Cal  1  ComponentCanDo 
(1-58). 


Functions 


Graphi  csExportSetDontRecompress  (1-592) 

Requests  that  the  original  compressed  data  for  a  graphics  export  operation  not 
be  decompressed  and  recompressed,  but  be  copied  through  to  the  output  file. 

Graphi  csExportGetDontRecompress  (1-562) 

Determines  whether  the  original  compressed  data  for  a  graphics  export 
operation  will  not  be  decompressed  and  recompressed,  but  be  copied  through 
to  the  output  file. 

Graphi  cs  Export  Set  I  nterl  aceStyl  e  (1-603) 

Defines  the  interlace  style  for  a  graphics  export  operation. 
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Graph i  csExportGetlnterl  aceStyl  e  (1-575) 

Returns  the  interlace  style  in  a  graphics  export  operation. 

Graph i  csExportSetMetaData  (I — 604) 

Defines  supplemental  data  for  a  graphics  export  operation,  such  as  copyright 
text. 

Graph  i  cs  Export  Get  Met  a  Data  (1-576) 

Returns  the  current  user  data  setting  in  a  graphics  export  operation. 

Graph i  csExportSetTargetDataSi  ze  (1-611) 

Defines  a  desired  maximum  data  size  for  a  graphics  export  operation  and  asks 
for  a  quality  that  does  not  exceed  that  size. 

Graph i csExportGetTargetDataSi ze  (1-585) 

Returns  the  current  desired  maximum  data  size  for  a  graphics  export  operation. 

Graph  i  cs  Export  Set  Comp  res  si  onMethod  (1-589) 

Defines  the  compression  method  to  use  in  a  graphics  export  operation. 

Graph  i  cs  Export  Get  Comp  res  si  onMethod  (1-559) 

Returns  the  compression  method  for  a  graphics  export  operation. 

Graphi  csExportSetCompressi  onQual  i  ty  (1-590) 

Defines  the  compression  quality  for  a  graphics  export  operation. 

Graphi  cs  Export  Get  Comp  res  si  onQual  i  ty  (1-559) 

Returns  the  compression  quality  value  for  a  graphics  export  operation. 

Graphi  cs  Export  Set  Resol  uti  on  (1-609) 

Defines  the  resolution  to  store  in  the  image  file  for  a  graphics  export  operation. 

Graphi  cs  Export  Get  Resol  uti  on  (1-583) 

Determines  the  resolution  of  a  graphics  exporter  component. 

Graphi csExportSetDepth  (1-591) 

Defines  the  depth  to  use  in  a  graphics  export  operation. 

Graphi  csExportGetDepth  (1-562) 

Returns  the  current  depth  setting  for  a  graphics  export  operation. 

Graphi  cs  Export  Set  Col  orSyncProfile  (1-589) 

Sets  the  ColorSync  profile  to  embed  in  the  image  file  for  a  graphics  export 
operation. 

Graphi  cs  Export  Get  Col  orSyncProfile  (1-558) 

Gets  the  current  value  of  the  ColorSync  profile  for  a  graphics  export  operation. 
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Getting  and  Setting  Progress  Procs 


Functions  for  getting  and  setting  progress  callbacks  are  always  implemented  by  the 

base  graphics  exporter. 

These  functions  are  listed  below. 


Functions 

Graphi  csExportSetProgressProc  (1-608) 

Installs  a  progress  function  in  a  graphics  export  operation. 

Graphi  csExportGetProgressProc  (1-582) 

Returns  the  current  progress  function  for  a  graphics  export  operation. 
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Specifying  Sources  for  Graphics  Exporter  Input  Images 

You  must  specify  an  input  image  source  before  you  can  call  Graphi  cs  Export  Do  Export 
(1-554).  The  source  can  be  a  QuickTime  graphics  importer  component  instance,  a 
QuickDraw  Picture  (IV-2331),  a  graphics  world,  or  a  pixel  map.  Or  it  can  be  apiece 
of  compressed  data  described  by  an  image  description.  Compressed  data  can  be  in 
a  file,  handle,  pointer,  or  other  data  reference.  The  application  must  make  sure  that 
the  source  is  not  disposed  of  before  the  graphics  exporter  instance  is  closed  or  given 
a  new  source. 

All  of  the  functions  listed  below  are  implemented  by  the  base  graphics  exporter. 
Format-specific  importers  should  delegate  all  of  them 


Functions 

Graphi  csExportSetlnputDataReference  (1-593) 

Specifies  that  the  source  image  for  a  graphics  export  operation  is  a  compressed 
image  stored  in  a  data  reference. 

Graphi  csExportGetlnputDataReference  (1-563) 

Returns  the  current  input  data  reference  for  a  graphics  export  operation. 

Graphi  cs  Export  Set  I  nputFi  1  e  (1-594) 

Specifies  that  the  source  image  for  a  graphics  export  operation  is  a  compressed 
image  stored  in  a  file. 

Graphi  cs  Expo rtGet  I  nputFi  1  e  (1-565) 

Returns  the  current  input  file  for  a  graphics  export  operation. 
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Graph i  cs Expo rtSet I nputHandl  e  (1-597) 

Specifies  that  the  source  image  for  a  graphics  export  operation  is  a  compressed 
image  referenced  by  a  handle. 

Graph i  cs Expo rtGet I nputHandl  e  (1-568) 

Returns  the  current  input  handle  for  a  graphics  export  operation. 

Graph i cs Expo rtSet I nputPtr  (1-602) 

Specifies  that  the  source  image  for  a  graphics  export  operation  is  a  compressed 
image  stored  at  a  fixed  address  in  memory. 

Graph i  cs Expo rtGet I nputPtr  (1-574) 

Returns  the  current  input  pointer  in  a  graphics  export  operation. 

Graph i  csExportSetlnputGraphi  cslmporter  (1-595) 

Specifies  that  the  source  image  for  a  graphics  export  operation  is  to  be  drawn 
by  a  graphics  importer  instance. 

Graph i  cs Expo rtGet I nputGraphi  cslmporter  (1-566) 

Returns  the  current  input  graphics  importer  instance  for  a  graphics  export 
operation. 

Graph  i  cs  Expo  rtSet  Input  Pi  cture  (1-599) 

Specifies  that  the  source  image  for  a  graphics  export  operation  is  a  picture. 

Graph  i  cs  Expo  rtGet  Input  Pi  cture  (1-572) 

Returns  the  current  input  picture  in  a  graphics  export  operation. 

Graph  i  cs  Expo  rtSet  I  nputGWorl  d  (1-596) 

Specifies  that  the  source  image  for  a  graphics  export  operation  is  a  graphics 
world. 

Graph  i  cs  Expo  rtGet  I  nputGWorl  d  (1-567) 

Returns  the  current  input  graphics  world  for  a  graphics  export  operation. 

Graph  i  cs  Expo  rtSet  Input  Pi  xmap  (1-600) 

Specifies  that  the  source  image  for  a  graphics  export  operation  is  a  pi  xmap. 

Graph  i  cs  Expo  rtGet  Input  Pi  xmap  (1-573) 

Returns  the  current  input  pi  xmap  in  a  graphics  export  operation. 

Restricting  the  Range  of  an  Input  Image's  Source 

Certain  functions  restrict  the  range  of  the  input  image  source  for  a  graphics 
exporter. 
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The  functions  listed  below  are  only  applicable  when  the  input  is  a  data  reference, 
file,  handle,  or  pointer. 


Functions 

Graphi  cs  Export  Set  In  put  Of  f  set  And  Li  mi  t  (1-598) 

Specifies  the  portion  of  an  input  data  reference,  file,  handle  or  pointer  that  a 
graphics  exporter  is  permitted  to  read. 

Graphi  csExportGetlnputOf  f  set  And  Li  mi  t  (1-572) 

Retrieves  the  current  input  offset  and  limit  in  a  graphics  export  operation. 
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Reading  Graphics  Exporter  Input  Data 

Certain  functions  read  the  input  data  for  graphics  exporters. 

These  functions  are  used  by  format-specific  graphics  exporters  when  transcoding. 
Applications  will  not  normally  need  to  call  them. 


Functions 


Graphi  csExportMayExporterReadlnputData  (1-585) 

Asks  whether  the  image  source  for  a  graphics  export  operation  is  in  a  form  that 
the  exporter  can  read. 

Graphi  csExportGetlnputDataSi  ze  (1-564) 

Returns  the  number  of  bytes  of  original  image  data  that  can  be  read  in  a 
graphics  export  operation. 

Graphi  csExportReadlnputData  (1-586) 

Reads  the  original  image  data  in  a  graphics  export  operation. 


Accessing  a  Graphics  Exporter's  Input  Image 

Certain  functions  are  used  by  format-specific  graphics  exporters  to  access  input 
images. 

When  doing  a  standalone  export,  an  exporter  will  typically  call 
Graphi csExportGetlnputlmageDescri pti  on  (1-570)  or 

Graphi csExportGetlnput ImageDi men si  on s  and  Graphi  csExportGetlnput ImageDepth 
(1-569)  to  determine  the  image's  bounds  and  depth,  and  then  allocate  an  offscreen 
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graphics  world  and  call  Graphi  csExportDrawInputlmage  (1-557)  to  draw  portions  of 
the  image  into  that  world. 


Functions 

Graphi  csExportGetlnputlmageDescri  pti  on  (1-570) 

Returns  an  image  description  describing  the  input  image  in  a  graphics  export 
operation. 

Graphi  csExportGetlnputlmageDi  men  si  on  s  (1-571) 

Returns  the  dimensions  of  the  input  image  in  a  graphics  export  operation. 

Graphi csExportGetlnputlmageDepth  (1-569) 

Returns  the  depth  of  the  input  image  for  a  graphics  export  operation. 

Graphi  csExportDrawInputlmage  (1-557) 

Draws  a  rectangular  portion  of  the  input  image  in  a  graphics  export  operation. 

Specifying  Destinations  for  Output  Images 

Certain  functions  are  used  to  specify  destinations  for  graphics  exporter  output 
images. 

These  functions  are  listed  below. 

Functions 

Graphi  cs  Expo  rtSetOutput  Data  Reference  (I — 604) 

Returns  the  current  output  data  reference  for  a  graphics  export  operation. 

Graphi  cs  Expo  rtGetOutput  Data  Reference  (1-578) 

Gets  the  output  data  reference  handle  in  a  graphics  export  operation. 

Graphi  cs  Expo  rtSetOutput  Fi  1  e  (1-605) 

Defines  the  output  file  for  a  graphics  export  operation. 

Graphi  cs  Expo  rtGetOutput  Fi  1  e  (1-578) 

Returns  the  current  output  file  for  a  graphics  export  operation. 

Graphi  csExportSetOutputHandl  e  (1-606) 

Sets  a  handle  to  the  output  of  a  graphics  export  operation. 

Graphi  csExportGetOutputHandl  e  (1-580) 

Returns  the  current  output  handle  for  a  graphics  export  operation. 
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Graphi csExportSetOutputOffsetAndMaxSi ze  (1-608) 

Specifies  the  output  starting  offset  and  maximum  size  limit  for  a  graphics 
export  operation. 

Graphi csExportGetOutputOffsetAndMaxSi ze  (1-581) 

Returns  the  output  starting  offset  and  maximum  size  limit  for  a  graphics  export 
operation. 

Graphi  csExportSetOutputFi 1 eTypeAndCreator  (1-606) 

Sets  the  file  type  and  creator  codes  for  the  output  file  of  a  graphics  export 
operation. 
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Graphi  csExportGetOutputFi  1  eTypeAndCreator  (1-579) 

Gets  the  type  and  creator  codes  for  the  output  file  in  a  graphics  export 
operation. 


Writing  Graphics  Exporter  Output  Data 

Certain  functions  are  used  by  format-specific  graphics  exporters  to  write  output 
data. 

These  functions  are  listed  below. 


Functions 

Graphi  csExportWri  teOutputData  (1-611) 

Writes  output  image  data  in  a  graphics  export  operation. 

Graphi  csExportSetOutputMark  (1-607) 

Seeks  to  the  specified  file  position  in  a  graphics  export  operation. 

Graphi  csExportGetOutputMark  (1-580) 

Returns  the  current  file  position  for  a  graphics  export  operation. 

Graphi  csExportReadOutputData  (1-587) 

Reads  output  image  data  in  a  graphics  export  operation. 
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Using  Video  Outputs 


Video  output  components  provide  an  interface  for  sending  QuickTime  video  to 
devices  that  are  not  recognized  as  video  displays  by  a  computer's  operating  system. 
Any  software  that  presents  video  data  can  be  a  client  of  a  video  output  component. 


Controlling  the  Video  Output  Display  Mode 

Each  video  output  device  has  a  finite  number  of  display  modes.  Each  mode  has 
several  characteristics,  including  width  and  height  of  the  display,  pixel  depth,  and 
video  refresh  rate. 

To  get  a  list  of  the  display  modes  supported  by  a  video  output  component,  call 
QTVi  deoOutputGetDi  spl  ayModeLi  st  (11-1326).  The  list  is  a  QT  atom  container,  and  list 
atoms  contain  the  characteristics  of  each  mode.  To  specify  a  display  mode  to  use, 
call  QTVi  deoOutputSetDi  spl  ayMode  (11-1332).  To  find  out  the  current  display  mode, 
call  QTVi  deoOutputGetDi  spl  ayMode  (11-1325). 


Functions 

QTVi  deoOutputGetDi  spl  ayModeLi  st  (11-1326) 

Returns  a  list  of  the  display  modes  supported  by  a  video  output  component. 

QTVi  deoOutputSetDi  spl  ayMode  (11-1332) 

Specifies  the  display  mode  to  be  used  by  a  video  output  component. 

QTVi  deoOutputGetDi  spl  ayMode  (11-1325) 

Returns  the  current  display  mode  for  a  video  output  component. 


Registering  the  Name  of  Video  Output  Software 

Several  functions  help  you  register  the  name  of  your  video  output  component. 

After  your  software  has  established  a  connection  to  a  video  output  component,  you 
can  register  its  name  with  the  instance  of  that  component  by  calling 
QTVi  deoOutputSetCl  i  entName  (11-1332).  The  name  can  then  be  used  by 
QTVi  deoOutputGetCurrentCl  i  entName  (11-1325)  to  specify  which  software  has 
exclusive  access  to  the  video  output  device  controlled  by  the  component.  To  get  the 
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name  of  the  application  or  other  software  that  is  registered  with  an  instance  of  a 
video  output  component,  call  QTVi  deoOutputGetCl  i  entName  (11-1323). 


Functions 


QTVi deoOutputSetCl  i entName  (11-1332) 

Registers  the  name  of  an  application  or  other  software  with  an  instance  of  a 
video  output  component. 

QTVi deoOutputGetCurrentCl  i entName  (11-1325) 

Returns  the  name  of  the  software,  if  any,  that  has  exclusive  access  to  the  video 
hardware  controlled  by  a  video  output  component. 

QTVi  deoOutputGetCl  i  entName  (11-1323) 

Obtains  the  name  of  the  application  or  other  software  that  is  registered  with  an 
instance  of  a  video  output  component. 
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Controlling  Video  Output 

Video  output  components  provide  functions  for  configuring  the  video  display,  for 
starting  and  stopping  video  output,  and  for  specifying  the  graphics  world  used  for 
the  display. 

To  display  a  dialog  box  in  which  the  user  can  specify  video  settings,  call 
QTVi  deoOutputCustomConf  i  gureDi  spl  ay  (11-1322).  To  get  a  pointer  to  the  graphics 
world  used  by  the  video  output  component,  call  QTVi  deoOutputGetGWorld  (II— 1 327) . 
Although  several  applications  or  other  software  can  connect  to  a  video  output 
component  at  the  same  time,  only  one  of  them  at  a  time  can  have  access  to  the  video 
output  device  controlled  by  the  component.  Use  QTVi  deoOutputBegi  n  (11-1321)  to 
gain  exclusive  access  to  the  video  output  device  and  QTVi  deoOutputEnd  (11-1322)  to 
relinquish  exclusive  access  when  your  software  has  finished  using  the  device.  If  a 
video  output  device  can  display  video  both  on  an  external  video  display  and  in  a 
window  on  a  computer's  desktop,  you  can  use  QTVi  deoOutputSetEchoPort  (11-1333) 
to  specify  a  window  on  the  desktop  in  which  to  display  video  sent  to  the  device. 


Functions 

QTVi  deoOutputCustomConf  i  gureDi  spl  ay  (11-1322) 

Displays  a  custom  video  configuration  dialog  box,  which  can  include  settings 
that  are  specific  to  the  video  device  controlled  by  the  video  output  component. 

QTVi  deoOutputGetGWorld  (11-1327) 

Returns  a  pointer  to  the  graphics  world  used  by  a  video  output  component. 
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QTVi  deoOutputGetGWorldParameters  (11-1328) 

Called  by  the  base  video  output  component  as  part  of  its  implementation  of 
QTVi  deoOutputGetGWorl  d  (11-1327). 

QTVi  deoOutputBegi  n  (II — 1321) 

Obtains  exclusive  access  to  the  video  hardware  controlled  by  a  video  output 
component. 

QTVi  deoOutputEnd  (11-1322) 

Releases  access  to  the  video  hardware  controlled  by  a  video  output  component. 
QTVi  deoOutputSetEchoPort  (11-1333) 

Specifies  a  window  on  the  desktop  in  which  to  display  video  sent  to  the  device. 


Finding  Components  Associated  With  a  Video  Output 

Video  output  components  provide  functions  for  finding  other  components 
associated  with  them. 

To  find  any  sound  output  components  associated  with  a  video  output  component, 
call  QTVi  deoOutputGetlndSoundOutput  (11-1329).  To  find  a  clock  component 
associated  with  a  video  output  component,  call  QTVi  deoOutputGetCl  ock  (11-1324). 


Functions 


QTVi  deoOutputGetlndSoundOutput  (11-1329) 

Determines  which  sound  output  components  are  associated  with  the  video 
output  component. 

QTVi  deoOutputGetCl  ock  (11-1324) 

Returns  a  pointer  to  the  clock  component  associated  with  the  video  output 
component. 


Saving  and  Restoring  Component  Configurations 

Video  output  components  provide  functions  for  saving  the  current  configuration  of 
a  video  output  component  and  later  restoring  the  configuration. 

To  save  the  current  configuration  of  a  video  output  component,  call 

QTVi  deoOutputSaveState  (11-1331).  To  restore  a  previously  saved  configuration  of  a 

video  output  component,  call  QTVi  deoOutputRestoreState  (11-1330). 
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Functions 


QTVi deoOutputSaveState  (11-1331) 

Saves  state  information  for  an  instance  of  a  video  output  component. 

QTVi deoOutputRestoreState  (11-1330) 

Restores  the  previously  saved  state  of  a  video  output  component. 


Using  the  Standard  Sound  Dialog 


The  standard  sound  dialog  component  is  a  QuickTime  component  with  an  API  for 
configuring  sound  settings. 
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Managing  the  Sound  Dialog 

The  standard  sound  dialog  component  implements  three  functions  from  the 
standard  compression  component  interface. 

These  functions  are  listed  below. 


Functions 

SCGetlnfo  (III— 1545) 

Retrieves  configuration  information  from  the  standard  dialog  component. 
SCSetlnfo  (III— 1558) 

Modifies  the  standard  dialog  component's  configuration  information. 
SCRequestlmageSetti  ngs  (III — 1 555) 

Displays  the  standard  image  dialog  box  to  the  user  and  shows  default  settings 
you  have  established. 

See  Also 

See  "Using  Image-Compression  Dialogs"  (V-2800). 


Sound  Dialog  Selectors 


Several  sound  constants  are  in  the  list  of  selectors  that  can  be  passed  to  SCGetlnfo 
(III— 1545)  and  SCSetlnfo  (III— 1558).  These  selectors  are  only  supported  by  the 
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standard  sound  dialog  component,  not  the  standard  image-compression  dialog 
component. 

These  selectors  are  listed  below. 


Constants 


scSoundSampleRateType 

A  pointer  to  an  Unsi  gnedFi  xed  value  that  represents  the  current  sample  rate. 
scSoundSampleSizeType 

A  pointer  to  a  short  integer  that  represents  the  current  sample  size.  This  value 
is  either  8  or  16. 

scSoundChannelCoun tType 

A  pointer  to  a  short  integer  that  represents  the  current  number  of  channels.  This 
value  is  either  1  or  2. 

scSoundCompressi onType 

A  pointer  to  a  value  of  type  OS  Type  that  represents  the  current  compression 
type.  This  value  is  either  kRawCodecType  or  one  of  the  available  sound 
compression  formats. 

scCompressi on  Lis tType 

A  pointer  to  a  handle  containing  an  array  of  values  of  type  OS  Type  that  indicate 
the  sound  compression  formats  that  may  be  presented  to  the  user.  Pass  N I L  to 
SCSetlnfo  to  reset  the  list  to  all  available  sound  compression  formats. 

scPreferenceFlagsType 

The  only  flag  that  is  supported  in  the  preferences  is  scUseMovableModal.  All 
other  flags  should  be  set  to  zero.  The  preference  flags  are  initialized  to 
scUseMovabl  eModal  when  the  standard  sound  dialog  component  is  instantiated. 

scExtendedProcsType 

The  only  fields  supported  are  f  i  1  terProc  and  ref  con.  All  other  fields  should  be 
initialized  to  zero.  The  filter  procedure  should  only  be  used  to  update 
background  windows.  It  should  not  be  used  to  intercept  user  interactions  in  the 
dialog  box  window  itself. 

scSettingsStateType 

This  selector  is  supported  in  the  same  way  as  in  the  standard 
image-compression  component. 
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Working  With  Video  Effects 


QuickTime  video  effects  are  implemented  as  specialized  image  decompressor 
components.  For  more  information  about  implementing  image  decompressor 
components,  see  "Managing  Image  Compression"  (V-2786).  To  use  an  effect 
component  in  a  QuickTime  movie,  you  add  an  effect  track  to  the  movie.  The  size 
and  duration  of  the  track  determines  the  area  of  the  movie  that  is  affected  and  how 
long  the  effect  runs. 
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High-Level  Effects  Functions 

Certain  functions  give  you  high-level  pre-packaged  access  to  video  effects  .  These 
functions  are  designed  to  be  easy  to  use  and  give  you  access  to  the  most  common 
uses  of  the  QuickTime  video  effects  architecture. 

These  functions  are  listed  below. 


Functions 

QTGetEffectsLi  st  (11-1174) 

Returns  a  QT  atom  container  holding  a  list  of  the  currently  installed  effects 
components. 

QTCreateStandardParameterDi  al  og  (11-1161) 

Creates  a  dialog  box  that  allows  the  user  to  choose  an  effect  from  the  list  of 
effects  passed  to  the  function. 

QTIsStandardParameterDi  al  ogEvent  (11-1186) 

Determines  if  a  Macintosh  event  is  processed  by  a  standard  parameter  dialog 
box  created  by  QTCreateStandardParameterDi  al  og  (11-1161). 

QTDi  smi  ssStandardParameterDi  al  og  (11-1163) 

Closes  a  standard  parameter  dialog  box  that  was  created  using 
QTCreateStandardParameterDi  al  og  (11-1161). 

QTStandardParameterDi  al  ogDoActi  on  (11-1313) 

Lets  you  change  some  of  the  default  behaviors  of  the  standard  parameter  dialog 
box. 

QTGetEf fectSpeed  (11-1176) 

Returns  the  speed  of  the  effect,  expressed  in  frames  per  second. 
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Low-Level  Effects  Functions 


Certain  functions  provide  more  complex  and  comprehensive  interfaces  to  the 
effects  dialog  functionality.  Using  the  low-level  functions,  you  can  gain  more 
control  over  the  standard  parameters  dialog  box,  such  as  the  ability  to  incorporate 
user  interface  elements  from  the  dialog  box  into  your  own  application-defined 
dialog  box. 

These  functions  are  listed  below. 


Functions 

ImageCodecGetParameterList  (11-717) 

Returns  a  parameter  description  atom  container  for  a  specified  effect 
component  instance. 

ImageCodecCreateStandardParameterDialog  (11-692) 

Creates  a  parameters  dialog  box  for  a  specified  effect. 

ImageCodecIsStandardParameterDialogEvent  (11-726) 

Processes  events  related  to  a  standard  parameters  dialog  box  created  by 
ImageCodecCreateStandardParameterDi  al  og  (11-692). 

ImageCodecStandardParameterDial  ogDoActi  on  (11-740) 

Allows  you  to  control  the  behavior  of  a  standard  parameter  dialog  box  created 
by  ImageCodecCreateStandardParameterDi  al  og  (11-692). 

ImageCodecDismissStandardParameterDialog  (11-695) 

Retrieves  values  from  a  standard  parameter  dialog  box  created  by  the  low-level 
ImageCodecCreateStandardParameterDi  al  og  (11-692)  function,  then  closes  the 
dialog  box. 


Creating  an  Effect  Sample  Description 

One  function  is  designed  to  create  a  sample  description  for  an  effect. 
This  function  is  listed  below. 


Functions 

MakelmageDescripti  on  For  Effect  (11-785) 

Returns  an  ImageDescription  (IV-2285)  structure  you  can  use  to  help  create  a 
sample  description  for  an  effect. 
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Working  With  the  Vector  Codec 


QuickTime  vectors  are  mathematical  descriptions  of  images  that  are  smaller  in  size 
than  their  equivalent  bitmaps  and  can  be  scaled  without  loss  of  image  quality.  A 
vector  QT  atom  container  specifies  the  characteristics  of  a  QuickTime  vector.  The 
container  contains  atoms  for  paths  and  can  also  contain  atoms  that  specify  attributes 
of  the  paths,  such  as  their  color. 


Vector  Codec  Component  Functions 
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Several  functions  are  provided  by  the  vector  codec  component. 
These  functions  are  listed  below. 


Functions 

CurveAddAtomToVectorStream  (1-151) 

Adds  an  atom  to  a  vector  data  stream. 

CurveAddPathAtomToVectorStream (1-152) 

Adds  a  path  to  a  vector  data  stream. 

CurveAddZeroAtomToVectorStream (1-152) 

Adds  a  kCurveEndAtom  to  a  vector  data  stream;  this  atom  marks  the  end  of  the 
vector  data  stream, 

CurveCountPointsInPath  (1-153) 

Counts  the  points  along  either  one  of  a  path's  contours  or  all  of  its  contours. 

CurveCreateVectorStream  (1-154) 

Creates  a  new,  empty  vector  data  stream. 

CurveGetAtomDataFromVectorStream  (1-154) 

Finds  the  first  atom  of  a  specified  type  within  a  vector  data  stream  and  get  its 
data. 

CurveGetLength  (1-155) 

Calculates  the  length  of  one  of  a  path's  contours  or  the  sum  of  the  lengths  of  all 
of  its  contours. 

CurveGetNearestPathPoi  nt  (1-156) 

Finds  the  closest  point  on  a  path  to  a  specified  point. 
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CurveGetPathPoi nt  (1-157) 

Obtains  a  point  from  a  path  and  to  find  out  if  the  point  is  on  the  curve. 

CurvelnsertPointlntoPath  (1-158) 

Adds  a  new  point  to  a  path. 

CurveLengthToPoi  nt  (1-159) 

Obtains  the  point  at  a  specified  distance  along  a  curve. 

CurveNewPath  (1-160) 

Creates  a  new  path. 

CurvePathPointToLength  (1-161) 

Obtains  the  length  of  a  path  between  specified  starting  and  ending  distances 
that  is  nearest  a  point. 

CurveSetPathPoi nt  (1-162) 

Changes  the  location  of  a  point  in  a  path. 


Working  With  the  Sprite  Toolbox 


The  Sprite  Toolbox  is  a  set  of  data  types  and  functions  you  can  use  to  add 
sprite-based  animation  to  an  application.  The  Sprite  Toolbox  composes  sprites  and 
their  background  in  an  offscreen  buffer,  invalidates  appropriate  screen  areas  as  sprite 
properties  change,  and  transfers  the  result  to  the  screen  or  to  an  alternate 
destination. 

If  you're  authoring  an  animation  outside  of  a  movie,  you  use  the  Sprite  Toolbox  to 
create  sprite  worlds  and  sprite  animations.  To  create  a  sprite  track  within  a 
QuickTime  movie,  you  create  media  samples  used  by  the  sprite  media  handler, 
which,  in  turn,  makes  use  of  the  Sprite  Toolbox. 


Working  with  Sprite  Worlds 

A  sprite  world  is  a  graphics  environment  populated  by  sprites  that  may  exist 
outside  of  movies.  The  Sprite  Toolbox  provides  several  functions  for  creating  and 
manipulating  sprite  worlds. 
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These  functions  are  listed  below. 


Functions 

NewSpri  teWorl  d  (11—1114) 

Creates  a  new  sprite  world. 

Di  sposeSpri  teWorl  d  (1-297) 

Disposes  of  a  sprite  world. 

SetSpri  teWorl  dCl  i  p  (III — 1 644) 

Sets  a  sprite  world's  clip  shape  to  the  specified  region. 

SetSpri  teWorl  dMatri  x  (III — 1 647) 

Sets  a  sprite  world's  matrix  to  the  specified  matrix. 

Spri  teWorl  dldl  e  (III — 1 908) 

Allows  a  sprite  world  to  update  its  invalid  areas. 

Inval  i  dateSpri  teWorl  d  (11-773) 

Invalidates  a  rectangular  area  of  a  sprite  world. 

Spri  teWorl  dHi  tTest  (III — 1907) 

Determines  whether  any  sprites  are  at  a  specified  location  in  a  sprite  world. 
Di  sposeAl  1  Spri  tes  (1-255) 

Disposes  of  all  sprites  associated  with  a  sprite  world. 
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Creating  and  Manipulating  Sprites 

The  Sprite  Toolbox  provides  several  functions  for  creating  and  manipulating 
sprites  in  sprite  worlds. 

These  functions  are  listed  below. 


Functions 

NewSpri  te  (11-1113) 

Creates  a  new  sprite  in  a  specified  sprite  world. 

Di  sposeSpri  te  (1-296) 

Disposes  of  a  sprite. 

Inval  i  dateSpri  te  (11-772) 

Invalidates  the  portion  of  a  sprite's  sprite  world  that  is  occupied  by  a  sprite. 
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Spri  teHi  tTest  (III — 1885) 

Determines  whether  a  location  in  a  sprite's  display  coordinate  system 
intersects  the  sprite. 

GetSpri  teProperty  (1-512) 

Retrieves  the  value  of  a  specified  sprite  property. 

SetSpri  teProperty  (III — 1 641) 

Sets  the  specified  property  of  a  sprite. 


Using  the  Sprite  Media  Handler 


The  sprite  media  handler  is  a  media  handler  you  can  use  to  add  a  sprite  animation 
track  to  a  QuickTime  movie.  It  provides  routines  for  manipulating  the  sprites  and 
images  in  a  sprite  track.  The  sprite  media  handler  makes  use  of  the  functionality 
provided  by  the  Sprite  Toolbox.  If  you  are  using  the  sprite  media  handler,  you  don't 
need  to  use  the  toolbox  API. 


Managing  Movie  Sprites 

The  sprite  media  handler  provides  several  functions  that  let  you  manage  sprites  in 
a  movie. 

These  functions  are  listed  below. 


Functions 

Spri  teMedi  aSetSpri  teProperty  (III — 1 904) 

Sets  the  specified  property  of  a  sprite. 

Spri  teMedi  aGetSpri  teProperty  (III — 1 896) 

Retrieves  the  value  of  the  specified  sprite  property. 

SpriteMediaHitTestAllSprites  (III — 1897) 

Determines  whether  any  sprites  are  at  a  specified  location. 

Spri  teMedi  aCountSpri  tes  (III — 1887) 

Retrieves  the  number  of  sprites  that  currently  exist  in  a  sprite  track. 
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Spri  teMedi  aCountlmages  (III — 1886) 

Retrieves  the  number  of  images  that  currently  exist  in  a  sprite  track. 

Spri  teMedi  aGetlndlmageDescri  pti  on  (III — 1891) 

Retrieves  an  image  description  for  a  specified  image  in  a  sprite  track. 

Spri  teMedi  aGetDi  spl  ayedSampl  eNumber  (III — 1 889) 

Retrieves  the  number  of  the  sprite  media  sample  that  is  currently  being 
displayed. 

Spri  teMedi  aGetSpri  teName  (III — 1 895) 

Returns  the  name  of  the  sprite  with  the  specified  ID  from  the  currently 
displayed  sample. 

Spri  teMedi  aGetlmageName  (III — 1890) 

Returns  the  name  of  the  image  with  the  specified  index  from  the  current  key 
frame  sample. 

Spri  teMedi  a H i  tTestOneSpri  te  (III — 1 898) 

Performs  a  hit  testing  operation  on  the  sprite  specified  by  a  spri  telD. 

Spri  teMedi  aSpri  telndexToID  (III — 1 906) 

Returns  the  ID  of  a  sprite  specified  by  a  sprite  index. 

Spri  teMedi  aSpri  telDToIndex  (III — 1 906) 

Converts  a  sprite  ID  to  the  corresponding  sprite  index. 

Spri  teMedi  aGetlndlmageProperty  (III — 1891) 

Returns  a  property  value  for  a  sprite  image  specified  by  an  index. 
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Working  With  Wired  Sprites 

A  wired  sprite  acts  like  a  button,  telling  other  software  when  the  user  has  clicked 
on  its  image  or  passed  the  cursor  over  it.  Two  functions  are  specific  to  sprite  tracks 
that  use  wired  sprites. 

These  functions  are  listed  below. 


Functions 

Spri  teMedi  aSetActi  onVari  abl  e  (III — 1901) 

Sets  the  value  of  a  sprite  track  variable  to  a  specified  value. 

Spri  teMedi  aGetActi  onVari  abl  e  (III — 1888) 

Returns  the  value  of  the  sprite  track  variable  with  the  specified  ID. 
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Working  With  Virtual  Reality 


QuickTime  VR  is  an  extension  of  the  QuickTime  technology  that  allows  users  to 
interactively  explore  and  examine  photorealistic,  three-dimensional  virtual  worlds. 
QuickTime  VR  is  presented  as  a  special  kind  of  QuickTime  movie,  displayed  by  the 
VR  movie  controller.  The  user  navigates  in  the  virtual  world  that  is  displayed  using 
standard  input  devices,  such  as  the  mouse  and  keyboard. 


Initializing  and  Terminating  QuickTime  VR 

The  QuickTime  VR  Manager  provides  two  functions  for  initializing  and 
terminating  its  operation.  These  functions  are  required  for  QuickTime  VR  to  run  in 
a  Windows  environment.  They  do  nothing  in  the  Mac  OS  environment,  but  should 
be  included  for  cross-platform  compatibility. 

These  functions  are  listed  below. 


Functions 


Ini  tializeQTVR  (11-758) 

Initializes  QuickTime  virtual  reality. 

Termi nateQTVR  (III— 1927) 

Terminates  QuickTime  VR  when  you  have  finished  using  its  functions. 


Managing  QuickTime  VR  Movie  Instances 

The  QuickTime  VR  Manager  provides  functions  for  obtaining  a  QTVR  track  and  a 
new  movie  instance. 

These  functions  are  listed  below. 


Functions 

QTVRGetQTVRT rack  (11-1375) 

Obtains  a  QTVR  track  contained  in  a  QuickTime  movie  to  use  in  the 
QTVRGetQTVRInstance  (11-1373)  call. 

QTVRGetQTVRInstance  (11-1373) 

Obtains  an  instance  of  a  QuickTime  VR  movie. 
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Manipulating  Viewing  Angles  and  Zooming 


The  QuickTime  VR  Manager  provides  functions  that  you  can  use  to  manipulate  the 
viewing  angles  and  zooming  characteristics  of  a  QuickTime  VR  movie.  Note  that 
the  parameters  to  these  functions  that  specify  angles  are  always  interpreted  in  the 
current  angular  unit  (degrees  or  radians)  set  by  a  previous  call  to 
QTVRSetAngul  arUni  ts  (11-1408).  The  default  angular  unit  is  degrees. 

These  functions  are  listed  below. 

Functions 
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QTVRGetPanAngl  e  (11-1373) 

Obtains  the  pan  angle  of  a  QuickTime  VR  movie. 

QTVRSetPanAngl  e  (11-1431) 

Sets  the  pan  angle  of  a  QuickTime  VR  movie. 

QTVRGetT i  1  tAngl  e  (11-1377) 

Obtains  the  tilt  angle  of  a  QuickTime  VR  movie. 

QTVRSetTil  tAngl  e  (11-1434) 

Sets  the  tilt  angle  of  a  QuickTime  VR  movie. 

QTVRGetFi  el  dOfVi  ew  (11-1360) 

Obtains  the  vertical  field  of  view  of  a  QuickTime  VR  movie. 

QTVRSetFi  el  dOfVi  ew  (11-1420) 

Sets  the  vertical  field  of  view  of  a  QuickTime  VR  movie. 

QTVRGetVi ewCenter  (11-1378) 

Obtains  the  view  center  of  a  QuickTime  VR  movie. 

QTVRSetVi ewCenter  (11-1437) 

Sets  the  view  center  of  a  QuickTime  VR  movie. 

QTVRNudge  (11-1402) 

Turns  one  step  in  a  particular  direction  and  displays  the  new  view. 
QTVRInteractl  onNudge  (11-1389) 

Translates  the  image  and  displays  the  new  view  or  rotates  the  object  in  a 
particular  direction  and  displays  its  new  appearance. 

QTVRShowDef  aul  tView  (11-1442) 

Displays  the  default  view  of  a  QTVR  node. 
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Getting  Scene  and  Node  Information 


The  QuickTime  VR  Manager  provides  functions  that  you  can  use  to  get  the  VR 
world  scene  description  atom  container  and  to  get  and  set  a  scene's  current  node. 

These  functions  are  listed  below. 


Functions 

QTVRGetVRWorl  d  (11-1385) 

Obtains  the  VR  world  atom  container  for  a  movie. 

QTVRGoToNodelD  (11-1386) 

Sets  the  current  node  of  a  movie. 

QTVRGet  Cur  rent  Node  ID  (11-1359) 

Obtains  the  current  node  of  a  movie. 

QTVRGetNodeType  (11-1372) 

Obtains  the  type  of  a  movie  node. 

QTVRGetNodelnfo  (11-1371) 

Obtains  the  node  information  atom  container  that  describes  a  node  and  all  the 
hot  spots  in  the  node. 

Managing  Hot  Spots 

The  QuickTime  VR  Manager  provides  functions  that  you  can  use  to  manage  the  hot 
spots  of  a  node. 

These  functions  are  listed  below. 


Functions 

QTVRPtToHotSpotID  (11-1405) 

Obtains  the  ID  of  the  hot  spot,  if  any,  that  lies  beneath  a  point. 

QTVRGet  Ho  tSpotType  (11-1364) 

Obtains  the  type  of  a  QuickTime  VR  hot  spot. 

QTVRTri ggerHotSpot  (11-1443) 

Triggers  a  QTVR  hot  spot. 

QTVREnabl  eHotSpot  (11-1340) 

Enables  or  disables  one  or  more  QTVR  hot  spots. 
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QTV  RSetMous  eO  ver  Hot  Spot  P  roc  (11-1429) 

Installs  or  removes  a  mouse  over  hot  spot  procedure. 

QTVRGetVi  si  bl  eHotSpots  (11—1384) 

Obtains  a  list  of  the  currently  visible  hot  spots  in  a  QuickTime  VR  movie. 

QTVRGetHotSpotRegi  on  (11-1363) 

Obtains  the  region  occupied  by  a  hot  spot. 


Handling  Events 
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The  QuickTime  VR  Manager  provides  a  number  of  functions  that  you  can  use  to 
handle  user  actions  such  as  moving  the  mouse  or  clicking  the  mouse  button. 
Normally,  QuickTime  VR  handles  all  user  interaction  internally  if  your  application 
calls  MCIsPl  ayerEvent  (11-819)  in  its  main  event  loop.  For  code  that  does  not  have  a 
main  event  loop,  you  might  need  to  override  QuickTime  VR's  mouse  event 
handling. 

These  functions  are  listed  below. 


Functions 

QTVRGetMouseOverT racki  ng  (11-1370) 

Obtains  the  current  state  of  mouse-over  tracking. 

QTV  RSetMous  eOverT  racki  ng  (11-1431) 

Sets  the  state  of  mouse-over  tracking. 

QTVRMouseEnter  (11-1392) 

Handles  the  user's  moving  the  cursor  into  a  QuickTime  VR  movie  for  which 
mouse-over  tracking  is  disabled. 

QTVRMouseWi  thi  n  (II — 1401) 

Handles  the  user's  leaving  the  cursor  in  a  QuickTime  VR  movie  for  which 
mouse-over  tracking  is  disabled. 

QTVRMouseLeave  (11-1394) 

Handles  the  user's  moving  the  cursor  out  of  a  QuickTime  VR  movie  for  which 
mouse-over  tracking  is  disabled. 

QTVRGetMouseDownT racki  ng  (11-1370) 

Obtains  the  current  state  of  mouse-down  tracking. 
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QTVRSetMouseDownT racking  (11-1429) 

Sets  the  state  of  mouse-down  tracking. 

QTVRMouseDown  (11-1391) 

Handles  the  user's  clicking  the  mouse  button  when  the  cursor  is  in  a  QuickTime 
VR  movie  for  which  mouse-down  tracking  is  disabled. 

QTVRMouseSti  1 1  Down  (11-1395) 

Handles  the  user's  holding  down  the  mouse  button  while  the  cursor  is  in  a 
QuickTime  VR  movie  for  which  mouse-down  tracking  is  disabled. 

QTVRMouseUp  (11-1398) 

Handles  the  user's  releasing  the  mouse  button  while  the  cursor  is  in  a 
QuickTime  VR  movie  for  which  mouse-down  tracking  is  disabled. 

QTVRMouseSti  1 1  DownExtended  (11-1396) 

Handles  the  user's  holding  down  the  mouse  button  while  the  cursor  is  in  a 
QuickTime  VR  movie  for  which  mouse-down  tracking  is  disabled. 

QTVRMouseUp  Ext  ended  (11-1399) 

Handles  the  user's  releasing  the  mouse  button  while  the  cursor  is  in  a 
QuickTime  VR  movie  for  which  mouse-down  tracking  is  disabled. 


Intercepting  QuickTime  VR  Manager  Routines 

The  QuickTime  VR  Manager  provides  functions  that  you  can  use  to  install  and  call 
intercept  procedures.  Your  intercept  procedure  can  provide  either  alternative  or 
additional  functionality  to  that  provided  by  the  intercepted  procedure. 

These  functions  are  listed  below. 


Functions 


QTVRInstal  1  InterceptProc  (11-1387) 

Installs  or  removes  an  intercept  procedure  for  a  QuickTime  VR  Manager 
function. 

QTVRCal  1  InterceptedProc  (11-1336) 

Calls  an  intercepted  QuickTime  VR  function  from  within  an  intercept 
procedure. 
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Managing  Object  Nodes 


The  QuickTime  VR  Manager  provides  functions  that  you  can  use  to  manage  object 
nodes  in  VR  object  movies. 

These  functions  are  listed  below. 


Functions 

QTVRGetCu i" rent Mous eMode  (11-1358) 

Obtains  the  current  mouse  control  modes. 

QTVRGetFrameRate  (11-1362) 

Obtains  the  current  frame  rate  of  an  object  node. 

QTVRSetFrameRate  (11-1421) 

Sets  the  frame  rate  of  an  object  node. 

QTVRGetVi ewRate  (11—1381) 

Obtains  the  current  view  rate  of  an  object  node. 

QTVRSetVi ewRate  (11-1439) 

Sets  the  view  rate  of  a  QTVR  object  node. 

QTVRGetCurrentVi  ewDurati  on  (11-1360) 

Obtains  the  duration  of  the  current  view  of  an  object  node. 

QTVRGetVi ewCurrentT i me  (11-1379) 

Obtains  the  current  time  in  the  current  view. 

QTVRSetVi  ewCurrentT i  me  (11-1438) 

Sets  the  time  in  the  current  QTVR  view. 

QTVRGetViewStateCount  (11-1383) 

Obtains  the  number  of  view  states  of  an  object  node. 

QTVRGetVi ewState  (11-1382) 

Obtains  the  value  of  a  view  state. 

QTVRSetVi  ewState  (11-1440) 

Sets  the  value  of  a  QTVR  view  state. 

QTVRGetAni mati  onSetti  ng  (II — 1344) 

Obtains  the  current  state  of  an  animation  setting  for  an  object  node. 

QTVRSetAni  mati  onSetti  ng  (11-1409) 

Sets  the  state  of  an  animation  setting  for  an  object  node. 
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QTVRGetControl  Setti  ng  (11-1355) 

Obtains  the  current  state  of  a  control  setting  for  an  object  node. 

QTVRSetControl  Setti  ng  (11-1416) 

Sets  the  state  of  a  control  setting  for  a  QTVR  object  node. 

QTVRGetFrameAnimation  (II — 1361) 

Obtains  the  current  state  of  frame  animation  for  an  object  node. 

QTVREnabl  eFrameAni  mati  on  (11-1339) 

Enables  or  disables  frame  animation  for  an  object  node. 

QTVRGetVi  ewAnimati  on  (11-1377) 

Obtains  the  current  state  of  view  animation  for  an  object  node. 

QTVREnabl  eVi  ewAnimati  on  (11-1342) 

Enables  or  disables  view  animation  for  an  object  node. 

Managing  Imaging  Characteristics 

The  QuickTime  VR  Manager  provides  functions  that  you  can  use  to  get  and  set 
various  imaging  characteristics  of  a  VR  movie. 

These  functions  are  listed  below. 


Functions 

QTVRGetVi  si  ble  (11-1384) 

Obtains  a  movie's  visibility  state. 

QTVRSetVi  si  bl  e  (11-1441) 

Sets  a  VR  movie's  visibility  state. 

QTVRGetlmagi ngProperty  (11-1365) 

Obtains  the  current  value  of  an  imaging  property  of  a  movie. 

QTVRSetlmagi ngProperty  (11-1422) 

Sets  the  value  of  an  imaging  property  of  a  movie. 

QTVRUpdate  (11-1445) 

Forces  an  immediate  update  of  a  QuickTime  VR  movie  image. 
QTVRBegi  nllpdateStream  (11-1335) 

Begins  a  stream  of  immediate  updates  to  a  QuickTime  VR  movie. 
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QTVREndllpdateStream  (11-1343) 

Ends  a  stream  of  immediate  updates  to  a  QuickTime  VR  movie. 

QTVRSetT ransi  ti  on  Property  (11-1435) 

Sets  the  value  of  a  transition  property. 

QTVREnabl  eTransi  ti  on  (11-1341) 

Enables  or  disables  a  transition  effect. 

Converting  Angles  and  Points 


SUM 


The  QuickTime  VR  Manager  provides  several  functions  that  you  can  use  to  convert 
mathematical  entities  and  perform  other  utility  operations. 

These  functions  are  listed  below. 


Functions 

QTVRGetAngul  arllni  ts  (11-1344) 

Obtains  the  type  of  unit  currently  used  when  specifying  angles. 

QTVRSetAngul  arllni  ts  (11-1408) 

Sets  the  type  of  unit  used  when  specifying  QTVR  angles. 

QTVRPtToAngl  es  (11-1404) 

Obtains  the  pan  and  tilt  angles  of  a  point. 

QTVRCoordToAngl  es  (11-1338) 

Get  the  pan  and  tilt  angles  of  a  floating-point  coordinate  in  a  panorama. 
QTVRAngl  esToCoord  (II — 1334) 

Obtains  a  floating-point  coordinate  determined  by  a  pair  of  pan  and  tilt  angles. 
QTVRPanToCol  umn  (11-1403) 

Obtains  the  column  number  in  the  object  image  array  that  corresponds  to  a  pan 
angle. 

QTVRCol  umnToPan  (11-1337) 

Get  the  pan  angle  that  corresponds  to  a  column  number  in  the  object  image 
array. 

QTVRTi  1  tToRow  (11-1443) 

Obtains  the  row  number  in  the  QTVR  object  image  array  that  corresponds  to  a 
tilt  angle. 
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QTVRRowToTilt  (11-1407) 

Obtains  the  tilt  angle  that  corresponds  to  a  row  number  in  a  QTVR  object  image 
array. 

QTVRWrapAndConstrai n  (11-1446) 

Preflights  a  change  in  the  viewing  or  control  characteristics  of  a  QTVR  object  or 
panoramic  node. 


Managing  QuickTime  VR  Movie  Interactions 

The  QuickTime  VR  Manager  provides  functions  that  you  can  use  to  augment  the 
normal  user  interaction  handling  provided  by  a  QuickTime  movie  controller. 

These  functions  are  listed  below. 


Functions 

QTVRSetEnteri ngNodeProc  (11-1419) 

Installs  or  removes  a  node-entering  procedure. 

QTVRSetLeavi ngNodeProc  (11-1428) 

Installs  or  removes  a  node-leaving  procedure. 

QTVRGet Interacti onProperty  (11-1368) 

Obtains  the  value  of  an  interaction  property. 

QTVRSetlnteracti onProperty  (11-1425) 

Sets  the  value  of  an  interaction  property. 

QTVRRepl  aceCursor  (11-1407) 

Replaces  any  of  the  standard  QuickTime  VR  cursors  with  your  own  custom 
cursor. 

Determining  Viewing  Limits  and  Constraints 

The  QuickTime  VR  Manager  provides  functions  that  you  can  use  to  get  the  physical 
viewing  limits  of  a  movie  and  to  get  and  set  a  movie's  constraints. 

These  functions  are  listed  below. 
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QTVRGetVi  ewi  ngLi  mi  ts  (11-1379) 

Obtains  the  current  viewing  limits  of  a  QuickTime  VR  movie. 

QTVRGetConstrai ntStatus  (11-1353) 

Obtains  the  set  of  constraints  active  for  the  current  view. 

QTVRGetConstrai nts  (11-1352) 

Obtains  the  current  constraints  of  a  QuickTime  VR  movie. 

QTVRSetConstrai nts  (11-1415) 

Sets  the  constraints  of  a  VR  movie. 

Managing  VR  Memory 

The  QuickTime  VR  Manager  provides  functions  that  you  can  use  to  help  manage 
the  memory  used  by  QuickTime  VR. 

These  functions  are  listed  below. 


SUM 


Functions 


QTVRGetAvai  1  abl  eResol  uti  ons  (11-1346) 

Obtains  the  image  resolutions  present  in  the  current  node. 

QTVRGetBackBuf ferMemlnf o  (11-1347) 

Obtains  information  about  the  internal  back  buffer  that  QuickTime  VR 
maintains  for  caching  panoramic  images. 

QTVRGetBackBuf ferSetti ngs  (11-1350) 

Obtains  information  about  the  resolution,  pixel  format,  and  size  of  the  back 
buffer  maintained  internally  by  QuickTime  VR  for  caching  a  panoramic  image 
in  a  particular  pixel  format. 

QTVRSetBackBuf ferPref s  (11-1412) 

Sets  the  resolution,  pixel  format,  and  size  of  the  back  buffer  maintained 
internally  by  QuickTime  VR  for  caching  a  panoramic  image  in  a  particular  pixel 
format. 
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Accessing  Image  Buffers 

The  QuickTime  VR  Manager  provides  functions  that  you  can  use  to  access  the  two 
internal  buffers  used  by  QuickTime  VR  when  it's  imaging  a  panorama. 

These  functions  are  listed  below. 


Functions 

QTVRSetPrescreenlmagi  ngCompl  eteProc  (11-1432) 

Installs  or  removes  a  prescreen  buffer  imaging  completion  procedure. 

QTVRSetBackBufferlmagi  ngProc  (11—1411) 

Installs  or  removes  a  QTVR  back  buffer  imaging  procedure. 

QTVRRef  reshBackBuffer  (11-1406) 

Refreshes  the  QTVR  back  buffer. 


Programming  Music 


The  QuickTime  music  architecture  (QTMA)  allows  QuickTime  movies, 
applications,  and  other  software  to  play  individual  musical  notes,  sequences  of 
notes,  and  a  broad  range  of  sounds  from  a  variety  of  instruments  and  synthesizers. 
With  QTMA,  you  can  also  import  Standard  MIDI  files  and  convert  them  into 
QuickTime  movies  for  easy  playback. 


Using  the  Tune  Player 

The  QTMA  tune  player  provides  functions  for  setting,  queueing,  and  manipulating 
music  sequences.  It  also  provides  certain  utility  functions. 

These  functions  are  listed  below. 


Functions 


TuneSetHeader  (III — 1 967) 

Prepares  the  tune  player  to  accept  subsequent  music  event  sequences  by 
defining  one  or  more  parts  to  be  used  by  sequence  Note  events. 
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TuneSetHeaderWi  thSi ze  (III — 1 968) 

Similar  to  T uneSetHeader  (III— 1967)  but  lets  you  specify  the  header  length. 

TuneSetNoteChannel  s  (III — 1 969) 

Assigns  note  channels  to  a  tune  player. 

TuneQueue  (III — 1 964) 

Places  a  sequence  of  music  events  into  a  queue  to  be  played. 

TuneStop  (III— 1975) 

Stops  a  currently  playing  sequence. 

TuneGetVol  lime  (III — 1 963) 

Returns  the  volume  associated  with  an  entire  tune  sequence. 

TuneSetVol  ume  (III — 1 974) 

Sets  the  volume  for  an  entire  sequence. 

TuneSetSoundLocal  i  zati  on  (III — 1 972) 

Passes  sound  localization  data  to  a  tune  player. 

TuneGetTimeBase  (III — 1 961) 

Returns  the  time  base  of  the  tune  player. 

TuneGetTimeScal  e  (III — 1 962) 

Returns  the  current  time  scale  for  a  specified  tune  player  instance. 
TuneSetTimeScal  e  (III — 1 973) 

Sets  the  time  scale  used  by  the  specified  tune  player  instance. 
TuneGetPartMix  (III — 1 960) 

Gets  volume,  balance,  and  mixing  settings  for  a  specified  part  of  a  tune. 
TuneSetPartMix  (III — 1 970) 

Sets  volume,  balance,  and  mixing  settings  for  a  specified  part  of  a  tune. 
Tunelnstant  (III — 1 963) 

Plays  a  particular  sequence  of  events  active  at  a  specified  position. 
TunePreroll  (III — 1 964) 

Prepares  to  play  a  tune  player  sequence  data  by  attempting  to  reserve  note 
channels  for  each  part  in  the  sequence. 

TuneUnroll  (III — 1 976) 

Releases  any  note  channel  resources  that  may  have  been  locked  down  by 
previous  calls  to  T unePrerol  1  (III— 1964)  for  this  tune  player. 
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T uneGetlndexedNoteChannel  (III — 1 958) 

Determines  how  many  parts  a  tune  is  playing  and  which  instrument  is  assigned 
to  those  parts. 

TuneGetStatus  (III — 1961) 

Returns  an  initialized  structure  describing  the  state  of  the  tune  player  instance. 

TuneSetPartTranspose  (III — 1 971) 

Modifies  the  pitch  and  volume  of  every  note  of  a  tune. 

TuneGetNoteAl  locator  (III — 1959) 

Returns  the  instance  of  the  note  allocator  that  the  tune  player  is  using. 
TuneSetSofter  (III — 1 972) 

Adjusts  the  volume  a  tune  is  played  at  to  the  softer  volume  produced  by 
QuickTime  2.1. 

TuneSetBal ance  (III — 1 966) 

Modifies  the  pan  controller  setting  for  a  tune  player. 

TuneTask  (III— 1975) 

Lets  a  tune  player  to  perform  tasks  it  must  perform  at  foreground  task  time. 

Allocating  and  Using  Note  Channels 

Several  QTMA  functions  create,  manipulate,  and  get  information  about  note 
channels. 

These  functions  are  listed  below. 


Functions 

NANewNoteChannel  (11-1030) 

Requests  a  new  note  channel  with  the  qualities  described  in  a  NoteRequest 
(IV-2323)  structure. 

NANewNoteChannel  FromAtomi  clnstrument  (II — 1031) 

Requests  a  new  note  channel  for  an  atomic  instrument. 

NADi sposeNoteChannel  (11-1020) 

Deletes  a  specified  note  channel. 

NAGetNoteChannel  Info  (11-1026) 

Returns  the  index  of  the  music  component  for  the  allocated  channel  and  its  part 
number  on  that  music  component. 
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NAGetlndNoteChannel  (11-1023) 

Returns  the  number  of  note  channels  handled  by  the  specified  note  allocator 
instance. 

NAUseDefaul  tMIDI  Input  (11-1052) 

Defines  an  entry  point  to  service  external  MIDI  device  events. 

NALoseDefaul  tMIDI  Input  (11-1029) 

Removes  the  external  default  MIDI  service  procedure  call,  if  previously  defined 
by  NAUseDefaul  tMIDI  Input  (11-1052). 

NAPreroll  NoteChannel  (11-1037) 

Attempts  to  reallocate  the  note  channel  if  it  was  invalid  previously. 

NAUnrol  1  NoteChannel  (11-1051) 

Marks  a  note  channel  as  available  to  be  stolen. 

NAResetNoteChannel  (11-1039) 

Turns  off  all  currently  "on"  notes  on  the  note  channel  and  resets  all  controllers 
to  their  default  values. 

NASetNoteChannel  Vol  ume  (11-1047) 

Sets  the  volume  on  the  specified  note  channel. 

NASetNoteChannel  Bal  ance  (11-1046) 

Modifies  the  pan  controller  setting  for  a  note  channel. 

NASetNoteChannel  Sound  Localization  (11-1047) 

Passes  sound  localization  data  to  a  note  channel. 

NAPlayNote  (11-1036) 

Plays  a  note  with  a  specified  pitch  and  velocity  on  the  specified  note  channel. 
NAGetControl  1  er  (11-1022) 

Retrieves  the  controller  settings  for  a  note  channel. 

NASetControl  1  er  (11-1042) 

Changes  the  controller  setting  on  a  note  channel  to  a  specified  value. 
NAGetKnob  (11—1024) 

Obtains  the  value  of  a  knob  for  a  given  note  channel. 

NASetKnob  (11-1045) 

Sets  a  note  channel  knob  to  a  particular  value. 
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NAFindNoteChannelTone  (II — 1 021) 

Locates  the  instrument  that  best  fits  a  requested  tone  description  for  a  specific 
channel. 

NASetlnstrumentNumber  (11-1044) 

Initializes  initializes  a  synthesizer  part  with  the  specified  instrument. 

NASetlnstrumentNumber  Inter  r  up  t  Safe  (11-1044) 

Initializes  a  synthesizer  part  with  the  specified  instrument  during  interrupt 
time. 

NASetAtomi  clnstrument  (11-1041) 

Initializes  a  synthesizer  part  with  an  atomic  instrument. 

NASendMIDI  (11-1040) 

Sends  a  MIDI  music  packet  to  a  synthesizer  that  contains  a  specific  note 
channel. 

NAGetNoteRequest  (11-1027) 

Retrieves  the  Note  Request  (IV-2323)  structure  that  was  passed  to  a  note  channel. 

Note  Allocator  Interface  Tools 

Several  QTMA  functions  provide  a  user  interface  for  instrument  selection  and 
presentation  of  copyright  information. 

These  functions  are  listed  below. 


Functions 

NAPi  cklnstrument  (11-1035) 

Presents  a  user  interface  for  picking  an  instrument. 

NAPi  ckEdi  tlnstrument  (11-1033) 

Presents  a  user  interface  for  changing  the  instrument  in  a  live  note  channel  or 
modifying  an  atomic  instrument. 

NAStuffToneDescri  pti  on  (11-1048) 

Initializes  a  tone  description  structure  with  the  details  of  a  General  MIDI  note 
channel. 

NAPi  ckArrangement  (11-1032) 

Displays  a  dialog  box  to  allow  instrument  selection. 
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NACopyri  ghtDi  al  og  (11-1019) 

Displays  a  copyright  dialog  box  with  information  specific  to  a  music  device. 


Note  Allocator  Configuration  and  Utilities 

Several  QTMA  functions  create  and  maintain  a  database  of  music  components,  save 
configuration  information  in  the  QuickTime  Preferences  file,  establish  connections 
to  external  MIDI  devices,  and  allow  the  note  allocator  to  perform  necessary  tasks  at 
task  foreground  time. 
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These  functions  are  listed  below. 


Functions 

NARegi  sterMusi  cDevi  ce  (11-1038) 

Registers  a  music  component  with  the  note  allocator. 

NAUnregi  sterMusi  cDevi  ce  (11-1051) 

Removes  a  previously  registered  music  component  from  the  note  allocator. 

NAGetRegi  steredMusi  cDevi  ce  (11-1028) 

Returns  details  about  music  components  registered  to  the  specified  note 
allocator  instance. 

NAGetDefaul  tMIDI  Input  (11-1023) 

Obtains  external  MIDI  connection  information. 

NASetDefaul  tMIDI  Input  (11-1043) 

Initializes  an  external  MIDI  device  used  to  receive  an  external  note  input. 
NAGetMIDIPorts  (11-1025) 

The  MIDI  input  and  output  ports  available  to  a  note  allocator. 

NASaveMusi  cConf  i  gurati  on  (11-1039) 

Saves  the  current  list  of  registered  devices  to  a  file. 

NATask  (11-1049) 

Called  periodically  to  allow  the  note  allocator  to  perform  tasks  in  foreground 
task  time. 
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Managing  Synthesizers 


Several  QTMA  functions  obtain  specific  information  about  a  synthesizer  and  obtain 
a  best  instrument  fit  for  a  requested  tone  from  the  available  instruments  within  the 
synthesizer;  play  a  note  with  a  specified  pitch,  volume,  and  duration;  get  and  set  a 
particular  synthesizer  knob;  obtain  synthesizer  knob  information;  and  get  and  set 
external  MIDI  procedure  name  entry  points. 

These  functions  are  listed  below. 


Functions 

Musi  cGetDescri  pti  on  (11-986) 

Returns  a  structure  describing  the  synthesizer  controlled  by  the  music 
component  device. 

Musi cFi ndTone  (11-981) 

Returns  the  number  of  the  best-matching  instrument  provided  by  a  specified 
music  component. 

Musi  cPl  ayNote  (11-1004) 

Plays  a  note  on  a  specified  part  at  a  specified  pitch  and  velocity. 

MusicGetKnob  (11-994) 

Returns  the  value  of  the  specified  global  synthesizer  knob. 

MusicSetKnob  (11-1007) 

Modifies  the  value  of  the  specified  global  synthesizer  knob. 

Musi  cGetKnobDescri  pti  on  (11-995) 

Returns  a  pointer  to  an  initialized  knob  description  structure  describing  a 
global  synthesizer  knob. 

Musi  cGetlnstrumentKnobDescri  pti  on  (11-992) 

Obtains  the  description  of  an  instrument  knob. 

Musi  cGetDrumKnobDescri  pti  on  (11-988) 

Returns  a  description  of  a  drum  kit  knob. 

Musi cGetKnobSetti ngStri ngs  (11-996) 

Returns  a  list  of  knob  setting  names  known  by  the  specified  music  component. 
MusicSetMIDIProc  (11-1009) 

Informs  the  music  component  what  procedure  to  call  when  it  needs  to  send 
MIDI  data. 
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Musi  cGetMIDIProc  (11-998) 

Returns  a  pointer  to  the  procedure  a  music  component  is  using  to  process 
external  MIDI  notes. 

Musi  cGetMIDIPorts  (11-997) 

Returns  the  number  of  input  and  output  ports  a  MIDI  device  has. 

MusicSendMIDI  (11-1006) 

Sends  a  MIDI  packet  to  a  specified  port. 

Musi  cGetDevi  ceConnecti  on  (11-987) 

Determines  how  many  hardware  synthesizers  are  available  to  a  music 
component  and  gets  the  IDs  for  those  devices. 

Musi  cUseDevi  ceConnecti  on  (11-1019) 

Tells  a  music  component  which  hardware  synthesizer  to  talk  to. 
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Managing  Instruments  and  Parts 

The  QTMA  provides  functions  to  initialize  a  part  with  an  instrument,  store 
instruments,  list  available  instruments,  manipulate  parts,  and  get  information 
about  parts. 

These  functions  are  listed  below. 


Functions 

Musi  cGetPartlnstrumentNumber  (11-1002) 

Returns  the  instrument  number  currently  assigned  to  a  part. 

Musi  cSetPartlnstrumentNumber  (11-1013) 

Superseded  by  Musi  cSetPartlnstrumentNumberlnterruptSafe  (11-1013). 

Musi  cSetPartlnstrumentNumberlnterruptSafe  (11-1013) 

Initializes  a  part  with  a  particular  instrument. 

Musi  cGetPartAtomi  clnstrument  (II — 1 000) 

Returns  the  atomic  instrument  currently  in  a  part. 

Musi  cSetPartAtomi  clnstrument  (II — 1  Oil) 

Initializes  a  part  with  an  atomic  instrument. 

Musi  cStorePartlnstrument  (11-1017) 

Puts  whatever  instrument  is  on  the  specified  part  into  the  synthesizer's 
instrument  store. 
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Musi  cGet  Instrument  About  Info  (11-990) 

Obtains  the  information  about  an  instrument  that  appears  in  its  About  box. 

Musi  cGetlnstrumentlnfo  (II — 99 1 ) 

Obtains  a  list  of  instruments  supported  by  a  synthesizer. 

MusicGetPart  (11-999) 

Returns  the  MIDI  channel  and  maximum  polyphony  for  a  particular  part. 
MusicSetPart  (II — 1 010) 

Sets  the  MIDI  channel  and  maximum  polyphony  for  a  specified  part. 

MusicGetPartName  (11-1003) 

Returns  the  string  name  of  a  part. 

MusicSetPartName  (11-1015) 

Changes  the  name  of  an  instrument  in  a  specified  part. 

MusicGetPartKnob  (11-1002) 

Retrieves  the  current  value  of  a  knob  for  a  part. 

MusicSetPartKnob  (11-1014) 

Sets  a  knob  for  a  specified  part. 

MusicResetPart  (11-1006) 

Silences  all  sounds  on  a  specified  part  and  resets  all  controllers  on  that  part  to 
their  default  values. 

MusicGetPartController  (II — 1001) 

Returns  the  value  of  a  specified  controller  on  a  specified  part. 

MusicSetPartController  (11-1012) 

Initializes  the  value  of  a  specified  controller  on  a  specified  part. 

MusicSetPartSoundLocalization  (11-1015) 

Passes  sound  localization  data  to  a  specified  synthesizer  part. 

Miscellaneous  Music  Component  Functions 

You  can  use  several  QTMA  functions  to  get  and  modify  the  master  tuning  of  the 
synthesizer,  to  play  off  line,  and  to  allow  the  music  component  to  perform  tasks  it 
must  perform  at  foreground  task  time. 

These  functions  are  listed  below. 
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Functions 


Musi  cGetMasterTune  (11-997) 

Returns  the  synthesizer's  master  tuning  as  a  fixed-point  value  in  semitones. 

Musi  cSetMasterTune  (11-1008) 

Alters  a  synthesizer's  master  tuning. 

Musi  cStartOffl  i  ne  (11-1016) 

Informs  the  QuickTime  music  synthesizer  that  the  music  will  not  be  played 
through  the  speakers. 

Musi  cSetOf  f  1  i  neT i meTo  (11-1009) 

Advances  the  synthesizer  clock  when  the  synthesizer  is  not  running  in  real 
time. 

Musi  cTask  (11-1018) 

Allows  a  music  component  to  perform  tasks  it  must  perform  at  foreground  task 
time. 
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Instrument  Component  Functions 

You  can  use  several  QTMA  functions  that  are  implemented  by  instrument 
components. 

These  functions  are  listed  below. 


Functions 


InstrumentGetlnfo  (11-766) 

Returns  information  about  all  the  atomic  instruments  supported  by  an 
instrument  component. 

InstrumentGetlnst  (11-767) 

Returns  an  atomic  instrument. 

Instrumentlni  ti  al  i  ze  (11-769) 

Tells  the  base  class  instrument  component  how  to  interpret  the  instrument 
component  resources. 

InstrumentOpenComponentResFi  1  e  (11-770) 

Opens  a  resource  file  containing  instruments  in  the  instrument  component  and 
makes  it  the  current  resource  file. 
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InstrumentCl  oseComponentResFi  1  e  (11-765) 

Closes  a  resource  file. 

InstrumentGetComponentRefCon  (11-766) 

Obtains  the  reference  constant  for  an  instrument  component. 

MIDI  Component  Functions 

You  can  use  several  QTMA  functions  that  are  implemented  by  MIDI  components. 
These  functions  are  MIDI  device  drivers;  they  are  called  by  the  note  allocator  MIDI 
routines. 

These  functions  are  listed  below. 


Functions 

QTMIDIGetMIDI Ports  (11-1188) 

Returns  two  lists  of  MIDI  ports  supported  by  the  specified  MIDI  component:  a 
list  of  ports  that  can  receive  MIDI  input  and  a  list  of  ports  that  can  send  MIDI 
output. 

QTMIDISendMIDI  (11-1189) 

Sends  MIDI  data  to  a  MIDI  port. 

QTMIDIUseRecei  vePort  (11-1189) 

Allocates  a  MIDI  port  for  input  or  to  release  the  port. 

QTMIDIUseSendPort  (11-1190) 

Allocates  a  MIDI  port  for  output  or  to  release  the  port. 

Importing  MIDI  Files 

You  can  use  QTMA  functions  to  control  the  importation  of  MIDI  files. 

These  functions  are  listed  below. 

Functions 

MIDI ImportGetSetti ngs  (11-917) 

Obtains  settings  that  control  the  importation  of  MIDI  files. 

MIDI ImportSetSetti ngs  (11-917) 

Define  settings  that  control  the  importation  of  MIDI  files. 
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Managing  the  Generic  Music  Component 


One  QTMA  functions  lets  you  tell  the  generic  music  component  what  services  your 
music  component  requires. 

This  function  is  listed  below. 


Functions 


Musi  cGeneri  cConf  i  gure  (11-982) 

Informs  the  generic  music  component  what  services  your  music  component 
requires  and  points  to  any  resources  that  are  necessary. 
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Calling  Generic  Music  Component  Clients 

Several  functions  are  implemented  by  client  music  components  of  the  generic  music 
component.  They  are  called  by  the  generic  music  component,  which  make  calls  that 
are  necessary  for  responding  to  function  calls  made  directly  by  applications. 

These  functions  are  listed  below. 


Functions 

Musi  cDeri  vedSetKnob  (11-976) 

Called  when  any  of  the  synthesizer's  knobs  are  altered. 

Musi  cDeri  vedSetPart  (11-979) 

Sets  the  polyphony  for  the  part  specified  in  the  GCPart  (IV-2263)  structure. 
Musi  cDeri  vedSetlnstrument  (11-976) 

The  complete  instrument  defined  by  the  Part  structure  to  the  synthesizer. 
Musi cDeri vedSetMIDI  (11-978) 

Sets  the  MIDI  channel  and  other  MIDI  settings  for  MIDI  output  only. 
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Extend edSchedul edSoundHeader 
Extend edSchedul edSoundHeader 
Extended Sound Component Data 
Ext end ed Sou nd Component Da t a Pt 
Extended Sound  Pa ramBl  ock 
Ext ended Sound  Pa ramBl  ockPtr 
ExtSoundHeader 
ExtSoundHeaderPtr 


atom  'dimm'  (IV- 
atom  'dinf'  (IV- 
callback  DlgHookProc  (III- 
“Universal  Procedure  Pointers"  (IV- 
callback  D1 gHookYDProc  (III- 
“Universal  Procedure  Pointers”  (IV- 
atom  'dmax'  (IV- 
atom  'dmed'  (IV- 
callback  DoMCActi onProc  (III- 
“Universal  Procedure  Pointers”  (IV- 
“Graphics  Types”  (IV- 
“Universal  Procedure  Pointers”  (IV- 
atom  'dref'  (IV- 
atom  'drep'  (IV- 
struct  EditListType  (IV- 
atom  'edts'  (IV- 
struct  EffectsFrameParams  (IV- 
“Effects  Types”  (IV- 
struct  EffectSource  (IV- 
“Effects  Types"  (IV- 
atom  'elst'  (IV- 
atom  'end  '  (IV- 
atom  'enda'  (IV- 
“Virtual  Reality  Types”  (IV- 
“Virtual  Reality  Types”  (IV- 
struct  EnumLi stRecord  (IV- 
struct  EnumRangeRecord  (IV- 
struct  EnumVal uePai r  (IV- 
struct  EQSpectrumBandsRecord  (IV- 
“Sound  Types"  (IV- 
“System  and  Toolbox  Types”  (IV- 
“System  and  Toolbox  Types”  (IV- 
“System  and  Toolbox  Types”  (IV- 
struct  EventRecord  (IV- 
atom  'expo'  (IV- 
atom  'ext  '  (IV- 
struct  ExtComponentResource  (IV- 
“Component  Types”  (IV- 
“Component  Types”  (IV- 
“Numeric  Types"  (IV- 
“Numeric  Types”  (IV- 
struct  ExtendedSchedul  edSoundHeader  (IV- 
Ptr  “Sound  Types”  (IV- 

struct  ExtendedSoundComponentData  (IV- 
r  “Sound  Types"  (IV- 

struct  ExtendedSoundParamBl ock  (IV- 
“Sound  Types"  (IV- 
struct  ExtSoundHeader  (IV- 
“Sound  Types"  (IV- 


“Vi rtual 
“Vi rtual 
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Fi el dlnfoImageDescri pti on  Ext en si  on 

struct  Fi el dlnfoImageDescri pti onExtension  (IV-2258) 
Fi el dlnfoImageDescri pti on  Ext en si  on 2 

struct  Fi el dlnfoImageDescri pti onExtensi on2  (IV-2258) 


F i 1 e  F i 1 terProcPtr 

callback  Fi  1  eFi  1  terProc 

( I I 1-2082 ) 

Fi  1  eFi  1  terliPP 

“Universal  Procedure  Pointers” 

(IV-2641) 

FileFilterYDProcPtr 

callback  Fi  1  eFi  1  terYDProc 

( I I 1-2083 ) 

Fi  1  eFi  1  terYDUPP 

“Universal  Procedure  Pointers” 

(IV-2641) 

Fi  1  ePl  ayCompl eti onProcPtr  ca' 

1 1  back  Fi 1 ePl ayCompl eti onProc 

( I I 1-2084 ) 

Fi 1 ePl ayCompl eti onUPP 

“Universal  Procedure  Pointers” 

(IV-2641) 

Fi  xed 

“Numeric  Types” 

(IV-2631) 

Fi xedPoi nt 

struct  FixedPoint 

(IV-2258) 

Fi xedPtr 

“Numeric  Types” 

(IV-2631) 

Fi xedRangeRecord 

struct  Fi xedRangeRecord 

( I V  -  2  2  5  9  ) 

Fi  xedRect 

struct  FixedRect 

(IV-2260) 

'flap' 

atom  'flap' 

( I V  -  2  5  3  7  ) 

FI ashDescri pti on 

struct  FI ashDescri pti on 

(IV-2260) 

FlashDescriptionHandle 

“Media  Handling  Types” 

(IV-2626) 

FI ashDescri pti onPtr 

“Media  Handling  Types” 

(IV-2626) 

FI  oat32 

“Numeric  Types” 

(IV-2631) 

FI oat64 

“Numeric  Types” 

(IV-2631) 

FI  oat80 

“Numeric  Types” 

(IV-2631) 

FI  oat96 

“Numeric  Types” 

(IV-2631) 

FI oatPoi nt 

“Virtual  Reality  Types” 

(IV-2647) 

FourCharCode 

“System  and  Toolbox  Types” 

( I V - 2638 ) 

Fract 

“Numeric  Types” 

(IV-2631) 

FractPtr 

“Numeric  Types” 

(IV-2631) 

' free ' 

atom  'free' 

( I V - 2538 ) 

' f rma ' 

atom  'frma' 

(IV-2538) 

FSSpec 

struct  FSSpec 

(IV-2262) 

FSSpecArrayPtr 

“File  System  Types” 

( I V - 2624 ) 

FSSpecHandl e 

"File  System  Types” 

( I V - 2624 ) 

FSSpecPtr 

"File  System  Types” 

(IV-2624) 

' ftyp' 

atom  'ftyp' 

( I V  -  2  5  3  9  ) 

GCInstrumentData 

struct  GCInstrumentData 

( I V  -  2  2  6  3  ) 

GCInstrumentDataHandl e 

“Music  Types” 

(IV-2630) 

GCInstrumentDataPtr 

“Music  Types” 

(IV-2630) 

GCPart 

struct  GCPart 

( I V  -  2  2  6  3  ) 

GDevi ce 

struct  GDevice 

(IV-2264) 

GDHandl e 

“Graphics  Types” 

(IV-2624) 

GDPtr 

“Graphics  Types” 

(IV-2624) 

Generi cKnobDescri pti on 

struct  Generi cKnobDescri  pti  on 

( I V  -  2  2  6  7  ) 

Generi cKnobDescri pti onLi st  struct  Generi cKnobDescri pti onList 

( I V - 2268 ) 

Generi cKnobDescri pti onListHandle 

“Music  Types” 

(IV-2630) 

Generi cKnobDescri pti onListPtr 

“Music  Types” 

(IV-2630) 

Get Mi ssi ngComponentResourceProcPtr 

callback  GetMissi ngComponentResourceProc 

( I I 1-2084 ) 

GetMissi ngComponentResourceUPP 

“Universal  Procedure  Pointers” 

(IV-2641) 

GetMovi eCompl eteParams 

struct  GetMovi eCompl eteParams 

( I V - 2268 ) 
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GetMovi eProcPtr 
GetMovi eUPP 
' gmhd ' 

' gmi n ' 

GMInstrumentlnfo 

GMInstrumentlnfoHandl e 

GMInstrumentlnfoPtr 

Gradi entCol orPtr 

Gradi entCol or Record 

Gradi entType 

Graf Port 

GrafPtr 

GrafVars 

Graphi clmageMovi elmportComponent 

Graphi csExportComponent 

Graphi cs ImportComponent 

GWorl  d  FI  ags 

GWorl  dPtr 

gxPath 

gxPaths 

gxPoi nt 

Handl e 

Handl erError 
' hdi r ' 

Hi  ghHookUPP 
'hint' 

'hint' 

'  h  1  i  t ' 

' hnti ' 

' hots ' 

'  h  s  i  n  ' 

'  hspa ' 

' htxt ' 

ICMA1 i gnmentProcPtr 
ICMA1 i gnmentProcRecord 
ICMA1 i gnmentProcRecordPtr 
ICMA1 i gnmentUPP 
ICMCompl eti onProcPtr 
ICMCompl eti onProcRecord 
ICMCompl eti onProcRecordPtr 
ICMCompl eti onUPP 

ICMConvertDataFormatProcPtr  cal 

ICMConvertDataFormatUPP 

ICMCursorNoti fy 

ICMCursorShieldedProcPtr 

ICMCursorShieldedUPP 

ICMDataProcPtr 

ICMDataProcRecord 

ICMDataProcRecordPtr 


callback  GetMovieProc  (III- 2085 ) 
"Universal  Procedure  Pointers”  (IV-2641) 
atom  'gmhd'  ( IV-2539) 
atom  'gmin'  (IV-2540) 
struct  GMInstrumentlnfo  ( IV-2272) 
“Music  Types”  (IV-2630) 
“Music  Types”  (IV-2630) 
“Effects  Types”  (IV-2622) 
struct  Gradi entCol orRecord  (IV-2273) 
“Effects  Types"  (IV-2622) 
struct  GrafPort  (IV-2273) 
“Graphics  Types”  (IV-2624) 
“Graphics  Types”  (IV-2624) 
“Component  Types”  (IV-2621) 
“Component  Types"  (IV-2621) 
“Component  Types”  (IV-2621) 
“Graphics  Types"  (IV-2624) 
“Graphics  Types”  (IV-2624) 
struct  gxPath  (IV-2276) 
struct  gxPaths  (IV-2277) 
struct  gxPoint  (IV-2277) 
“Memory  Types"  (IV-2627) 
“Data  Handling  Types"  (IV-2622) 
atom  ' hdl r '  (IV-2540) 
"Universal  Procedure  Pointers”  (IV-2641) 
atom  'hinf'  (IV-2541) 
atom  'hint'  (IV-2542) 
atom  ' h 1 i t '  (IV-2543) 
atom  ' hnti '  ( I V - 2544 ) 
atom  'hots'  (IV- 2544 ) 
atom  'hsin'  (IV-2545) 
atom  'hspa'  (IV-2545) 
atom  'htxt'  (IV-2546) 
callback  ICMA1 i gnmentProc  (III - 2086 ) 
struct  ICMA1 i gnmentProcRecord  (IV-2278) 
“Codec  Types”  (IV-2619) 
"Universal  Procedure  Pointers”  (IV-2641) 
callback  ICMCompl eti onProc  (III -2087 ) 
struct  ICMCompl eti onProcRecord  (IV-2279) 
“Codec  Types”  (IV-2619) 
"Universal  Procedure  Pointers”  (IV-2641) 
Iback  ICMConvertDataFormatProc  (III -2088 ) 
"Universal  Procedure  Pointers”  (IV-2641) 
“Codec  Types”  (IV-2619) 
callback  ICMCursorShi el dedProc  (III -2089 ) 
"Universal  Procedure  Pointers"  (IV-2641) 
callback  ICMDataProc  (II 1-2090) 
struct  ICMDataProcRecord  (IV-2279) 
“Codec  Types”  (IV-2619) 


IXT 
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ICMDataUPP 
I  CM  FI ushProcPtr 
ICMFlushProc Record 
ICMFlushProcRecordPtr 
ICMFlushUPP 
ICMFrameTimelnfo 
ICMFrameT i melnfoPtr 
ICMFrameTimePtr 
ICMFrameT i me Record 
ICMMemoryDi sposedProcPtr 
ICMMemoryDi sposedUPP 
ICMPixel Formatlnfo 
ICMPixel FormatlnfoPtr 
ICMProgressProcPtr 
ICMProgressProc Record 
ICMProgressProcRecordPtr 
ICMProgressUPP 
'  i dat ' 

'  i dsc ' 

'  i i cc ' 

'  i mag ' 

ImageCodecMPDrawBandProcPtr 
ImageCodecMPDrawBandUPP 
ImageCodecT imeT  riggerProcPtr 
ImageCodecT imeT  riggerUPP 
ImageDescri pti on 
ImageDescriptionHandle 
ImageDescri pti onPtr 
ImageFieldSequence 
ImageRangeRecord 
ImageSequence 
ImageSequence Da taSource 
Images ubCodec Decomp ressCa pa bi 1 

struct 


"Universal  Procedure  Pointers” 
callback  ICMFlushProc 
struct  I  CM  FI ushProcRecord 
"Codec  Types” 
"Universal  Procedure  Pointers” 
struct  ICMFrameT i me  Info 
"Codec  Types” 
"Codec  Types” 
struct  ICMFrameTimeRecord 
callback  ICMMemoryDi sposedProc 
"Universal  Procedure  Pointers” 
struct  ICMPi xel Formatlnfo 
"Codec  Types” 
callback  ICMProgressProc 
struct  ICMProgressProcRecord 
"Codec  Types” 
"Universal  Procedure  Pointers” 
atom  'idat' 
atom  'idsc' 
atom  'iicc' 
atom  'imag' 

callback  ImageCodecMPDrawBandProc 
"Universal  Procedure  Pointers” 
callback  ImageCodecTi meT riggerProc 
"Universal  Procedure  Pointers” 
struct  ImageDescri pti on 
"Codec  Types” 
"Codec  Types” 
"Codec  Types” 
struct  ImageRangeRecord 
"Codec  Types” 
"Codec  Types” 

i  ti  es 

Images ubCodec Decomp ressCa pa bi 1 i ti es 


(IV-2641) 
( 1 1 1 -2091 ) 
(IV-2280) 
(IV-2619) 
(IV-2641) 
( I V  -  2281  ) 
(IV-2619) 
(IV-2619) 
( I V  -  2281 ) 
( 1 1 1-2092 ) 
(IV-2641) 
( I V - 2282 ) 
(IV-2619) 
( 1 1 1-2093 ) 
( I V  -  2284 ) 
(IV-2619) 
(IV-2641) 
(IV-2546) 
(IV-2547) 
(IV-2547) 
(IV-2547) 
( 1 1 1 -2095 ) 
(IV-2641) 
( 1 1 1-2096 ) 
(IV-2641) 
( I V - 2285 ) 
(IV-2619) 
(IV-2619) 
(IV-2619) 
( I V - 2288 ) 
(IV-2619) 
(IV-2619) 

( I V - 2288 ) 


Images ubCodec Decompress  Record 


ImageT  ranscoderComponent 

struct  Images ubCodec Decompress  Record 
"Component  Types” 

(IV-2289) 

(IV-2621) 

ImageTranscodeSequence 

"Codec 

Types” 

(IV-2619) 

Imagi ngCompl eteProcPtr 

"Virtual  Reality 

Types” 

(IV-2647) 

Imagi ngCompl eteUPP 

"Virtual  Reality 

Types” 

(IV-2647) 

' imap' 

atom 

'  i map ' 

( I V - 2548 ) 

'  i  met ' 

atom 

'  i met ' 

(IV-2549) 

' i mda ' 

atom 

'  i mda ' 

(IV-2549) 

'  i  mgp ' 

atom 

'  i mgp ' 

( I V  -  2  5  5  0  ) 

'  i  mgr ' 

atom 

'  i mgr ' 

( I V  -  2  5  5  0  ) 

' i mpn ' 

atom 

'  i mpn ' 

(IV-2551) 

' i mre ' 

atom 

'  i mre ' 

(IV-2552) 

' i mrg ' 

atom 

'  i mrg ' 

(IV-2552) 

' i mrt ' 

atom 

'  i mrt ' 

( I V  -  2  5  5  3  ) 
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'  i  n ' 

InstCompInfo 
InstCompInfoHandl e 
InstCompInfoPtr 
InstKnobLi  st 
InstKnobRec 
InstLi bDescRec 
InstrumentAboutlnfo 
InstrumentAboutlnfoHandl e 
InstrumentAboutlnf oPtr 
InstrumentlnfoLi st 
I  instrument  I  nfoLi  stHandl  e 
InstrumentlnfoLi stPtr 
InstrumentlnfoRecord 
InstSampl eDescRec 
ISAType 
ITab 

ITabHandl e 

ITabPtr 

ItemCount 

KaraokeAtom 

KaraokeRec 

' kmat ' 

KnobDescri pti on 
LangCode 

Leavi ngNodeProcPtr 
Leavi ngNodeUPP 
LeftOverBl ock 
LeftOverBl ockPtr 
Level Meterlnfo 
Level MeterlnfoPtr 
LHHandl e 
'link' 

' 1 oad ' 

Logi cal  Address 
LongRangeRecord 
' LOOP' 

MacPolygon 
MacRegi on 
Matri xRecord 
Matri xRecordPtr 
'matt' 

'maxr' 
mcActi on 

MCActi onFi 1 terProcPtr 

MCActi  onFi  1  terLIPP 

MCActi onFi 1 terWi thRefConProcPtr 


atom  '  in'  (IV-2554) 
struct  InstCompInfo  (IV-2291) 
“Music  Types”  ( IV-2630) 
“Music  Types”  (IV-2630) 
struct  InstKnobList  (IV-2292) 
struct  InstKnobRec  ( IV-2293) 
struct  InstLi bDescRec  (IV-2293) 
struct  InstrumentAboutlnfo  (IV-2293) 
“Music  Types”  (IV-2630) 
“Music  Types”  (IV-2630) 
struct  InstrumentlnfoLi st  (IV-2294) 
“Music  Types”  (IV-2630) 
“Music  Types”  (IV-2630) 
struct  InstrumentlnfoRecord  (IV-2295) 
struct  InstSampl eDescRec  (IV-2296) 
“System  and  Toolbox  Types”  (IV- 2638 ) 
struct  ITab  (IV-2297) 
“Graphics  Types”  (IV-2624) 
“Graphics  Types”  (IV-2624) 
“System  and  Toolbox  Types”  (IV- 2638 ) 
struct  KaraokeAtom  (IV-2298) 
struct  KaraokeRec  (IV-2298) 
atom  'kmat'  (IV-2554) 
struct  KnobDescri pti on  (IV-2299) 
“Text  Types”  (IV-2640) 
“Virtual  Reality  Types”  (IV-2647) 
“Virtual  Reality  Types”  (IV-2647) 
struct  LeftOverBl ock  (IV- 230 1 ) 
“Sound  Types”  (IV-2633) 
struct  Level Meterlnfo  (IV - 230 1 ) 
“Sound  Types”  (IV-2633) 
“Text  Types”  (IV-2640) 
atom  'link'  (IV-2556) 
atom  'load'  (IV-2556) 
“Memory  Types”  (IV-2627) 
struct  LongRangeRecord  (IV-2302) 
atom  'LOOP'  (IV-2557) 
struct  MacPolygon  (IV - 2303 ) 
struct  MacRegion  (IV- 2303 ) 
struct  MatrixRecord  (IV- 2304 ) 
“Effects  Types”  (IV-2622) 
atom  'matt'  (IV-2557) 
atom  'maxr'  (IV-2558) 
“Movie  Controller  Types”  (IV-2628) 
callback  MCActi onFi 1 terProc  (III -2096 ) 
Universal  Procedure  Pointers”  (IV-2641) 


callback  MCActionFi 1 terWi thRefConProc  (III -2097 ) 


MCActi onFi 1 terWi thRefConUPP  “Universal  Procedure  Pointers"  (IV-2641) 


IXT 
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mcM  ags 

MC Inter fa ceEl ement 
' mdat ' 

' mdhd ' 

' mdi a ' 

Medi  a 

Medi a EQSpectrumBands Record 

MediaEQSpectrumBandsRecordPtr 

Medi aHandl er 

Medi aHandl er Component 

medi aHandl erFlagsEn urn 

Medi aHeader 

Medi a  Packet i zer Info 

MediaPacketizerlnfoHandle 

MediaPacketizerlnfoPtr 

Medi aPacketi zerRequi remen ts 

Medi aPacketi zerRequi remen tsPtr 

Medi aRecord 

MenuHandl e 

Menulnfo 

MenuPtr 

'mime' 

' mi nf ' ( base ) 

' mi nf ' ( generi c ) 

' mi nf ' (sound ) 

' mi nf ' ( vi deo ) 

Modal Fi 1 terProcPtr 
Modal Fi 1 terUPP 
Modal FilterYDProcPtr 
Modal FilterYDUPP 


“Movie  Controller  Types” 
“Movie  Controller  Types” 
atom  'mdat' 
atom  'mdhd' 
atom  'mdia' 
“Movie  Types” 
struct  Medi a EQSpectrumBands Record 
“Media  Handling  Types” 
“Component  Types” 
“Component  Types” 
“Media  Handling  Types” 
struct  MediaHeader 
struct  Medi aPacketi zerlnfo 
“Streaming  Types” 
“Streaming  Types” 
struct  Medi aPacketi zerRequi remen ts 
“Streaming  Types” 
struct  MediaRecord 
“System  and  Toolbox  Types” 
struct  Menulnfo 
“System  and  Toolbox  Types” 
atom  'mime' 
atom  'minf'(base) 
atom  ' mi nf ' ( generi c ) 
atom  'minf ' (sound) 
atom  ' mi nf ' ( vi deo ) 
callback  Modal Fi 1 terProc 
"Universal  Procedure  Pointers” 
callback  Modal Fi 1 terYDProc 
"Universal  Procedure  Pointers” 


Modi  f  i  erTrackGraphi cs Mode Record 

struct  Modi f i erTrackGraphi cs Mode Record 


ModRef 
' moov ' 

Moti onJPEGApplMarker 
MouseOverHotSpotProcPtr 
MouseOverHotSpotUPP 
Movi  e 

Movi eControl 1 er 

Movi eControl 1 erPtr 

Movi eDrawi ngCompl eteProcPtr  c 

Movi eDrawi ngCompl eteUPP 

Movi eEdi tState 

Movi eEditState Record 

Movi eExecuteWi redActi onsProcPtr 

cal  1  b 

Movi eExecuteWi redActi onsUPP 
Movi e Export Component 
Movi e Export Get Data  Pa  rams 


struct  ModRef 
atom  'moov' 
struct  Moti onJPEGApplMarker 
“Virtual  Reality  Types” 
“Virtual  Reality  Types” 
“Movie  Types” 
“Movie  Controller  Types” 
“Movie  Controller  Types” 
llback  Movi eDrawi ngCompl eteProc 
“Universal  Procedure  Pointers” 
“Movie  Types” 
struct  Movi eEdi tStateRecord 

ck  Movi eExecuteWi redActi onsProc 
“Universal  Procedure  Pointers” 
“Component  Types” 
struct  Movi eExportGetDataParams 


( I V - 2628 ) 
( I V - 2628 ) 
(IV-2558) 
( I V  -  2  5  5  9  ) 
( I V  -  2  5  6  0  ) 
( I V - 2628 ) 
( I V - 2304 ) 
(IV-2626) 
(IV-2621) 
(IV-2621) 
(IV-2626) 
(IV-2305) 
(IV-2306) 
(IV-2636) 
(IV-2636) 
( I V - 2308 ) 
(IV-2636) 
(IV-2310) 
( I V - 2638 ) 
(IV-2310) 
( I V - 2638 ) 
(IV-2561) 
(IV-2561) 
(IV-2562) 
( I V - 2564 ) 
(IV-2565) 

( 1 1 1-2098 ) 
(IV-2641) 

( 1 1 1-2099 ) 
(IV-2641) 

(IV-2311) 
( IV-2312) 
( I V  -  2  5  6  6  ) 
(IV-2312) 
(IV-2647) 
(IV-2647) 
( I V - 2628 ) 
( I V - 2628 ) 
( I V - 2628 ) 

( 1 1 1 -2100 ) 
(IV-2641) 
( I V - 2628 ) 
(IV-2313) 

( 1 1 1 -2101 ) 
(IV-2641) 
(IV-2621) 
( IV-2314) 
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Movi eExportGetDataProcPtr 

Movi eExportGetDataUPP 

Movi e Expo rtGet P r ope rtyP roc Ptr 


callback  MovieExportGetDataProc 
"Universal  Procedure  Pointers’ 


cal  1  back  Movi eExportGetPropertyProc 
"Universal  Procedure  Pointers" 
“Movie  Types” 
struct  MovieHeader 
“Component  Types” 
struct  Movi eMedi aTimeRecord 


Movi eExportGetPropertyUPP 
movieFl  attenFl  agsEnum 
Movi eHeader 
Movi elmportComponent 
Movi eMedi aTi meRecord 
Movi ePrePrerol 1  Comp! eteProcPtr 

callback  Movi eP re P re roll  Comp! eteProc 
Movi ePrePrerol 1  Comp! eteUPP  “Universal  Procedure  Pointers 

Movi ePrevi ewCal 1 OutProcPtr  callback  Movi ePrevi ewCal 1 OutProc 


Movi ePrevi ewCal 1 OutUPP 

MovieProgressProcPtr 

Movi eProgressUPP 

Movi ePtr 

Movi eRecord 

MovieRgnCoverProcPtr 

Movi eRgnCoverUPP 

MoviesErrorProcPtr 

Movi esErrorUPP 

Movi esUserData 

Musi cComponent 

Musi cControl 1 er 

Musi cDescri pti on 

Musi cDescri pti onHandl e 

Musi cDescri pti onPtr 

Musi cMIDIPacket 

MusicMIDIReadHookProcPtr 

MusicMIDIReadHookUPP 

Musi cMIDISendP roc Ptr 

Musi cMIDISendUPP 

Musi cOfflineDataProc Ptr 

MusicOfflineDataUPP 

Musi cOpWord 

Musi cOpWordPtr 

'mvhd ' 

'name' (sprite) 


“Universal  Procedure  Pointers” 
callback  MovieProgressProc 
“Universal  Procedure  Pointers” 
“Movie  Types" 
struct  MovieRecord 


(III- 
(IV- 

(III- 
(IV- 
(IV- 
(IV- 
(IV- 
(IV- 

(III- 
(IV- 
(III- 
(IV- 
(III- 
(IV- 
(IV- 
(IV- 

callback  Movi eRgnCoverProc  (III- 
"Universal  Procedure  Pointers”  (IV- 
callback  MoviesErrorProc  (III- 
“Universal  Procedure  Pointers”  (IV- 
struct  Movi esUserData 
“Music  Types” 
“Music  Types" 
struct  Musi cDescri pti on 
“Music  Types” 
“Music  Types” 
struct  MusicMIDIPacket 
callback  MusicMIDIReadHookProc 
“Universal  Procedure  Pointers” 
callback  Musi cMIDISendProc 
“Universal  Procedure  Pointers” 
callback  Musi cOffl i neDataProc 
“Universal  Procedure  Pointers" 
“Music  Types” 


atom 
atom 


“Music  Types” 
atom  'mvhd' 
name' (sprite) 
name ' ( userdata  ) 


' name ' ( userdata  ) 

NCLCCol orlnfoImageDescripti onExtensi on 

struct  NCLCCol orlnfoImageDescri pti onExtensi  on 
'ndhd'  atom  'ndhd' 


nextTimeFl agsEnum 
'  nl  oc ' 

nonGM Instrument  Info 
nonGMInstrumentlnfoHandl  e 
nonGM Instrument  Inf oPtr 
nonGM Instrument  Inf o Record 


"Timing  and  Callback  Types” 
atom  'nloc' 
struct  nonGMInstrumentlnfo 
“Musi c  Types” 
“Musi c  Types” 
struct  nonGMInstrumentlnfoRecord 


(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(III- 

(IV- 

(III- 

(IV- 

(III- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 


-2101) 

-2641) 

-2102) 
-2641) 
-2628) 
-2316) 
-2621  ) 
-2318) 

-2104) 

-2641) 

-2105) 

-2641) 

-2105) 

-2641) 

-2628) 

-2318) 

-2108) 

-2641) 

-2109) 

-2641) 

-2319) 

-2630) 

-2630) 

-2319) 

-2630) 

-2630) 

-2320) 

-2109) 

-2641) 

-2110) 

-2641) 

-2110) 

-2641) 

-2630) 

-2630) 

-2567) 

-2568) 

-2569) 

-2321) 

-2569) 

-2640) 

-2570) 

-2321) 

-2630) 

-2630) 

-2322) 
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NoteAl 1 ocator 

“Music  Types” 

(IV-2630) 

NoteChannel 

“Music  Types” 

(IV-2630) 

NoteRequest 

struct  NoteRequest 

( I V  -  2  3  2  3  ) 

NoteRequestlnfo 

struct  NoteRequestlnfo 

( I V  -  2  3  2  3  ) 

Nul 1 StHandl e 

“Text  Types” 

(IV-2640) 

'nump ' 

atom  'nump' 

(IV-2570) 

NumVersi on 

struct  NumVersion 

(IV-2324) 

' obi d ' 

atom  ' ob i d ' 

(IV-2571) 

Off 1 i neSampl eType 

struct  Off 1 i neSampl eType 

(IV-2325) 

OpenCPi cParams 

struct  OpenCPi cParams 

( I V  -  2  3  2  6  ) 

Opti onBi ts 

“System  and  Toolbox  Types” 

( I V - 2638 ) 

OSErr 

“System  and  Toolbox  Types” 

( I V - 2638 ) 

OSStatus 

“System  and  Toolbox  Types” 

(IV-2638) 

OSType 

“System  and  Toolbox  Types” 

( I V - 2638 ) 

OSTypePtr 

“System  and  Toolbox  Types” 

(IV-2638) 

ParameterAlternateDataEntry 

struct  ParameterAlternateDataEntry 

( I V  -  2  3  2  6  ) 

ParameterAlternateDataType 

struct  ParameterAlternateDataType 

( I V  -  2  3  2  7  ) 

ParameterAtomTypeAndlD 

struct  ParameterAtomTypeAndlD 

( I V  -  2  3  2  7  ) 

ParameterDataBehavior 

struct  ParameterDataBehavior 

( I V - 2328 ) 

ParameterDataType 

struct  ParameterDataType 

( I V  -  2  3  2  9  ) 

ParameterDataUsage 

struct  ParameterDataUsage 

( I V  -  2  3  3  0  ) 

ParameterDependancy Record 

struct  ParameterDependancyRecord 

( I V  -  2  3  3  0  ) 

Pattern 

struct  Pattern 

( I V  -  2  3  3  0  ) 

'  payt ' 

atom  'payt' 

(IV-2571) 

PBVersi on 

“System  and  Toolbox  Types” 

(IV-2638) 

' pdat ' 

atom  'pdat' 

(IV-2572) 

Physi cal  Address 

“Memory  Types” 

( I V  -  2  6  2  7  ) 

Pi cHandl e 

“Graphics  Types” 

(IV-2624) 

Pi cPtr 

“Graphics  Types” 

(IV-2624) 

Pi cture 

struct  Picture 

( I V - 233 1  ) 

Pi xel Aspect Rati olmageDescri pti on  Ext en si  on 

struct  Pixel 

Aspect Rati olmageDescri pti on  Ext en si  on 

(IV-2332) 

Pi xMap 

struct  PixMap 

(IV-2332) 

Pi xMapExtensi on 

struct  Pi xMapExtensi on 

(IV-2335) 

Pi xMapExtHandl  e 

“Graphics  Types” 

(IV-2624) 

Pi xMapExtPtr 

“Graphics  Types” 

(IV-2624) 

Pi xMapHandl e 

“Graphics  Types” 

(IV-2624) 

Pi xMapPtr 

“Graphics  Types” 

(IV-2624) 

PixPat 

struct  PixPat 

( I V  -  2  3  3  6  ) 

Pi xPatHandl e 

“Graphics  Types” 

(IV-2624) 

Pi xPatPtr 

“Graphics  Types” 

(IV-2624) 

PI  ana r Component  Info 

struct  PI anarComponentlnfo 

( I V  -  2  3  3  7  ) 

PI anarPixMapInfo 

struct  PI anarPixMapInfo 

( I V  -  2  3  3  7  ) 

PI anarPixmapInfoSorensonYUV9 

struct  PI  ana r Pi xmapInfoSorensonYUV9 

( I V - 2338 ) 

PI anarPixmapInfoYUV420 

struct  PlanarPixmapInfoYUV420 

( I V - 2338 ) 

pi ayHi ntsEnum 

“Movie  Types” 

( I V - 2628 ) 

' pmax ' 

atom  'pmax' 

(IV-2572) 

' pnot ' 

atom  'pnot' 

(IV-2573) 

pnotComponent 

“Component  Types” 

(IV-2621) 
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Pol  nt 
Poi ntPtr 
PolyHandl e 
PolyPtr 

PrePrerol 1 Compl ete ProcPtr 

PrePrerol 1 Compl eteUPP 

Previ ewResource 

Previ ewResourcePtr 

Previ ewResource Record 

ProcHandl e 

ProcInfoType 

ProcPtr 

Ptr 

Publ i cHandl erlnfo 

QDArcProcPtr 

QDArcUPP 

QDBi tsProcPtr 

QDBitsUPP 

QDCommentProcPtr 

QDCommentUPP 

QDGetPi cProcPtr 

QDGetPi  clIPP 

QDJShieldCursorProcPtr 

QDJShieldCursorUPP 

Q  D  Li neProcPtr 

QDLineUPP 

QDOpcodeProcPtr 

QDOpcodeUPP 

QDOval ProcPtr 

QDOvalUPP 

QDPi xProcPtr 

QDPixUPP 

QDPolyProcPtr 

QDPolyUPP 

QDPrinterStatusUPP 
QDProcs 
QDProcsPtr 
QDPutPi cProcPtr 
QDPutPi  clIPP 
QDRectProcPtr 
QDRectUPP 
' qdrg ' 

QDRgnProcPtr 

QDRgnUPP 

QDRRectProcPtr 

QDRRectUPP 

QDStdGlyphsProcPtr 

QDStdGlyphsUPP 

QDTextProcPtr 


struct  Point  (IV- 2339 ) 
“Memory  Types”  ( IV-2627  ) 
“Graphics  Types”  ( IV-2624) 
“Graphics  Types”  (IV-2624) 
callback  PrePrerol 1 Compl eteProc  (III -2111 ) 
“Universal  Procedure  Pointers”  (IV-2641) 
“Codec  Types”  (IV-2619) 
“Codec  Types”  (IV-2619) 
struct  Previ ewResourceRecord  (IV-2340) 
“Universal  Procedure  Pointers”  (IV-2641) 
“System  and  Toolbox  Types”  (IV- 2638 ) 
callback  Proc  (III -2112 ) 
“Memory  Types”  (IV-2627) 
struct  Publ i cHandl erlnfo  (IV-2341) 
callback  QDArcProc  (III-2112) 
“Universal  Procedure  Pointers"  (IV-2641) 
callback  QDBitsProc  (II 1-2113) 
“Universal  Procedure  Pointers”  (IV-2641) 
callback  QDCommentProc  (III-2114) 
“Universal  Procedure  Pointers"  (IV-2641) 
callback  QDGetPicProc  (III-2114) 
“Universal  Procedure  Pointers”  (IV-2641) 
callback  QDJShi el dCursorProc  (III-2115) 
“Universal  Procedure  Pointers”  (IV-2641) 
callback  QDLineProc  (III-2115) 
“Universal  Procedure  Pointers”  (IV-2641) 
callback  QDOpcodeProc  (III-2116) 
“Universal  Procedure  Pointers"  (IV-2641) 
callback  QDOvalProc  (III-2116) 
“Universal  Procedure  Pointers”  (IV-2641) 
callback  QDPixProc  (III -2117 ) 
“Universal  Procedure  Pointers”  (IV-2641) 
callback  QDPolyProc  ( 1 1 1 -2118) 
“Universal  Procedure  Pointers”  (IV-2641) 
“Universal  Procedure  Pointers”  (IV-2641) 
struct  QDProcs  (IV- 2342 ) 
“Graphics  Types”  (IV-2624) 
callback  QDPutPicProc  (III-2119) 
“Universal  Procedure  Pointers”  (IV-2641) 
callback  QDRectProc  (III-2119) 
“Universal  Procedure  Pointers”  (IV-2641) 
atom  'qdrg'  (IV-2574) 
callback  QDRgnProc  (III-2120) 
“Universal  Procedure  Pointers”  (IV-2641) 
callback  QDRRectProc  (II 1-2121 ) 
“Universal  Procedure  Pointers”  (IV-2641) 
callback  QDStdGlyphsProc  (III -2122 ) 
“Universal  Procedure  Pointers”  (IV-2641) 
callback  QDTextProc  ( 1 1 1 -2122 ) 


IXT 


Inside  QuickTime:  Index  of  Data  Types 


V-2939 
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QDTextUPP 

QDTxMeasProcPtr 

QDTxMeasUPP 

QE1  em 

QE1  emPtr 

QHdr 

QHdrPtr 

QTA1 tComponentCheckRecord 
QTAltCPU Rating Record 
QTA1 1 Data  Rate Record 
QTAlt Language Record 
QTAltVersionCheckRecord 
QTAtom 

QTAtomContai ner 

QTAtomlD 

QTAtomSpec 

QTAtomSpecPtr 

QTAtomType 

QTBandwidthNotificationProcPtr 


“Universal  Procedure  Pointers” 
callback  QDTxMeasProc 
“Universal  Procedure  Pointers” 
struct  QElem 
“Memory  Types” 
struct  QHdr 
“Memory  Types” 
struct  QTA1 tComponentCheckRecord 
struct  QTA1 tCPURati ngRecord 
struct  QTA1 tDataRateRecord 
struct  QTA1 tLanguageRecord 
struct  QTAltVersionCheckRecord 
“Atom  Types” 
“Atom  Types” 
“Atom  Types” 
struct  QTAtomSpec 
“Media  Handling  Types” 
“Atom  Types” 


(IV-2641) 
( 1 11-2123 ) 
(IV-2641) 
( I V - 2344 ) 
(IV-2627) 
( I V - 2345 ) 
(IV-2627) 
( I V  -  2  34  5  ) 
(IV-2346) 
( I V - 2347 ) 
(IV-2348) 
( I V - 2348 ) 
(IV-2619) 
(IV-2619) 
(IV-2619) 
(IV-2349) 
(IV-2626) 
(IV-2619) 


QTBandwidthNotificationUPP 
QTBandwidth Reference 
QTCal 1  Back 
QTCal 1 BackFl ags 
QTCal 1 BackHeader 
QTCal 1 BackProcPtr 
QTCal 1 BackType 
QTCal 1 BackUPP 
QTChapterlnfoPtr 
QTChapterlnfo Record 
QTCustomActi onTargetPtr 
QTCustomActi onTarget Record 
QTDoScri ptPtr 
QTDoScri ptRecord 
QTEffectLi stOptions 
QTEval uateExpressi onPtr 
QTEval uateExpressi on  Record 
QTEventRecord 
QTEventRecordPtr 
QTFetch Parameter As Ptr 
QTFetch Parameter As  Record 
QTF1 oatDoubl e 
QTF1 oatSi ngl e 
QTGetChapterTimePtr 
QTGetChapterTimeRecord 
QTGetCursorByIDPtr 
QTGetCursor By  ID Record 
QTGet External  Movi  ePtr 
QTGet External Movi  e Record 


cal  1 


back  QTBandwi dthNotificationProc 
"Universal  Procedure  Pointers” 
“Movie  Types” 
“Timing  and  Callback  Types” 
“Timing  and  Callback  Types” 
struct  QTCal 1 BackHeader 
callback  QTCal 1 BackProc 
“Timing  and  Callback  Types” 
"Universal  Procedure  Pointers” 
“Movie  Controller  Types” 
struct  QTChapterlnfoRecord 
“Media  Handling  Types” 
struct  QTCustomActi onTarget Record 
“Movie  Controller  Types” 
struct  QTDoScri ptRecord 
“Effects  Types” 
“Movie  Controller  Types” 
struct  QTEval uateExpressi on  Record 
struct  QTEventRecord 
“Media  Handling  Types” 
“Movie  Controller  Types” 
struct  QTFetchParameterAsRecord 
“Numeric  Types” 
“Numeric  Types” 
“Movie  Controller  Types” 
struct  QTGetChapterTimeRecord 
“Movie  Controller  Types” 
struct  QTGetCursorBy IDRecord 
“Movie  Controller  Types” 
struct  QTGetExternal Movi eRecord 


( 1 11-2124) 
(IV-2641) 
( I V - 2628 ) 
(IV-2640) 
(IV-2640) 
(IV-2349) 
( 1 11-2124) 
(IV-2640) 
(IV-2641) 
( I V - 2628 ) 
(IV-2351) 
(IV-2626) 
(IV-2351) 
( I V - 2628 ) 
( I V  -  2  3  5  2  ) 
(IV-2622) 
( I V - 2628 ) 
( I V  -  2  3  5  3  ) 
( I V  -  2  3  5  3  ) 
(IV-2626) 
( I V - 2628 ) 
(IV-2354) 
(IV-2631) 
(IV-2631) 
( I V - 2628 ) 
(IV-2355) 
( I V - 2628 ) 
( I V  -  2  3  5  6  ) 
( I V - 2628 ) 
( I V  -  2  3  5  6  ) 


V-2940 


Inside  QuickTime:  Index  of  Data  Types 


QTMIDIComponent 

QTMIDIPort 

QTMIDIPortLi st 

QTMIDIPortLi stHandl e 

QTMIDIPortLi stPtr 

QTMLMutex 

QTMLSyncVar 

QTMLSyncVarPtr 

QTMovi eExportSourcelnfo 

QTMovi eExportSourceRecord 

QTParamDialogEventPtr 

QTParamDi al ogEventRecord 

QTParameterDi  al  og 

QTParameterDi al ogOpti  ons 

QTParameterVal i dati  onOpti  ons 

QTParamFetchPreviewPtr 

QTParamFetchPreviewRecord 

QTParamPreviewPtr 

QTParamPreviewRecord 

QTPresetlnfo 

QTPresetLi stRecord 

QTResol uti onSetti  ngs 

QTRestartAtTimePtr 

QTRestartAtTi  me Record 

QTRuntimeSpri teDescPtr 

QTRuntimeSpri teDescStruct 

QTSAtomContai nerData Struct 

QTSAudi oParams 

QTSBandwi dthAl ertParams 


“Musi c  Types” 
struct  QTMIDIPort 
struct  QTMIDIPortList 
“Music  Types” 
“Music  Types" 
“Windows  Programming  Types” 
“Windows  Programming  Types" 
“Windows  Programming  Types” 
struct  QTMovi eExportSourcelnfo 
struct  QTMovi eExportSourceRecord 
“Effects  Types" 
struct  QTParamDi al ogEventRecord 
“Effects  Types” 
“Effects  Types” 
“Effects  Types" 
“Effects  Types” 
struct  QTParamFetchPreviewRecord 
“Effects  Types” 
struct  QTParamPreviewRecord 
struct  QTPresetlnfo 
struct  QTPresetLi stRecord 
struct  QTResol uti onSetti  ngs 
“Movie  Controller  Types” 
struct  QTRestartAtTimeRecord 
“Sprite  Management  Types” 
struct  QTRuntimeSpri teDescStruct 
struct  QTSAtomContai nerData Struct 
struct  QTSAudioParams 
struct  QTSBandwi dthAl ertParams 
struct  QTSBuf f erTimeAtom 


QTSBufferTimeAtom  struct  QTSBufferTimeAtom 

QTSCanHandleSendDataTypeParams 

struct  QTSCanHandleSendDataTypeParams 


QTScheduledBandwidthHandle 

QTSchedul edBandwi dthPtr 

QTSchedul edBandwi dth Record 

QTSchedul edBandwi dth Reference 

QTSC1 i pRectAtom 

QTSDataRateHi storyParams 

QTSDimensi onParams 

QTSDi rectConnectPrefsRecord 

QTSDurati onAtom 

QTSEdi tEntry 

QTSEdi  t Li  st 

QTSEdi t  Li stHandl e 

QTSEdi  t Li  stPtr 

QTSErrorParams 

QTSetti ngsVersi onAtomRecord 

QTSGetURLLi  nkRecord 

QTSGraphi cs Mode Pa  rams 


“Movie  Types" 
“Movie  Types” 
struct  QTSchedul edBandwi dth Record 
“Movie  Types" 
struct  QTSC1 i pRectAtom 
struct  QTSDataRateHi storyParams 
struct  QTSDimensi onParams 
struct  QTSDi rectConnectPrefsRecord 
struct  QTSDurati onAtom 
struct  QTSEditEntry 
struct  QTSEdi tList 
“Streaming  Types” 
“Streaming  Types” 
struct  QTSErrorParams 
struct  QTSetti ngsVersi onAtomRecord 
struct  QTSGetURLLi nkRecord 
struct  QTSGraphi csModeParams 


(IV-2630) 
(IV-2357) 
(IV-2357) 
(IV-2630) 
(IV-2630) 
(IV-2648) 
(IV-2648) 
(IV-2648) 
( I V  -  2358 ) 
( I V  -  2358 ) 
(IV-2622) 
( I V  -  2  3  5  9 ) 
(IV-2622) 
(IV-2622) 
(IV-2622) 
(IV-2622) 
(IV-2360) 
(IV-2622) 
(IV-2360) 
(IV-2360) 
( I V - 236 1 ) 
( I V  -  2  3  6  2 ) 
(IV-2628) 
( I V  -  2  3  6  2 ) 
(IV-2636) 
( I V  -  2363 ) 
( I V  -  2364 ) 
( I V  -  2364 ) 
( I V  -  2  3  6  5 ) 
(IV-2366) 

(IV-2366) 
(IV-2628) 
(IV-2628) 
(IV-2366) 
(IV-2628) 
( I V  -  2  3  6  7 ) 
(IV-2368) 
(IV-2368) 
( I V  -  2369 ) 
( I V  -  2369 ) 
(IV-2370) 
(IV-2370) 
(IV-2636) 
(IV-2636) 
( I V - 237 1 ) 
( I V - 237 1 ) 
( I V - 237 1 ) 
( I V  -  2  3  7  2 ) 
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QTSInfoParams 
QTSLostPercentParams 
QTSMedi alndSampleDescripti 

st 

QTSMedi aNotificationParams 

QTSMedi aParams 

QTSMedi aPresentationParams 

QTSMedi aStreamHeaderAtom 

QTSMemPtr 

QTSNameParams 

QTSNewPresDetectedParams 

QTSNewPresentationParams 

QTS NewStreamPa rams 

QTSNoProxyPref 

QTSNotificationProcPtr 

QTSNotificationUPP 

QTSPresentati on 

QTSPresentati on Header Atom 

QTSPresentati on  Record 

QTSPresIdl eParams 

QTSpriteButtonBehaviorPtr 

QTSpriteButtonBehaviorStru 

QTSProxyPref 

QTS ProxyP refs  Record 

QTSSampl eDescri pti  on 

QTSSampleDescriptionHandle 

QTSSampl eDescri pti onPtr 

QTSStatHel per 

QTSStatHel per Next Pa  rams 

QTSStatHel per Record 

QTSStatisticsParams 

QTSStatus 

QTSStatusParams 

QTSStream 

QTSStreamBuffer 

QTSStreamChangedParams 

QTSStreamGon eParams 

QTSStreamRecord 

QTStatusStri  ngPtr 

QTStatusStri ng Record 

QTST  ransportPref 

QTSURLParams 

QTSVi deoParams 

QTSVol umesParams 

QTSyncTaskProcPtr 

QTSyncTaskPtr 

QTSyncTaskRecord 

QTSyncTaskUPP 

QTTargetDataSi  ze 


struct  QTSInfoParams 
struct  QTSLostPercentParams 

onParams 

ruct  QTSMedi alndSampl eDescri pti onParams 
struct  QTSMedi aNotificationParams 
struct  QTSMedi aParams 
struct  QTSMedi aPresentationParams 
struct  QTSMedi aStreamHeaderAtom 
“Streaming  Types” 
struct  QTSNameParams 
struct  QTSNewPresDetectedParams 
struct  QTSNewPresentationParams 
struct  QTSNewStreamParams 
struct  QTSNoProxyPref 
callback  QTSNoti f i cati onProc 
"Universal  Procedure  Pointers” 
“Streaming  Types” 
struct  QTSPresentati onHeaderAtom 
struct  QTSPresentati onRecord 
struct  QTSPresIdl eParams 
“Sprite  Management  Types” 
ct  struct  QTSpri teButtonBehavi orStruct 
struct  QTSProxyPref 
struct  QTSProxyPref sRecord 
struct  QTSSampl eDescri  pti  on 
“Streaming  Types” 
“Streaming  Types” 
“Streaming  Types” 
struct  QTSStatHel perNextParams 
struct  QTSStatHel perRecord 
struct  QTSStatisticsParams 
“Streaming  Types” 
struct  QTSStatusParams 
“Streaming  Types” 
struct  QTSStreamBuffer 
struct  QTSStreamChangedParams 
struct  QTSStreamGoneParams 
struct  QTSStreamRecord 
“Movie  Controller  Types” 
struct  QTStatusStri ngRecord 
struct  QTSTransportPref 
struct  QTSURLParams 
struct  QTSVi deoParams 
struct  QTSVol umesParams 
callback  QTSyncTaskProc 
“Timing  and  Callback  Types” 
struct  QTSyncTaskRecord 
"Universal  Procedure  Pointers” 
struct  QTTargetDataSize 


(IV-2372) 

(IV-2373) 

(IV-2373) 
(IV-2374) 
(IV-2374) 
(IV-2375) 
(IV-2375) 
(IV-2636) 
(IV-2376) 
(IV-2376) 
(IV-2376) 
( I V  -  2  3  7  7  ) 
(IV-2378) 
( 1 11-2126 ) 
(IV-2641) 
(IV-2636) 
(IV-2378) 
(IV-2379) 
(IV-2379) 
(IV-2636) 
(IV-2380) 
(IV-2380) 
( I V  -  2381 ) 
( I V  -  2381 ) 
(IV-2636) 
(IV-2636) 
(IV-2636) 
(IV-2382) 
( I V - 2384 ) 
( I V - 2384 ) 
(IV-2636) 
( I V - 2385 ) 
(IV-2636) 
( I V - 2385 ) 
(IV-2386) 
( I V - 2387 ) 
( I V - 2387 ) 
( I V - 2628 ) 
( I V - 2387 ) 
( I V - 2388 ) 
(IV-2389) 
(IV-2389) 
( I V  -  2  3  9  0  ) 
( 1 11-2127 ) 
(IV-2640) 
(IV-2391) 
(IV-2641) 
(IV-2391) 
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QTTweener 

QTTweenerRecord 

QTVi deoOutputComponent 

QTVRAngul arUni ts 

QTVRArea Of  Interest 

QTVRBackBuf f erlmagi ngProcPtr 

QTVRBackBuf f erlmagi  ngUPP 

QTVRControl  Setti  ng 

QTVRCubi cFaceData 

QTVRCubi cVi ewAtom 

QTVRCursorRecord 

QTVREnterl ngNodeProcPtr 

QTVREnteri  ngNodeUPP 

QTVRF1  oatPoi  nt 

QTVRImagi ngCompl eteProcPtr 

QTVRImagi ngCompl  eteUPP 

QTVRImagi ngMode 

QTVRInstance 

QTVRInterceptProcPtr 

QTVRInterceptPtr 

QTVRIntercept Record 

QTVRInterceptUPP 

QTVRLeavi ngNodeProcPtr 

QTVRLeavi ngNodeUPP 

QTV RMous eOver Hot Spot ProcPtr 

QTVRMouseOverHotSpotUPP 

QTVRNudgeControl 

QTVRNudgeMode 

QTVRObjectAni mati on Setti ng 
QTVRPanoImagi  ngAtom 
QTVRProcSel ector 
QTVRVi ewStateType 
RDF1 agsType 
'  rdrf ' 

Rect 

RectPtr 

Ref erenceMovi eData Ref Record 


“Component  Types”  (IV- 
struct  QTTweenerRecord  (IV- 
“Video  Types”  (IV- 
“Virtual  Reality  Types”  (IV- 
struct  QTVRAreaOf Interest  (IV- 
callback  QTVRBackBuf f erlmagi ngProc  (III- 
“Universal  Procedure  Pointers”  (IV- 
“Virtual  Reality  Types”  (IV- 
struct  QTVRCubi cFaceData  (IV- 
struct  QTVRCubi cVi ewAtom  (IV- 
struct  QTVRCursorRecord  (IV- 
callback  QTVREnteri ngNodeProc  (III- 
“Universal  Procedure  Pointers”  (IV- 
struct  QTVRF1 oatPoi nt  (IV- 
callback  QTVRImagi ngCompl eteProc  (III- 
“Universal  Procedure  Pointers”  (IV- 
“Virtual  Reality  Types”  (IV- 
“Virtual  Reality  Types”  (IV- 
callback  QTVRInterceptProc  (III- 
“Virtual  Reality  Types”  (IV- 
struct  QTVRInterceptRecord  (IV- 


"Universal  Procedure  Pointers 
callback  QTVRLeavi ngNodeProc 
“Universal  Procedure  Pointers 
callback  QTV RMous eO ver Hot Spot P roc 
“Universal  Procedure  Pointers" 
“Virtual  Reality  Types" 
“Virtual  Reality  Types" 
“Virtual  Reality  Types” 
struct  QTVRPanoImagi ngAtom 
“Virtual  Reality  Types" 
“Virtual  Reality  Types” 
“System  and  Toolbox  Types” 
atom  'rdrf' 
struct  Rect 
“Memory  Types” 
struct  Ref erenceMovi eData Ref Record 
“Text  Types” 
“Component  Types" 


Regi onCode 

Regi steredComponentlnstancePtr 
Regi ste red Component InstanceRecord 

struct  Regi steredComponentlnstanceRecord 
Regi steredComponentlnstanceRecordPtr  “Component  Types” 


Regi steredComponentPtr 
Regi steredComponentRecord 
Regi steredComponentRecordPtr 
'  reso ' 

Resol vedQTEventSpec 
Resol vedQT Event Spec Ptr 
ResourceSpec 


“Component  Types" 
struct  Regi steredComponentRecord 
“Component  Types" 
atom  'reso' 
struct  Resol vedQTEventSpec 
“Media  Handling  Types” 
struct  ResourceSpec 


(IV- 

(III 

(IV- 

(III- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 


-2621  ) 
-2391) 
-2646) 
-2647) 
-2392) 
-2127) 
-2641) 
-2647) 
-2393) 
-2394) 
-2395) 
-2128) 
-2641) 
-2396) 
-2129) 
-2641) 
-2647) 
-2647) 
-2130) 
-2647) 
-2396) 
-2641) 
-2130) 
-2641) 
-2131) 
-2641) 
-2647) 
-2647) 
-2647) 
-2398) 
-2647) 
-2647) 
-2638) 
-2575) 
-2399) 
-2627) 
-2400) 
-2640) 
-2621  ) 

-2401) 
-2621  ) 
-2621  ) 
-2401) 
-2621  ) 
-2576) 
-2401) 
-2626) 
-2402) 
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ResTypePtr 
RGBCol or 
RGBCol orHdl 
RGBCol orPtr 
RGBRangeRecord 
RgnHandl e 
RgnPtr 
' rmcd ' 

' rmcs ' 

' rmda ' 

' rmdr ' 

' rml a ' 

' rmqu ' 

' rmra ' 

' rmvc ' 

Routi neDescri ptor 
Routi neFl agsType 
Routi neRecord 
RTPMedi aPacketi zer 
RTPMPDataReleaseProcPtr 
RTPMPDataReleaseUPP 
RTPMPPayloadTypeParams 
RTPMPSampleDataParams 
RTPMPSampl eRef 
RTPPacketBui 1 der 
RTPPacketGroupRef 
RTPPacketRef 

RTPPacket Repeated Data  Ref 
RTPPayloadCharacteristic 
RTPPayl oadlnfo 
RTPPayloadlnfoHandle 
RTPPayl oadlnfoPtr 
RTPPayl oadSort Request 
RTPPayl oadSortRequestPtr 
RTPPBCallbackProcPtr 
RTPPBCal 1 backUPP 
RTPReassembl er 
RTPReassembl erlnfo 
RTPReassembl erlnfo Handle 
RTPReassembl erlnfo Ptr 
RTPRssmlni tParams 
RTPRssmPacket 


“System  and  Toolbox  Types”  (IV- 2638 ) 
struct  RGBColor  (IV- 2403 ) 
“Graphics  Types”  (IV-2624) 
“Graphics  Types”  (IV-2624) 
struct  RGBRangeRecord  (IV-2403) 
“Memory  Types”  (IV-2627) 
"Memory  Types”  (IV-2627) 
atom  'rmcd'  (IV-2576) 
atom  'rmcs'  (IV-2577) 
atom  'rmda'  (IV-2577) 
atom  'rmdr'  (IV-2578) 
atom  'rmla'  (IV-2579) 
atom  'rmqu'  (IV-2579) 
atom  'rmra'  (IV-2580) 
atom  'rmvc'  ( I V - 2 581 ) 
struct  Routi neDescri ptor  (IV-2404) 
“System  and  Toolbox  Types”  (IV- 2638 ) 
struct  Routi neRecord  (IV-2405) 
“Streaming  Types”  (IV-2636) 
callback  RTPMPDataRel easeProc  (III -2132 ) 
"Universal  Procedure  Pointers”  (IV- 2641 ) 
struct  RTPMPPayloadTypeParams  (IV-2407) 
struct  RTPMPSampleDataParams  (IV-2407) 
“Streaming  Types”  (IV-2636) 
“Streaming  Types”  (IV-2636) 
“Streaming  Types”  (IV-2636) 
“Streaming  Types”  (IV-2636) 
“Streaming  Types”  (IV-2636) 
struct  RTPPayloadCharacteristic  (IV-2409) 
struct  RTPPayl oadlnfo  (IV-2409) 
“Streaming  Types”  (IV-2636) 
“Streaming  Types”  (IV-2636) 
struct  RTPPayl oadSortRequest  (IV- 241 0 ) 
“Streaming  Types”  (IV-2636) 
callback  RTPPBCal 1 backProc  (III -2133 ) 
"Universal  Procedure  Pointers”  (IV- 2641 ) 
“Streaming  Types”  (IV-2636) 
struct  RTPReassembl erlnfo  (IV- 241 0 ) 
“Streaming  Types”  (IV-2636) 
“Streaming  Types”  (IV-2636) 
struct  RTPRssmlni tParams  (IV-2411) 
struct  RTPRssmPacket  (IV- 241 2 ) 


RTPSendStreamBufferRangeParams 

struct  RTPSendStreamBufferRangeParams 


RTPSSRC 

Sampl eDescri pti on 
SampleDescriptionHandle 
Sampl eDescri pti onPtr 
Sampl eReference64Ptr 


“Streaming  Types” 
struct  Sampl eDescri pti on 
“Media  Handling  Types” 
“Media  Handling  Types” 
“Media  Handling  Types” 


(IV-2413) 
(IV-2636) 
(IV-2414) 
(IV-2626) 
( I V  -  2  6  2  6  ) 
(IV-2626) 
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Sampl eReference64 Record 
Sampl e Refer encePtr 
Sampl e Reference Record 
Sampl eToChunk 
SCDataRateSetti ngs 
SCExtendedProcs 
ScheduledSoundHeader 
ScheduledSoundHeaderPtr 
SCModal Fi 1 terProcPtr 
SCModal  Fi  1  terllPP 
SCModal HookProcPtr 
SCModal HookUPP 
SCParams 
' sept ' 

Seri ptCode 
ScrpSTEl ement 
SCSpati al Setti ngs 
SCStatus 
SCStatusPtr 
SCTemporal Setti ngs 
'  sdp  ' 

' sean ' 

■SelO' 

SeqGrabChannel InfoEnum 
SeqGrabComponent 
SeqGrabDataOutputEnum 
SeqGrabExtended Frame  Info 
SeqGrabExtended Frame  Inf oPtr 
SeqGrabFramelnfo 
SeqGrab Frame  Inf oPtr 
SeqGrabUsageEnum 
SequenceFi 1 terComponent 
SequenceFi IterDataProcPtr 
SequenceFi IterDataUPP 
SFModal Fi 1 terProcPtr 
SFModal FilterUPP 
SFReply 

SGAddFrameBottl eProcPtr 
SGAddFrameBottl  eLIPP 
SGChannel 

SGCompressBottl eProcPtr 
SGCompressBottl  ellPP 
SGCompressCompl eteBottl eProcPtr 


struct  Sampl eReference64Record  (IV-2415) 
“Media  Handling  Types”  ( IV-2626) 
struct  Sampl eReferenceRecord  (IV-2416) 
struct  Sampl eToChunk  (IV-2417) 
struct  SCDataRateSettings  (IV-2417) 
struct  SCExtendedProcs  (IV-2418) 
struct  ScheduledSoundHeader  (IV-2419) 
“Sound  Types”  (IV-2633) 
callback  SCModal Fi 1 terProc  ( 1 1 1  - 2 133 ) 
“Universal  Procedure  Pointers”  (IV-2641) 
callback  SCModal HookProc  ( 1 1 1  - 2 134 ) 
“Universal  Procedure  Pointers”  (IV-2641) 
struct  SCParams  (IV - 2420 ) 
atom  'sept'  (IV-2581) 
“Text  Types”  (IV-2640) 
struct  ScrpSTEl ement  (IV-2422) 
struct  SCSpati al Setti ngs  (IV - 2423 ) 
struct  SCStatus  (IV-2425) 
“Sound  Types”  (IV-2633) 
struct  SCTemporal Setti ngs  (IV-2427) 
atom  'sdp  '  (IV-2582) 
atom  'sean'  (IV-2582) 
atom  'SelO'  (IV-2582) 
“Sequence  Grabbing  Types”  (IV-2632) 
“Sequence  Grabbing  Types”  (IV-2632) 
“Sequence  Grabbing  Types”  (IV-2632) 
struct  SeqGrabExtendedFramelnfo  (IV - 2429 ) 
“Sequence  Grabbing  Types”  (IV-2632) 
struct  SeqGrabFramelnfo  (IV - 2430 ) 
“Sequence  Grabbing  Types”  (IV-2632) 
“Sequence  Grabbing  Types”  (IV-2632) 
“Component  Types”  (IV-2621) 
callback  SequenceFi 1 terDataProc  (III -2135 ) 
“Universal  Procedure  Pointers”  (IV-2641) 
callback  SFModal Fi 1 terProc  ( 1 1 1  - 2 136 ) 
“Universal  Procedure  Pointers”  (IV-2641) 
struct  SFReply  (IV-2431) 
callback  SGAddFrameBottl eProc  ( 1 1 1  - 2 136 ) 
“Universal  Procedure  Pointers”  (IV-2641) 
“Sequence  Grabbing  Types”  (IV-2632) 
callback  SGCompressBottl eProc  (III -2137 ) 
“Universal  Procedure  Pointers”  (IV-2641) 


cal  1 bac 

SGCompressCompl eteBottl eUPP 

SGCompressInfo 

SGDataProcPtr 

SGDataUPP 

SGDevi ceLi st 


SGCompressCompl eteBottl eProc  ( 1 1 1 -2138) 
Universal  Procedure  Pointers”  (IV-2641) 
struct  SGCompressInfo  (IV - 2432 ) 
callback  SGDataProc  (II 1-2139 ) 
Universal  Procedure  Pointers”  (IV-2641) 
“Sequence  Grabbing  Types”  (IV-2632) 
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SGDevi ceLi stPtr 
SGDeviceLi st Record 
SGDevi ceName 
SGDisplayBottleProcPtr 
SGDisplayBottleUPP 
SGDi spl ayCompressBottl  eProc 

SGDi spl ayCompressBottl  eUPP 
SGGrabBottleProcPtr 
SGGrabBottl eUPP 
SGGrabCompl eteBottleProcPtr 
SGGrabCompl eteBottleUPP 
SGGrabCompressCompl eteBottl 

cal  1 

SGGrabCompressCompl eteBottl 

SGModal FilterProcPtr 

SGModal FilterUPP 

SGOutput 

SGOutputRecord 

SGTransferFrameBottleProcPt 

SGTransferFrameBottleUPP 

ShadowSync 

SHChunkRecord 

ShortFi xed 

SHServerEditParameters 

SICCompI etionProcPtr 

SI  Comp 1 etionProcPtr 

SICompI eti onUPP 

Si gnedByte 

SI  InterruptProcPtr 

SI  InterruptUPP 

SIntl6 

SInt32 

SInt64 

SInt8 

Si  ze 

'skip' 

'  smhd ' 

SMPTEF1 ags 
SMPTEFrame Reference 
SMPTEWi peType 
SMStatus 
SMStatusPtr 
Snd2Li stHandl e 
Snd2Li stHndl 
Snd2Li stPtr 
Snd2Li stResource 
SndCal 1 BackProcPtr 
SndCal 1 BackUPP 


“Sequence  Grabbing  Types” 
struct  SGDevi ceLi stRecord 
struct  SGDeviceName 
callback  SGDi spl ayBottl eProc 
"Universal  Procedure  Pointers” 
Ptr 

callback  SGDi spl ayCompressBottl eProc 
"Universal  Procedure  Pointers” 
callback  SGGrabBottl eProc 
"Universal  Procedure  Pointers” 
callback  SGGrabCompl eteBottl eProc 
"Universal  Procedure  Pointers” 

eProcPtr 

back  SGGrabCompressCompl eteBottl eProc 
eUPP  "Universal  Procedure  Pointers” 
callback  SGModal Fi 1 terProc 
"Universal  Procedure  Pointers” 
“Sequence  Grabbing  Types” 
struct  SGOutputRecord 
callback  SGTransferFrameBottl eProc 
"Universal  Procedure  Pointers” 
struct  ShadowSync 
struct  SHChunkRecord 
"Numeric  Types” 
struct  SHServerEditParameters 
callback  SICCompI eti onProc 
callback  SICompI eti onProc 
"Universal  Procedure  Pointers” 
"Numeric  Types” 
callback  SI InterruptProc 
"Universal  Procedure  Pointers” 
"Numeric  Types” 
"Numeric  Types” 
"Numeric  Types” 
"Numeric  Types” 
"Memory  Types” 
atom  'skip' 
atom  'smhd' 
"Effects  Types” 
"Effects  Types” 
"Effects  Types” 
struct  SMStatus 
"Sound  Types” 
"Sound  Types” 
"Sound  Types” 
"Sound  Types” 
struct  Snd2Li stResource 
callback  SndCal 1 BackProc 
"Universal  Procedure  Pointers” 


(IV-2632) 
(IV-2433) 
( I V - 2434 ) 
( 1 11-2140 ) 
(IV-2641) 

( 1 1 1-2141 ) 
(IV-2641) 
( 1 11-2142) 
(IV-2641) 
( 1 11-2143 ) 
(IV-2641) 

( 1 11-2143 ) 
(IV-2641) 
( 1 11-2144) 
(IV-2641) 
(IV-2632) 
( I V - 2435 ) 
( 1 11-2145 ) 
(IV-2641) 
(IV-2436) 
(IV-2436) 
(IV-2631) 
(IV-2437) 
(II 1-2146 ) 
( 1 11-2146 ) 
(IV-2641) 
(IV-2631) 
( 1 11-2147 ) 
(IV-2641) 
(IV-2631) 
(IV-2631) 
(IV-2631) 
(IV-2631) 
( I V  -  2  6  2  7  ) 
(IV-2583) 
( I V - 2584 ) 
(IV-2622) 
(IV-2622) 
(IV-2622) 
( I V - 2438 ) 
(IV-2633) 
( I V  -  2  6  3  3  ) 
(IV-2633) 
(IV-2633) 
(IV-2439) 
( 1 11-2147 ) 
(IV-2641) 
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SndChannel 
SndChannel Ptr 
SndCommand 

SndDoubleBackProcPtr 
SndDoubl eBackUPP 
SndDoubl eBuf fer 
SndDoubl eBufferHeader 
SndDoubl eBufferHeader2 
SndDoubl eBuf ferHeader2 Ptr 
SndDoubl eBufferHeader Ptr 
SndDoubl eBuf fer Ptr 
SndlnputCmpParam 
SndlnputCmpParamPtr 
SndLi stHandl e 
SndLi stHndl 
SndLi  stPtr 
SndLi stResource 
Sound Component Data 
Sound Component Data Ptr 
Sound Component Li nk 
Sound Component Li nkPtr 
SoundConverter 

SoundConverterFi llBufferDataProcPtr 

callback  Soun 

SoundConverterFi llBufferDataUPP 

SoundDescri pti  on 

SoundDescriptionHandle 

SoundDescri pti  onPtr 

SoundDescri pti onVl 

SoundDescri pti onVIHandl e 

SoundDescri pti onVIPtr 

SoundHeader 

SoundHeaderPtr 

SoundHeaderUni  on 

SoundlnfoLi st 

SoundlnfoLi  stPtr 

SoundMedialnfoHeader 

SoundParamBl  ock 

SoundParamBlockPtr 

SoundParamProcPtr 

SoundParamllPP 

Sound SI opeAnd Intercept Ptr 

Sound SI opeAnd Intercept Record  struct 

SoundSource 

SoundSourcePtr 

SourceData 

SPB 

SPBPtr 
Spri te 


struct  SndChannel  (IV- 
“Sound  Types”  (IV- 
struct  SndCommand  (IV- 
callback  SndDoubl eBackProc  (Ill- 
Universal  Procedure  Pointers”  (IV- 
struct  SndDoubl eBuf fer  (IV- 
struct  SndDoubl eBuf ferHeader  (IV- 
struct  SndDoubl eBuf ferHeader2  (IV- 
“Sound  Types”  (IV- 
“Sound  Types”  (IV- 
“Sound  Types”  (IV- 
struct  SndlnputCmpParam  (IV- 
“Sound  Types”  (IV- 
“Sound  Types”  (IV- 
“Sound  Types”  (IV- 
“Sound  Types”  (IV- 
struct  SndLi stResource  (IV- 
struct  SoundComponentData  (IV- 
“Sound  Types”  (IV- 
struct  SoundComponentLi nk  (IV- 
“Sound  Types”  (IV- 
“Sound  Types”  (IV- 

dConverterFi llBufferDataProc  (Ill- 
Universal  Procedure  Pointers”  (IV- 
struct  SoundDescri pti on  (IV- 
“Sound  Types”  (IV- 
“Sound  Types”  (IV- 
struct  SoundDescri pti onVl  (IV- 
“Sound  Types”  (IV- 
“Sound  Types”  (IV- 
struct  SoundHeader  (IV- 
“Sound  Types”  (IV- 
“Sound  Types”  (IV- 
struct  SoundlnfoLi st  (IV- 
“Sound  Types”  (IV- 
struct  SoundMedialnfoHeader  (IV- 
struct  SoundParamBl ock  (IV- 
“Sound  Types”  (IV- 
callback  SoundParamProc  (Ill- 
Universal  Procedure  Pointers”  (IV- 
“Sound  Types”  (IV- 
SoundSl  opeAnd Intercept Record  (IV- 
“Sound  Types”  (IV- 
“Sound  Types”  (IV- 
“Codec  Types”  (IV- 
struct  SPB  (IV- 
“Sound  Types”  (IV- 
“Sprite  Management  Types”  (IV- 
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Spri teDescri pti on 

struct  Spri teDescri pti on 

( I V - 2458 ) 

SpriteDescriptionHandle 

“Sprite  Management  Types” 

(IV-2636) 

Spri teDescri pti onPtr 

“Sprite  Management  Types” 

(IV-2636) 

Spri teRecord 

struct  SpriteRecord 

(IV-2459) 

Spri  teWorl  d 

“Sprite  Management  Types” 

(IV-2636) 

Spri teWorl dRecord 

struct  Spri teWorl dRecord 

(IV-2459) 

SProcHndl 

“System  and  Toolbox  Types” 

(IV-2638) 

SProcPtr 

“System  and  Toolbox  Types” 

( I V - 2638 ) 

SProcRec 

struct  SProcRec 

(IV-2459) 

' sprt ' 

atom  'sprt' 

( I V  -  2584 ) 

' sptl  ' 

atom  'sptl  ' 

(IV-2586) 

SSpLocalizat ion  Data 

struct  SSpLocal i zati onData 

(IV-2460) 

SSpLocati onData 

“Sound  Types” 

(IV-2633) 

SSpVirtual Source Data 

“Sound  Types” 

(IV-2633) 

' ssrc ' 

atom  'ssrc' 

(IV-2586) 

StandardFi 1 eReply 

struct  StandardFi 1 eReply 

( I V - 246 1 ) 

StateBl ock 

struct  StateBlock 

(IV-2463) 

StateBl ockPtr 

“Sound  Types” 

(IV-2633) 

' stbl  ' 

atom  ' stbl  ' 

( I V - 2 587 ) 

' stco ' 

atom  'stco' 

(IV-2589) 

StdPi xProcPtr 

cal  1  back  StdPi xProc 

( 1 11-2149 ) 

StdPixUPP 

"Universal  Procedure  Pointers” 

(IV-2641) 

STHandl e 

“Text  Types” 

(IV-2640) 

StrFi 1 eName 

“String  Types” 

( I V  -  2  6  3  7  ) 

Stri ngHandl e 

“String  Types” 

( I V  -  2  6  3  7  ) 

Stri ngPtr 

“String  Types” 

( I V  -  2  6  3  7  ) 

Stri ngRangeRecord 

struct  Stri ngRangeRecord 

(IV-2463) 

' strt ' 

atom  'strt' 

(IV-2589) 

' stsc ' 

atom  'stsc' 

( I V  -  2  5  9  0  ) 

' stsd ' 

atom  'stsd' 

(IV-2591) 

' stsh ' 

atom  'stsh' 

(IV-2592) 

' stss ' 

atom  'stss' 

( I V  -  2  5  9  3  ) 

' stsz ' 

atom  'stsz' 

(IV-2594) 

' stts ' 

atom  'stts' 

(IV-2595) 

Styl  e 

“Graphics  Types” 

(IV-2624) 

Sty!  eFi  el  d 

“Graphics  Types” 

( I V - 2624 ) 

Styl eParameter 

“Graphics  Types” 

(IV-2624) 

Styl eRun 

“Text  Types” 

(IV-2640) 

' sync ' 

atom  'sync' 

( I V  -  2  5  9  6  ) 

SynthesizerConnections 

struct  SynthesizerConnections 

( I V - 2464 ) 

SynthesizerDescription 

struct  SynthesizerDescription 

( I V - 2465 ) 

' tbox ' 

atom  'tbox' 

( I V  -  2  5  9  7  ) 

' tcmi  ' 

atom  ' tcmi ' 

( I V  -  2  5  9  7  ) 

TCTextOpti ons 

struct  TCTextOpti ons 

( I V - 2468 ) 

TCTextOpti onsPtr 

“Text  Types” 

(IV-2640) 

TEC1 i ckLoopUPP 

"Universal  Procedure  Pointers” 

(IV-2641) 

TEHandl e 

“Text  Types” 

(IV-2640) 

TEPtr 

“Text  Types” 

(IV-2640) 

TERec 

struct  TERec 

(IV-2469) 
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TEStyl eRec 
TextDescri pti on 
TextDescri pti onHandl e 
TextDescri pti onPtr 
TextDi spl ayData 
Text  Expo rtComponent 
TextMedi aProcPtr 
TextMedi  allPP 
ThreeDeeDescri pti on 
ThreeDeeDescri pti onHandl e 
ThreeDeeDescri pti onPtr 
ThreeDeeNonLi nearSample 
ThreeDeeNonLi nearTweenHeaderAtom 

struct 

ThreeDeeVRObjectSampl e 

TimeBase 

TimeBaseFl ags 

TimeBaseRecord 

TimeBaseStatus 

TimeCodeCounter 

TimeCodeDef 

Ti meCodeDescri pti on 

Ti meCodeDescri pti onHandl e 

Ti meCodeDescri pti onPtr 

TimeCodeRecord 

TimeCodeTime 

TimeRecord 

TimeScale 

TimeToSampl eNum 

TimeVal ue 

TimeVal ue64 

' tkhd ' 


struct  TEStyl eRec 
struct  TextDescri pti on 
“Text  Types” 
“Text  Types” 
struct  TextDi spl ayData 
“Component  Types” 
callback  TextMedi aProc 
“Universal  Procedure  Pointers” 
struct  ThreeDeeDescri pti on 
“Media  Handling  Types” 
“Media  Handling  Types” 
struct  ThreeDeeNonLinearSampl e 

ThreeDeeNonLi nearTweenHeaderAtom 
struct  ThreeDeeVRObjectSampl e 
“Timing  and  Callback  Types" 
“Timing  and  Callback  Types” 
struct  TimeBaseRecord 
“Timing  and  Callback  Types” 
struct  TimeCodeCounter 
struct  TimeCodeDef 
struct  TimeCodeDescription 
“Timing  and  Callback  Types” 
“Timing  and  Callback  Types” 
struct  TimeCodeRecord 
struct  TimeCodeTime 
struct  TimeRecord 
“Timing  and  Callback  Types” 
struct  TimeToSampleNum 
“Timing  and  Callback  Types” 
“Timing  and  Callback  Types” 
atom  'tkhd' 


'tmax' 

' tmcd ' 

' tmi n ' 

ToneDescri pti on 
' tpyl  ' 

TQ3Matri x4x4 
T  rack 

T  rackDi rectory 
TrackDi rectory Entry 
T  rackEdi tState 
TrackEdi t St ate Record 
T  rackHeader 
T  rackLoadSetti ngs 
T  rackRecord 
TrackTransferProcPtr 
T  rackT  ransferUPP 
'trak' 


atom  'tmax' 
atom  'tmcd' 
atom  'tmin' 
struct  ToneDescri pti on 
atom  'tpyl ' 
struct  TQ3Matrix4x4 
“Movie  Types” 
“Movie  Types" 
struct  TrackDi rectoryEntry 
“Movie  Types” 
struct  TrackEdi tStateRecord 
struct  TrackHeader 
struct  TrackLoadSetti ngs 
struct  TrackRecord 
callback  TrackTransferProc 
Universal  Procedure  Pointers” 
atom  'trak' 


( I V  -  247  3 ) 
( I V  -  247  4 ) 
(IV-2640) 
(IV-2640) 
( I V - 247 6 ) 
( I V  -  2  6  2 1  ) 
(II 1-2150) 
( I V  -  2  64 1  ) 
( I V  -  247  8 ) 
(IV-2626) 
(IV-2626) 
( I V  -  247  9 ) 

(IV-2480) 
(IV-2480) 
(IV-2640) 
(IV-2640) 
( I V - 248 1  ) 
(IV-2640) 
( I V - 248 1  ) 
( I V  -  2482 ) 
(IV-2483) 
(IV-2640) 
(IV-2640) 
(IV-2484) 
( I V  -  2485 ) 
( I V  -  2486 ) 
(IV-2640) 
( I V  -  2486 ) 
(IV-2640) 
(IV-2640) 
(IV-2598) 
(IV-2598) 
( I V  -  2  5  9  9 ) 
( I V  -  2  5  9  9 ) 
( I V  -  2487 ) 
(IV-2600) 
(IV-2488) 
(IV-2628) 
(IV-2628) 
( I V  -  2489 ) 
(IV-2628) 
( I V  -  2489 ) 
( I V  -  2489 ) 
( I V - 249 1 ) 
(IV-2492) 
( 1 1 1 -2151 ) 
( I V - 2  64 1 ) 
(IV-2600) 
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' tref ' 

' trpy ' 

TuneCallBackProcPtr 
T  uneCal 1 BackUPP 
TunePlayCallBackProcPtr 
TunePlayCailBackUPP 
T  unePl ayer 
T  uneStatus 
' twdt ' 

' twdu ' 

TweenerComponent 

TweenerDataProcPtr 

TweenerDataUPP 

TweenRecord 

TweenSequenceEntry Record 
TweenVIRecord 
' twen ' 

' twnt ' 

' twst ' 

'  ty' 

' udta ' 

UIntl6 

UInt32 

UInt64 

UInt8 

Uni  Char 

Uni CharCount 

UniversalProcHandle 

Uni versal ProcPtr 

Unsi gnedFi xed 

Unsi gnedFi xedPtr 

Unsi gnedWi de 

Unsi gnedWi dePtr 

UserData 

UserDataRecord 

VDCompressi onLi st 

VDCompressi onListHandle 

VDCompressi onListPtr 

VDGammaRecord 

VDGamRecPtr 

Vdi gBufferRec 

Vdi gBufferRecLi st 

Vdi gBufferRecLi stHandl e 

Vdi gBufferRecLi stPtr 

Vdi glntProcPtr 

Vdi glntUPP 

Vdi gType 

Vdi gTypeLi st 

VHSel ect 


atom  'tref'  (IV- 
atom  'trpy'  (IV- 
callback  TuneCal 1 BackProc  (III- 
"Universal  Procedure  Pointers”  (IV- 
callback  TunePl ayCal 1 BackProc  (III- 
"Universal  Procedure  Pointers”  (IV- 
“Music  Types”  (IV- 
struct  TuneStatus  (IV- 
atom  'twdt'  (IV- 
atom  'twdu'  (IV- 
“Component  Types”  (IV- 
callback  TweenerDataProc  (III- 
"Universal  Procedure  Pointers”  (IV- 
struct  TweenRecord  (IV- 
struct  TweenSequenceEntryRecord  (IV- 
struct  TweenVIRecord  (IV- 
atom  'twen'  (IV- 
atom  'twnt'  (IV- 
atom  'twst'  (IV- 
atom  '  ty'  (IV- 
atom  'udta'  (IV- 
“Numeric  Types”  (IV- 
“Numeric  Types”  (IV- 
“Numeric  Types”  (IV- 
“Numeric  Types”  (IV- 
“String  Types”  (IV- 
“String  Types”  (IV- 
"Universal  Procedure  Pointers”  (IV- 
"Universal  Procedure  Pointers”  (IV- 
“Numeric  Types”  (IV- 
“Numeric  Types”  (IV- 
struct  UnsignedWide  (IV- 
“Numeric  Types”  (IV- 
“Movie  Types”  (IV- 
struct  UserDataRecord  (IV- 
struct  VDCompressionList  (IV- 
“Video  Types”  (IV- 
“Video  Types”  (IV- 
struct  VDGammaRecord  (IV- 
“Graphics  Types”  (IV- 
struct  Vdi gBufferRec  (IV- 
struct  Vdi gBufferRecLi st  (IV- 
“Video  Types”  (IV- 
“Video  Types”  (IV- 
callback  VdiglntProc  (III- 
"Universal  Procedure  Pointers”  (IV- 
struct  VdigType  (IV- 
struct  VdigTypeList  (IV- 
“Numeric  Types”  (IV- 


2602) 

2603) 
2152) 
2641) 

2152) 
2641) 

2630) 

2492) 

2604) 

2604) 
2621) 

2153) 
2641) 

2493) 

2494) 

2495) 

2605) 

2605) 

2606) 
2606) 
2607) 

2631) 
2631) 
2631) 
2631) 
2637) 
2637) 
2641) 
2641) 
2631) 
2631) 

2496) 
2631) 
2628) 

2496) 

2497) 
2646) 
2646) 

2498) 
2624) 

2498) 

2499) 
2646) 
2646) 

2154) 
2641) 

2500) 

2501) 
2631) 
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'vide' 

Vi deoBottl es 
Vi deoDi gi ti zerComponent 
Vi deoDi gi ti zerError 
Vi deoMedi alnfoHeader 
' vmhd ' (medi a  ) 

' vmhd ' (transfer) 

' vrcp ' 

' vrni  ' 

' vrnp ' 

' vrsc ' 

'wide' 

Wi dePtr 
Wi ndowPtr 
Wi ndowRef 
'  WLOC ' 

WordBreakUPP 

'wtxt' 

XMLAttri bute 
XMLAttri butePtr 
XMLAttri buteVal ue 
XMLContent 
XMLContentPtr 
XMLDoc 

XMLDocRecord 
XMLE1  ement 
XMLE1 ementContent 
XMLE1 ementPtr 


atom  'vide'  (IV-2610) 
struct  VideoBottles  (IV-2501) 
“Video  Types”  (IV-2646) 
“Video  Types”  (IV-2646) 
struct  VideoMedi alnfoHeader  (IV-2503) 
atom  ' vmhd ' (medi a )  (IV-2611) 
atom  ' vmhd ' (transfer)  (IV-2612) 
atom  'vrcp'  (IV-2612) 
atom  ' vrni '  ( IV-2613) 
atom  'vrnp'  (IV-2614) 
atom  'vrsc'  (IV-2614) 
atom  'wide'  (IV-2614) 
“Numeric  Types”  (IV-2631) 
“Graphics  Types”  (IV-2624) 
“Graphics  Types”  (IV-2624) 
atom  'WLOC'  (IV-2615) 
Universal  Procedure  Pointers”  (IV-2641) 
atom  'wtxt'  (IV-2616) 
struct  XMLAttribute  ( IV-2504) 
“SMIL  Types”  (IV-2633) 
“SMIL  Types”  (IV-2633) 
struct  XMLContent  (IV-2505) 
“SMIL  Types”  (IV-2633) 
“SMIL  Types”  (IV-2633) 
struct  XMLDocRecord  (IV-2505) 
struct  XMLElement  (IV-2505) 
“SMIL  Types”  (IV-2633) 
“SMIL  Types”  (IV-2633) 
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0x0000 

0x00000001 

0x00000002 

0x00000004 

0x00000010 

0x00000100 

0x00001000 

0x0001 

0x00010000 

0x0002 

0x00100000 

AAPNotCreatedErr 

AAPNotFoundErr 

acti vateEvt 

acti  veFl  ag 

adbAddrMask 

addMax 

addOver 

addPi  n 

adMax 

adMi  n 

al  i  gnPi x 

'All F ' 

all  I  n  i  t 

al  pha  Lock 

al phaStage 

anyCodec 

Appl eDataCompressorSubType 
ASDBadForkErr 
ASDBadHeaderErr 
ASDEntryNotFoundErr 
atomlndexInvalidErr 
atomsNotOf SameTypeErr 
Audi oMedi aCharacteri sti c 
autoKey 

auxi 1 i ary Export Data  Una vai 1 abl e 
avai 1 abl eCmd 
'  avr  '  , 

badCal 1 OrderErr 
badComponentSel ector 


function  DragAl i gnedGrayRgn  (1-304) 
function  GetMedi aQual i ty  (1-441) 
function  ImageCodecNewMemory  (11-729) 
struct  ParameterAtomTypeAndID  (IV-2327) 
function  GetMedi aQual i ty  (1-441) 
function  GetMedi aQual i ty  (1-441) 
function  GetMedi aQual i ty  (1-441) 
function  CDSequenceNewMemory  (1-84) 
function  GetMedi aQual i ty  (1-441) 
function  CDSequenceNewMemory  (1-84) 
function  GetMedi aQual i ty  (1-441) 
“Error  Codes"  (IV-2663) 
“Error  Codes”  (IV-2663) 
struct  EventRecord  (IV - 2246 ) 
function  QTVRMouseDown  (11-1391) 
struct  EventRecord  (IV - 2246 ) 
“Graphics  Transfer  Modes”  (IV-2670) 
function  SetDSequenceTransferMode  (III-1591) 
function  SetDSequenceTransferMode  (III-1591) 
function  SetDSequenceTransferMode  (III-1591) 
function  SetDSequenceTransferMode  (III-1591) 
function  NewImageGWorl d  (11-1066) 
atom  ' Al 1 F '  (IV-2511) 
struct  GDevice  (IV-2264) 
function  QTVRMouseDown  (11-1391) 
struct  NumVersion  (IV - 2324 ) 
function  CompressSequenceBegi n  (1-119) 
atom  'dcom'  (IV-2527) 
“Error  Codes”  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Error  Codes"  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Error  Codes”  (IV-2663) 
function  GetMovi  eNext  Interest!'  ngTime  (  1-480) 
struct  EventRecord  (IV-2246) 
“Error  Codes”  (IV-2663) 
“Sound  Commands”  (IV-2691) 
atom  'wtxt'  (IV-2616) 
atom  'wtxt'  (IV-2616) 
function  ComponentSetTarget  (1-112) 


V-2953 


badComponentType 
badDataRef Index 
badDepthErr 
badEdi tlndex 
badEdi t  L i st 
badlmageDescription 
badPublicMovi eAtom 
badT  racklndex 

Bandwi dthManagementPrefsType 

BaseMedi aType 

best Comp  res si  on Codec 

bestFi del i tyCodec 

bestSpeedCodec 

betaStage 

bl ackCol or 

bl  end 

bl ueCol or 

btnState 

bufferCmd 

bufferLength 

bufferPtr 

burstDevi ce 

cal Arabi cCi vi 1 

calArabicLunar 

cal Copti c 

cal Gregori an 

cal  Japanese 

cal Jewi sh 

call BackAt Extremes 
call BackAt Interrupt 
cal  1 BackAtRate 
cal  1 BackAtT i me 
call BackAtT i me Jump 
cal  1 BackCmd 

call  No t Supported By NodeErr 
cal  1 01 d  B i ts 
cal  1 StdBi ts 
cal Persi an 

canMovi  eExportAuxDataHandl e 
canMovi eExportFi 1 es 
canMovi e Expo rtFromProcedu res 
canMovi eExportHandl es 
canMovi eExportVal i dateMovi e 
can Mo vi el mport Data  References 
canMovi el mportFiles 
canMovi el mportHandles 
canMovi el mportlnPl ace 
canMovi el mportPartial 


“Error  Codes”  (IV- 2663 ) 
“Error  Codes”  (IV-2663) 
atom  'wtxt'  (IV-2616) 
“Error  Codes”  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Error  Codes”  (IV-2663) 
function  GetQui ckTi mePreference  (1-507) 
“Component  Identifiers”  (IV-2657) 
function  Comp r ess Sequence Beg i n  ( 1-119 ) 
function  Comp r ess Sequence Beg i n  ( 1-119 ) 
function  Comp r ess Sequence Beg i n  ( 1-119 ) 
struct  NumVersion  (IV-2324) 
“Color  Constants”  (IV-2657) 
function  SetDSequenceTransferMode  (III -1591 ) 
“Color  Constants”  (IV-2657) 
function  QTVRMouseDown  (11-1391) 
“Sound  Commands”  (IV- 269 1 ) 
function  SPBRecord  (III -1878 ) 
function  SPBRecord  (III -1878 ) 
struct  GDevice  (IV-2264) 
“Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
function  NewCallBack  (11-1053) 
function  Cl ockNewCall Back  (1-96) 
function  Cl ockNewCall Back  (1-96) 
function  Cl ockNewCall Back  (1-96) 
function  Cl ockNewCall Back  (1-96) 

“Sound  Commands”  (IV-2691) 
“Error  Codes”  (IV-2663) 
function  StdPix  (III-1912) 
function  StdPix  (III-1912) 
"Localization  Codes”  (IV-2673) 
struct  ComponentDescri pti on  (IV-2212) 
struct  ComponentDescri pti on  (IV-2212) 
struct  ComponentDescri pti on  (IV-2212) 
struct  ComponentDescri pti on  (IV-2212) 
struct  ComponentDescri pti on  (IV-2212) 
struct  ComponentDescri pti on  (IV-2212) 
struct  ComponentDescri pti on  (IV-2212) 
struct  ComponentDescri pti on  (IV-2212) 
struct  ComponentDescri pti on  (IV-2212) 
struct  ComponentDescri pti on  (IV-2212) 


canMovi elmportVal i dateDataReferences  struct  ComponentDescri pti on  (IV-2212) 
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canMovi elmportVal i dateFi 1 e 
canMovi elmportVal idateHandles 
can not Be  Leaf AtomErr 
cannotFi ndAtomErr 
cantCreateSi ngl eForkFi 1 e 
cantEnabl eT  rack 
cantFi ndHandl er 
cantOpenHandl er 
cantPutPubl i cMovi eAtom 
cantRecei veFromSynthesi zerOS Err 
cantSendToSynthesizerOSErr 
channel  FlagDontOpenResFile 
channel FlagHasDependency 
channel  PI ayAl 1  Data 
channel  PI  ayFast 
channelPlayHighQuality 
channel  PI ayNormal 
' chap ' 

charCodeMask 

'clip' 

Cl  ipAID 
cl i pPi x 

cl ockComponentCmd 

cl ockComponentType 

cl utType 

cmdKey 

' cmov ' 

cmpSH 

' cmvd ' 

' co64 ' 

'CODE' 

codecAbortErr 

codecBadDataErr 

codecCanAsync 

codecCanAsyncWhen 

codecCanCl i pRectangul ar 

codecCanCl i pVerti cal 

codecCanCopyPrev 

codecCanCopyPrevComp 

codecCanFastDither 

codecCanMakeMask 

codecCanManagePrevBuffer 

codecCanMask 

codecCanMatte 

codecCanRemapCol or 

codecCanScal e 

codecCanShieldCursor 

codecCanShi ft 

codecCanSpool 


struct  ComponentDescri pti on  (IV-2212) 
struct  ComponentDescri pti on  (IV-2212) 
“Error  Codes"  (IV-2663) 
“Error  Codes”  (IV-2663) 
atom  'wtxt'  (IV-2616) 
“Error  Codes”  (IV-2663) 
“Error  Codes"  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Error  Codes"  (IV-2663) 
“Error  Codes”  (IV-2663) 
struct  ComponentDescri pti on  (IV-2212) 
struct  ComponentDescri pti on  (IV-2212) 
f uncti on  SGGetChannel PI  ay Flags  (III-1705) 
function  SGGetChannel PI  ay Flags  (III-1705) 
function  SGGetChannel PI  ay Flags  ( 1 1 1  - 1 705 ) 
function  SGGetChannel PI  ay Flags  (III-1705) 
atom  'chap'  (IV-2512) 
struct  EventRecord  (IV-2246) 
atom  'clip'  (IV-2513) 
“Atom  ID  Codes”  (IV-2649) 
function  NewImageGWorl d  (11-1066) 
“Sound  Commands”  (IV-2691) 
“Component  Identifiers”  (IV-2657) 
struct  GDevice  (IV-2264) 
function  QTVRMouseDown  (11-1391) 
atom  'cmov'  (IV-2514) 
struct  CmpSoundHeader  (IV-2176) 
atom  'cmvd'  (IV-2514) 
atom  ' co64 '  (IV-2515) 
struct  ResourceSpec  (IV-2402) 
“Error  Codes”  (IV-2663) 
“Error  Codes”  (IV-2663) 
struct  CodecCapabi 1 i ti es  (IV-2179) 
struct  CodecCapabi 1 i ti es  (IV-2179) 
struct  CodecCapabi 1 i ti es  (IV-2179) 
struct  CodecCapabi 1 i ti es  (IV-2179) 
struct  CodecCapabi 1 i ti es  (IV-2179) 
struct  CodecCapabi 1 i ti es  (IV-2179) 
struct  CodecCapabi 1 i ti es  (IV-2179) 
struct  CodecCapabi 1 i ti es  (IV-2179) 
struct  CodecCapabi 1 i ti es  (IV-2179) 
struct  CodecCapabi 1 i ti es  (IV-2179) 
struct  CodecCapabi 1 i ti es  (IV-2179) 
struct  CodecCapabi 1 i ti es  (IV-2179) 
struct  CodecCapabi 1 i ti es  (IV-2179) 
struct  CodecCapabi 1 i ti es  (IV-2179) 
struct  CodecCapabi 1 i ti es  (IV-2179) 
struct  CodecCapabi 1 i ti es  (IV-2179) 
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codecCanSrc Extract 
codecCantQueueErr 
codecCanTransferMode 
codecCanTransform 
codecCantWhenErr 
codecCompl eti onDest 
codecCompl etionDontUnshield 
codecCompl etionSource 
codecConditionCatchUpDiff 
codecConditionCodecChangedMask 
codecConditionDoCursor 
codecCondi ti onErr 
codecConditionFirstBand 
codecCondi tionFirstFrame 
codecCondi tionFirstScreen 
codecCondi tionLastBand 
codecCondi ti onMaskMayBeChanged 
codecCondi ti onNewAccuracy 
codecCondi ti onNewCl ut 
codecCondi tionNewDepth 
codecCondi tionNewDesti nation 
codecCondi ti onNewMatte 
codecCondi ti onNewSrcRect 
codecCondi ti onNewT  ransferMode 
codecCondi ti onNewT  ransform 
codecCondi ti onToBuffer 
codecDataVersErr 
codecDi sabl edErr 
codecDroppedFrameErr 
codecErr 

codec  Ext en si onNotFoundErr 
codecFlagCatchUpDiff 
codec  FI agDon tOff screen 
codec  FI agDontUselmageBuffer 
codec  FI agDontUseNewImageBuffer 
codec  FI  a g Force Key  Frame 
codecFlaglnterlacellpdate 
codecFl  agLi  veGrab 
codecFlagNoScreenUpdate 
codecFlagOnlyScreenllpdate 
codecFlagllpdatePrevious 
codecFlagUpdatePrevi o us Comp 
codec  FI  a  gllsedl  mage  Buffer 
codec  FI  agllsedNewImageBuffer 
codec  FI  a gUs el mage Buffer 
codec  FI  a  gllseScreen  Buffer 
codec  FI  a gWas Compressed 
codecHasVolatil eBuffer 
codecHi ghQual i ty 


struct  CodecCapabi 1 i ti es  (IV-2179) 
“Error  Codes”  (IV-2663) 
struct  CodecCapabi 1 i ti es  (IV-2179) 
struct  CodecCapabi 1 i ti es  (IV-2179) 
“Error  Codes”  (IV-2663) 
function  ICMDecompressCompl ete  (11-671) 
function  ICMDecompressCompl ete  (11-671) 
function  ICMDecompressCompl ete  (11-671) 
struct  CodecDecompressParams  (IV-2190) 
struct  CodecCompressParams  (IV-2184) 
struct  CodecDecompressParams  (IV-2190) 
“Error  Codes”  (IV-2663) 
struct  CodecCompressParams  (IV-2184) 
struct  CodecDecompressParams  (IV-2190) 
struct  CodecDecompressParams  (IV-2190) 
struct  CodecCompressParams  (IV-2184) 
struct  CodecDecompressParams  (IV-2190) 
struct  CodecDecompressParams  (IV-2190) 
struct  CodecDecompressParams  (IV-2190) 
struct  CodecDecompressParams  (IV-2190) 
struct  CodecDecompressParams  (IV-2190) 
struct  CodecDecompressParams  (IV-2190) 
struct  CodecDecompressParams  (IV-2190) 
struct  CodecDecompressParams  (IV-2190) 
struct  CodecDecompressParams  (IV-2190) 
struct  CodecDecompressParams  (IV-2190) 
"Error  Codes”  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Error  Codes”  (IV-2663) 
function  DecompressSequenceFrameS  (1-243) 
function  DecompressSequenceFrameS  (1-243) 
function  Decomp r ess Sequence Beg i nS  ( 1-239 ) 
function  DecompressSequenceFrameS  (1-243) 
function  CompressSequenceFrame  (1-124) 
function  DecompressSequenceFrameS  (1-243) 
function  CompressSequenceFrame  (1-124) 
function  DecompressSequenceFrameS  (1-243) 
function  DecompressSequenceFrameS  (1-243) 
function  CompressSequenceBegi n  (1-119) 
function  CompressSequenceBegi n  (1-119) 
function  DecompressSequenceFrameS  (1-243) 
function  DecompressSequenceFrameS  (1-243) 
function  Decomp r ess Sequence Beg i nS  ( 1-239 ) 
function  Decomp r ess Sequence Beg i nS  ( 1-239 ) 
function  CompressSequenceBegi n  ( 1-119 ) 
struct  CodecCapabi 1 i ti es  (IV-2179) 
function  Compresslmage  (1-113) 
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codecImageBuf Err 

codecImageBuf f erlsOnScreen 

codecInfoDepthl 

codecInfoDepthl6 

codecInfoDepth2 

codecInfoDepth24 

codecInfoDepth32 

codecInfoDepth33 

codecInfoDepth34 

codecInfoDepth36 

codecInfoDepth4 

codecInfoDepth40 

codecInfoDepth8 

codecInfoDoesl 

codecInfoDoesl6 

codecInfoDoes2 

codecInfoDoes32 

codecInfoDoes4 

codecInfoDoes8 

codecInfoDoesBlend 

codecInfoDoesDither 

codecInfoDoesDouble 

codecInfoDoesHal f 

codecInfoDoesHorizFlip 

codecInfoDoesLossless 

codecInfoDoesMask 

codecInfoDoesQuad 

codecInfoDoesQuarter 

codecInfoDoesRateConstrai n 

codec  I nf oDoes Recompress 

codec  I nfoDoes Rotate 

codecInfoDoesShrink 

codecInfoDoesSpool 

codec  I nfoDoes St retch 

codec  Inf oDoesTemporal 

codecInfoDoesVertFlip 

codecInfoDoesWarp 

codeclnf oHas Effect Parameter LI st 

codecInfoSequenceSensi five 

codecInfoStoresClut 

codec Los  si essQual i ty 

codecLowQual i ty 

codecMaxQual i ty 

codecMi nQual i ty 

codecNeedAccessKeyErr 

codecNeedToFl ushChainErr 

codecNoMemoryPl easeWaitErr 

codecNormal Quality 

codecNothingToBlitErr 


“Error  Codes” 

(IV-2663) 

struct  CodecCapabi 1 i ti es 

(IV-2179) 

struct 

Codeclnfo 

( I V  -  2  2  0  2 ) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

struct 

Codeclnfo 

(IV-2202) 

function  Compress  Image  (1-113) 
function  Compress  Image  (1-113) 
function  Compress  Image  (1-113) 
function  Compress  Image  (1-113) 
“Error  Codes”  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Error  Codes”  (IV-2663) 
function  Compress  Image  (1-113) 
“Error  Codes”  (IV-2663) 
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codecOffscreenFai 1 edErr  “Error  Codes”  (IV-2663) 
codecOffscreenFai 1 edPl easeRetryErr  “Error  Codes”  (IV-2663) 
codecOpenErr  “Error  Codes”  (IV-2663) 
codecParameterDialogConfirm 


function  QTIsStandardParameterDial ogEvent  (11-1186) 


codecProgressClose 

callback  ICMProgressProc 

( I 11-2093 ) 

codecProgressOpen 

callback  ICMProgressProc 

( I 11-2093 ) 

codecProgressUpdatePercent 

callback  ICMProgressProc 

( I 11-2093 ) 

codecScreenBuf Err 

“Error 

Codes” 

(IV-2663) 

codecSi zeErr 

“Error 

Codes” 

(IV-2663) 

codecSpool Err 

“Error 

Codes” 

(IV-2663) 

codecUni mpErr 

“Error 

Codes” 

(IV-2663) 

codecWantsDestinationPixels 

struct  CodecCapabi 

1 i ti es 

(IV-2179) 

codecWantsSpecial Scaling 

struct  CodecCapabi 

1 i ti es 

(IV-2179) 

codecWoul dOff screen  Err 

“Error 

Codes” 

(IV-2663) 

Col orTabl eAID 

“Atom  ID 

Codes” 

(IV-2649) 

compl eti onRouti ne 

function  SPBRecord 

( I 11-1878) 

component AutoVersi onlncludeFlags 

struct 

Component Resource Extensi on 

(IV-2221) 

componentDl lEntryNotFoundErr 

atom 

'wtxt ' 

(IV-2616) 

componentDl 1 LoadErr 

atom 

'wtxt ' 

(IV-2616) 

component DoAutoVersi on 

struct 

Component ResourceExtensi on 

(IV-2221) 

componentHasMul ti pi ePl atforms 

struct 

Component ResourceExtensi on 

(IV-2221) 

component  Load Res i dent 

struct 

Component Resource Extensi  on 

(IV-2221) 

componentWantsUnregi ster 

struct 

Component Resource Extensi  on 

(IV-2221) 

composi teln 

function  VDGetlnputFormat 

( I 11-2005) 

CompressedMovi eAID 

“Atom  ID 

Codes” 

(IV-2649) 

CompressedMovi eDataAID 

“Atom  ID 

Codes” 

(IV-2649) 

compressorComponentType 

“Component  Identifiers” 

( I V  -  2  6  5  7  ) 

ConnectionSpeedPrefsType 

function  GetQuickTimePreference  (1-507) 

constraintReachedErr 

“Error 

Codes” 

(IV-2663) 

control  Key 

function  QTVRMouseDown 

(11-1391) 

convertClipboardFlag 

struct  EventRecord 

(IV-2246) 

'©cpy ' 

atom 

'©cpy ' 

(IV-2515) 

'©day ' 

atom 

'©day ' 

(IV-2516) 

'©dir' 

atom 

'©dir' 

( I V  -  2  5 1 7  ) 

'©edl ' 

atom 

'©edl ' 

( I V  -  2  5 1 7  ) 

'©fmt ' 

atom 

'©fmt ' 

( IV-2518) 

'©inf' 

atom 

'©inf' 

(IV-2519) 

'©prd ' 

atom 

'©prd ' 

(IV-2519) 

'©prf ' 

atom 

'©prf' 

( I V  -  2  5  2  0  ) 

'©req ' 

atom 

'©req ' 

(IV-2521) 

'©src ' 

atom 

'©src ' 

(IV-2521) 

'©wrt ' 

atom 

'©wrt ' 

(IV-2522) 

couldNot Resolve Data  Ref 

“Error 

Codes” 

(IV-2663) 

coul  dNotUseAnExi stingSample 

“Error 

Codes” 

(IV-2663) 

count 

function  SPBRecord 

( I 11-1878) 

CreateFilePrevi ewComponentType 

“Component  Identifiers” 

( I V  -  2  6  5  7  ) 

createMovieFileDeleteCurFile  function  ConvertFil eToMovi eFile  (1-129) 
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createMovi eFi 1 eDontCreateMovi e 
createMovi eFi 1 eDon tC reate Res Fi 1 e 
createMovi eFileDontOpenFile 
' crgn ' 

'crsr' 

' cspd ' 

' ctab ' 

'  cut  a ' 

'CURS' 

'  CUVW' 

' cvi d ' 
cyanCol or 
' dasz ' 

dataAl readyCl osed 

dataAl ready Open ForWri te 

DataCompressi onAtomAID 

DataFlandl  erType 

DatalnfoAID 

dataNoDataRef 

dataNotOpenForRead 

da taNotOpen ForWri te 

DataRefAID 

Data  Ref ContainerAID 

dataRefSel f Reference 

data  Ref Was  Not Resol ved 

dbBuf f erReady 

dbLastBuf fer 

'dcom' 

decomp res sorComponent Type 
def  a  ill  tComponentAny  FI  ags 
def a ul tComponentAnyManuf acturer 
def aul tComponentAnySubType 
defaul tComponentldenti cal 
def aul t  D i ther 
' def  i  ' 

' desc ' 

devel opStage 


df Anti  Alias 

f uncti on 

dfCl i pToTextBox 

f uncti on 

dfContinuous Karaoke 

f uncti on 

dfConti nuousScrol 1 

f uncti on 

df DontAutoScal e 

f uncti on 

df DontDi s pi  ay 

f uncti on 

df DropShadow 

f uncti on 

df  FI  owHori  z 

f uncti on 

dfHori zScrol 1 

f uncti on 

df InverseHi 1 i te 

f uncti on 

df KeyedText 

f uncti on 

'  df  1 1 ' 


function  CreateMovi eFi 1 e  (1-145) 
function  CreateMovi eFi 1 e  (1-145) 
function  CreateMovi eFi 1 e  (1-145) 
atom  'crgn'  ( IV-2523) 
atom  'crsr'  (IV-2524) 
atom  'cspd'  (IV-2524) 
atom  'ctab'  (IV-2525) 
atom  'cufa'  (IV-2525) 
atom  'CURS'  (IV-2526) 
(IV-2526) 
(III - 1744 ) 
(IV-2657) 


IXC 


(IV-2663) 
(IV-2663) 
( I V  -  2  64  9 ) 
(IV-2657) 
( I V  -  2  64  9 ) 
(IV-2663) 
(IV-2663) 
(IV-2663) 
( I V  -  2  64  9 ) 
( I V  -  2  64  9 ) 
(1-427) 
(1-427) 

( I V  -  2442 ) 
( I V  -  2442 ) 
( I V  -  2  5  27 ) 
(IV-2657) 
( 1 11-1581 ) 
( 1 11-1581 ) 
( 1 11-1581 ) 
( 1 11-1581 ) 
(1-311) 
atom  'defi '  (IV-2528) 
atom  'desc'  (IV-2528) 
struct  NumVersion  (IV- 2324 ) 
TextMedi aAddTESampl e  (III - 1933 ) 
TextMedi aAddTESampl e  (III - 1933 ) 
TextMedi aAddTESampl e  (III - 1933 ) 
TextMedi aAddTESampl e  (III - 1933 ) 
TextMedi aAddTESampl e  (III - 1933 ) 
TextMedi aAddTESampl e  (III - 1933 ) 
TextMedi aAddTESampl e  (III - 1933 ) 
TextMedi aAddTESampl e  (III - 1933 ) 
TextMedi aAddTESampl e  (III - 1933 ) 
TextMedi aAddTESampl e  (III - 1933 ) 
TextMedi aAddTESampl e  (III - 1933 ) 
atom  ' df 1 1 '  ( I V - 2 5 2 9 ) 


atom  'cuvw' 

function  SGGetVi deoCompressorType 
“Color  Constants” 
atom  'dasz' 
“Error  Codes” 
“Error  Codes” 
“Atom  ID  Codes” 
“Component  Identifiers” 
“Atom  ID  Codes” 
“Error  Codes” 
“Error  Codes” 
“Error  Codes” 
“Atom  ID  Codes” 
“Atom  ID  Codes” 
function  GetMedi aDataRef 
function  GetMedi aDataRef 
struct  SndDoubl eBuf f er 
struct  SndDoubl eBuf fer 
atom  'dcom' 
“Component  Identifiers 
function  SetDef aul tComponent 
function  SetDef aul tComponent 
function  SetDef aul tComponent 
function  SetDef aul tComponent 
function  DrawTrimmedPi cture 
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df ReverseScrol 1 

dfScrol 1  In 

dfScrol 1  Out 

dfShri  nkTextBoxToFi t 

dfTextCol orHi 1 i te 

di gi InDoesBW 

di gi InDoesCol or 

di gi In  Does Component 

di gi In Does Compos i te 

di gi InDoesGenLock 

di gi InDoesNTSC 

di gi InDoesPAL 

di gi InDoesSECAM 

di gi InDoesSVi deo 

di gi InSi gnal Lock 

di gi InVTR_Broadcast 

di gi OutDoesl 

di gi 0utDoesl6 

di gi 0utDoes2 

di gi 0utDoes32 

di gi 0utDoes4 

di gi 0utDoes8 

di gi Out Does AsyncGrabs 

di gi OutDoesBl end 

di gi OutDoesCompress 

digi OutDoesCompressOnly 

digi OutDoesCompress Parti al lyVi sibl e 


function  TextMediaAddTESampl e  (III 
function  TextMediaAddTESampl e  (III 
function  TextMediaAddTESampl e  (III 
function  TextMediaAddTESampl e  (III 
function  TextMediaAddTESampl e  (III 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
“Video  Digitizer  Capabilities” 

struct  Di gi ti zerlnfo  (IV 
struct  Di gi ti zerlnfo  (IV 
struct  Di gi ti zerlnfo  (IV 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo  (IV 
struct  Di gi ti zerlnfo  (IV 
struct  Di gi ti zerlnfo  (IV 
struct  Di gi ti zerlnfo  (IV 
struct  Di gi ti zerlnfo  (IV 


(IV 

(IV 

(IV 

(IV 

(IV 

(IV 

(IV 

(IV 

(IV 


(IV 

(IV 

(IV 

(IV 


1933) 

1933) 

1933) 

1933) 

1933) 

2234) 

2234) 

2234) 

2234) 

2234) 

2234) 

2234) 

2234) 

2696) 

2234) 

2234) 

2234) 

2234) 

2234) 

2234) 

2234) 

2234) 

2234) 

2234) 

2234) 

2234) 


di gi OutDoesDi ther 
di gi OutDoesDMA 
di gi OutDoesDoubl e 
digi  Out  DoesHorizFlip 
di gi OutDoesHW_DMA 
di gi OutDoesHWPl ayThru 
di gi OutDoes I LUT 
digi Out Does  Key Col  or 
di gi OutDoesMask 

digi Out DoesPl ayThruDuri ngCompress 

di gi OutDoesQuad 

digi Out DoesQuarter 

di gi OutDoesRotate 

di gi OutDoesShri nk 

di gi OutDoesSixteenth 

di gi OutDoesSkew 

digi Out DoesStretch 

digi Out DoesUnreadableScreenBits 

digiOutDoesVertFlip 

di gi OutDoesWarp 

di gi tlnDoesSVi deo 


“Video  Digitizer  Capabilities” 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
“Video  Digitizer  Capabilities” 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 
struct  Di gi ti zerlnfo 


(IV-2696) 

(IV-2234) 

(IV-2234) 

(IV-2234) 

(IV-2234) 

(IV-2696) 

(IV-2234) 

(IV-2234) 

(IV-2234) 

(IV-2234) 

(IV-2234) 

(IV-2234) 

(IV-2234) 

(IV-2234) 

(IV-2234) 

(IV-2234) 

(IV-2234) 

(IV-2234) 

(IV-2234) 

(IV-2234) 

(IV-2234) 

(IV-2234) 
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di gi ti zerOf f 
di gi ti zerOn 
di gi Uni mpErr 
' d i mm ' 

'  d  i  n  f ' 
di rectType 

di rectXObjectAl readyExi sts 

di skEvt 

di therCopy 

di therPi x 

'dmax' 

' dmed ' 

dontAutoFi 1 eMovi e Import 
dontRegi sterWi th Easy Open 
' dref ' 

'  drep ' 

dupl i cateAtomTypeAndIDErr 
' eat  '  , 

Ed i  t  Li stAID 
Ed i tsAID 
' edts ' 

effectlsRealtime 
elOptionsIncludeNonelnList 
'  el  st ' 

emptyPathErr 
'  end  ' 

' enda ' 

endOfDataReached 

error 

evenFi eldlToEvenFieldOut 


function  VDSetPl ayThruOnOf f  (III -2050 ) 
function  VDSetPl ayThruOnOf f  (III -2050 ) 
atom  'wtxt'  (IV-2616) 
atom  'dimm'  ( IV-2529) 
atom  'dinf'  (IV-2530) 
struct  GDevice  ( IV-2264) 
“Error  Codes”  ( IV-2663) 
struct  EventRecord  (IV-2246) 
function  SetDSequenceT ransferMode  (III-1591) 
function  NewImageGWorl d  (11-1066) 
atom  'dmax'  (IV-2531) 
atom  'dmed'  (IV-2531) 
struct  ComponentDescri pti on  (IV-2212) 
struct  ComponentDescri pti on  (IV-2212) 
atom  'dref'  (IV-2532) 
atom  'drep'  (IV-2532) 
“Error  Codes"  (IV-2663) 
atom  'wtxt'  (IV-2616) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
atom  'edts'  (IV-2533) 
function  QTGetEf fectSpeed  (11-1176) 
function  QTGetEffectsLi st  (11-1174) 
atom  'elst'  (IV-2533) 
“Error  Codes”  (IV-2663) 
atom  'end  '  (IV-2534) 
atom  'enda'  (IV-2535) 
“Error  Codes”  (IV-2663) 
function  SPBRecord  (III- 1878 ) 


function  ImageCodecExtractAndCombi neFi el ds  (11-705) 

even  Fi  el  dlToOddFi  el  dOut 


function  ImageCodecExtractAndCombi neFi el ds  (11-705) 
evenFi  el  d2ToEvenFi  el  dOut 


function  ImageCodecExtractAndCombi neFi el ds  (11-705) 

evenFi  el  d2To0ddFi  el  dOut 


' expo ' 

'  ext  ' 

ext32Devi ce 
extSH 

featureUn supported 
fi 1 eOffsetTooBi gErr 
f i nal Stage 

f i ndTextCaseSensi ti ve 
f i ndTextEdgeOK 
fi ndTextReverseSearch 
fi ndTextUseOf f set 
f i ndTextWrapAround 


function  ImageCodecExtractAndCombi neFi el ds  (11-705) 

atom  'expo'  (IV-2535) 
atom  'ext  '  (IV-2536) 
struct  GDevice  (IV-2264) 
struct  CmpSoundHeader  (IV-2176) 
function  QTIsStandardParameterDi al ogEvent  (11-1186) 

“Error  Codes”  (IV-2663) 
struct  NumVersion  (IV- 2324 ) 
function  TextMedi aFindNextText  (III- 1941 ) 
function  TextMedi aFindNextText  (III- 1941 ) 
function  TextMedi aFindNextText  (III- 1941 ) 
function  TextMedi aFindNextText  (III- 1941 ) 
function  TextMedi aFindNextText  (III- 1941 ) 
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f i xedCompressi on 
f i xedType 
'flap' 

FI ashMedi aType 

fl atten Ac tiveT racks Only 

flatten AddMo vieTo Da taFork 

flatten DontlnterleaveFl atten 

f 1 ushCmd 

fl ushFromRam 

forceDi ther 

' free ' 

FreeAtomType 

' f rma ' 

fsCurPerm 

fsRdPerm 

fsRdWrPerm 

fsRdWrShPerm 

fsWrPerin 

ft Adobe Premi ereMovi e 
ftAfterDarkModul e 
ftCl i p3Dgraphi c 
ftCri cketChart 
ftCri cketDrawi ng 
ftDesi gnCADDrawi ng 
ftlmageStudioGraphic 
ftKaleidaGraphGraphic 
ftMacFl owChart 
ftMacSpi nDataSet 
ftMovi ePl ayerMovi e 
ft  P i xel Pai nt 
ftSuper3DDrawi ng 
ftSwi vel 3DDrawi ng 
ftVersaCADDrawi ng 
' ftyp ' 

fullScreenAl low Events 

full  Screen DontChangeMenuBar 

fullScreenHi deCursor 

fullScreenPreflightSize 

gdDevType 

'geff ' 

Generi cMedi alnfoAID 
GenericMedialnfoFleaderAID 
getCl ockComponentCmd 
getRateMul ti pi i erCmd 
getVol umeCmd 
' gmhd ' 

' gmi n ' 

grabPictCurrentlmage 
grabPi ctlgnoreCl i p 


function  GetCompressionlnfo  (1-398) 
struct  GDevice  (IV-2264) 
atom  'flap'  (IV-2537) 
“Component  Identifiers”  (IV-2657) 
function  FlattenMovie  (1-372) 
function  FlattenMovie  (1-372) 
function  FlattenMovie  (1-372) 
“Sound  Commands”  (IV- 269 1 ) 
function  LoadMedialntoRam  (11-779) 
function  DrawTri mmedPi cture  (1-311) 
atom  'free'  (IV- 2538 ) 
“Atom  ID  Codes”  (IV-2649) 
atom  'frma'  (IV- 2538 ) 
function  OpenMovi eFi 1 e  (11-1133) 
function  OpenMovi eFi 1 e  (11-1133) 
function  OpenMovi eFi 1 e  (11-1133) 
function  OpenMovi eFi 1 e  (11-1133) 
function  OpenMovi eFi 1 e  (11-1133) 
"File  Types  and  Creators”  (IV- 2668 ) 

"File  Types  and  Creators”  (IV- 2668 ) 

"File  Types  and  Creators”  (IV- 2668 ) 

“File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

“File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

“File  Types  and  Creators”  (IV-2668) 

“File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

“File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

“File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

atom  'ftyp'  (IV-2539) 
function  Begi nFul 1  Screen  (1-52) 
function  BeginFul 1  Screen  (1-52) 
function  Begi nFul 1  Screen  (1-52) 
function  BeginFul 1  Screen  (1-52) 

struct  GDevice  (IV-2264) 
struct  EffectSource  (IV- 2243 ) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
“Sound  Commands”  (IV- 269 1 ) 
“Sound  Commands”  (IV- 269 1 ) 
“Sound  Commands”  (IV- 269 1 ) 
atom  'gmhd'  (IV-2539) 
atom  'gmin'  (IV-2540) 
function  SGGrabPict  (III -1748 ) 
function  SGGrabPict  ( 1 1 1-1748) 
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grabPi ctOff Screen 

graphi cs ImporterDoesntDrawAl 1  Pixel s 

function  Gra 

graphi csImporterDontKnowlfDrawAl  1  Pixel 

function  Gra 

graphi cs ImporterDrawsAl 1  Pixel s 

function  Gra 

grayi shTextOr 
greenCol or 
gwFl  agErr 

gWorl dsNotSameDepthAndSi  zeErr 
HandleDataHandlerSubType 
Handl erAID 

handl erCanCl i p  function 

handl erCanMatte  function 

handl erCanTransferMode  function 

handl erCGraf PortOnly  function 

handl erHasSpati al  function 

handl erNeedsBuffer  function 

handl erNoIdl e  function 

handl erNoSchedul er  function 

handlerWantsTime  function 

hasMovieExportUserlnterface 
hasMovi elmportMIMELi st 
hasMovielmportUserlnterface 
' hdl r ' 
hi  1 i te 
hi  1 i te , 

hi  1 i tetransfermode 
'hint' 

'hint' 

hi  ntsAl  1  owBl  ackl  i  ni  ng 
hintsAl 1 owlnterl ace 
hi ntsDontPurge 
hi ntsHi ghQual i ty 
hi nts Inacti ve 
hi ntsScrubMode 
hintsUseSoundlnterp 
'  h  1  i  t ' 

' hnti ' 

' hots ' 

'  h  s  i  n  ' 

'  hspa ' 

' htxt ' 

i cmFrameTimeHasVi rtual StartTimeAndDura 

' ICON' 

'  i  d  a  t ' 

i denti tyMatri xType 


f uncti  on  SGGrabPi ct  (  1 1 1 -1748) 

phi cs ImportDoesDrawAl  1  Pixel  s  (1-613) 
s 

phi cs ImportDoesDrawAl 1  Pixel  s  (1-613) 

phi cs ImportDoesDrawAl 1  Pixel  s  (1-613) 
atom  'wtxt'  (IV-2616) 
“Color  Constants”  (IV-2657) 
function  NewImageGWorl d  (11-1066) 
“Error  Codes”  (IV-2663) 
“Component  Identifiers”  (IV-2657) 
“Atom  ID  Codes”  (IV-2649) 
Medi a  Set Handl erCapabi 1 i ti es  (11-894) 
Medi a  Set Handl erCapabi 1 i ti es  (11-894) 
Medi a  Set Handl erCapabi 1 i ti es  (11-894) 
Medi a  Set Handl erCapabi 1 i ti es  (11-894) 
Medi a  Set Handl erCapabi 1 i ti es  (11-894) 
Medi a  Set Handl erCapabi 1 i ti es  (11-894) 
Medi a  Set Handl erCapabi 1 i ti es  (11-894) 
Medi a  Set Handl erCapabi 1 i ti es  (11-894) 
Medi a  Set Handl erCapabi 1 i ti es  (11-894) 
struct  ComponentDescri pti on  (IV-2212) 
struct  ComponentDescri pti on  (IV-2212) 
struct  ComponentDescri pti on  (IV-2212) 
atom  ' hdl r '  (IV-2540) 
“Graphics  Transfer  Modes”  (IV - 2670 ) 
atom  'wtxt'  (IV-2616) 
“Graphics  Transfer  Modes”  (IV-2670) 
atom  'hint'  (IV-2541) 
atom  'hint'  (IV-2542) 
f uncti on  SetMedi aPlayHints  (III-1601) 
function  SetMedi aPlayHints  (III-1601) 
function  SetMedi aPlayHints  (III-1601) 
function  SetMedi aPlayHints  (III-1601) 
f uncti on  SetMedi aPlayHints  (III- 160 1 ) 
f uncti on  SetMedi aPlayHints  (III-1601) 
f uncti on  SetMedi aPlayHints  (III- 160 1 ) 
atom  ' hi i t '  (IV-2543) 
atom  ' hnti '  ( I V - 2544 ) 
atom  'hots'  (IV- 2544 ) 
atom  'hsin'  (IV-2545) 
atom  'hspa'  (IV-2545) 
atom  'htxt'  (IV-2546) 

ti  on 

struct  ICMFrameTimeRecord  (IV-2281) 
struct  ResourceSpec  (IV-2402) 
atom  'idat'  (IV-2546) 
function  GetMatrixType  (1-419) 
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' i dsc ' 

atom 

' i dsc ' 

( I V - 2547 ) 

'  i  i  cc ' 

atom 

'  i i cc ' 

(IV-2547) 

i 1 1 egal Channel OSErr 

“Error 

Codes” 

(IV-2663) 

illegalControllerOSErr 

“Error 

Codes” 

( I V  -  2  6  6  3  ) 

illegal InstrumentOSErr 

“Error 

Codes” 

(IV-2663) 

i 1 1 egal KnobOSErr 

“Error 

Codes” 

(IV-2663) 

illegal KnobValueOSErr 

“Error 

Codes” 

(IV-2663) 

il legal NoteChannel OSErr 

“Error 

Codes” 

(IV-2663) 

i 1 1 egal PartOSErr 

“Error 

Codes” 

(IV-2663) 

illegalVoiceAllocationOSErr 

“Error 

Codes” 

(IV-2663) 

' i ma4 ' 

function  GetCompressi onlnfo  (1-398) 

' i mag ' 

atom 

'  imag ' 

(IV-2547) 

' i map ' 

atom 

'  imap ' 

( I V - 2548 ) 

'  i  mco ' 

atom 

' wtxt ' 

(IV-2616) 

'  i  met ' 

atom 

' i met ' 

(IV-2549) 

' i mda ' 

atom 

' imda ' 

(IV-2549) 

'  i  mdc ' 

atom 

'wtxt ' 

(IV-2616) 

'  i  mgp ' 

atom 

'imgp' 

( I V  -  2  5  5  0  ) 

' i mgr ' 

atom 

'  imgr ' 

(IV-2550) 

' i mpn ' 

atom 

'  impn ' 

( I V  -  2  5  5 1  ) 

' i mre ' 

atom 

'  imre ' 

(IV-2552) 

' i mrg ' 

atom 

'  imrg ' 

(IV-2552) 

' i mrt ' 

atom 

'  imrt ' 

( I V  -  2  5  5  3  ) 

'  i  n ' 

atom 

'  i  n ' 

(IV-2554) 

i ni tPanMask 

struct  SCStatus 

( I V - 2425 ) 

i ni tSRateMask 

struct  SCStatus 

( I V - 2425 ) 

i ni tStereoMask 

struct  SCStatus 

(IV-2425) 

InputMapAID 

“Atom  ID 

Codes” 

(IV-2649) 

i nRef Num 

function  SPBRecord 

( I 11-1878) 

i ntArabi c 

"Local i zati on 

Codes” 

(IV-2673) 

internal  Component  Err 

“Error 

Codes” 

(IV-2663) 

internalQuickTi me  Error 

“Error 

Codes” 

(IV-2663) 

i nterruptRouti ne 

function  SPBRecord 

( I 11-1878) 

i ntEuropean 

"Local i zati on 

Codes” 

(IV-2673) 

i nt Japanese 

"Local i zati on 

Codes” 

(IV-2673) 

i nt Roman 

"Local i zati on 

Codes” 

(IV-2673) 

i ntWestern 

"Local i zati on 

Codes” 

(IV-2673) 

i nval i dAtomContai nerErr 

“Error 

Codes” 

(IV-2663) 

i nval i dAtomErr 

“Error 

Codes” 

(IV-2663) 

i nval i dAtomTypeErr 

“Error 

Codes” 

(IV-2663) 

i nval i dChunkCache 

“Error 

Codes” 

(IV-2663) 

i nval i dChunkNum 

“Error 

Codes” 

(IV-2663) 

i nval i dDataRef 

“Error 

Codes” 

(IV-2663) 

i nval i dData Ref Con tai ner 

“Error 

Codes” 

(IV-2663) 

i nval i dDurati on 

“Error 

Codes” 

(IV-2663) 

i nval i d  Edi tState 

“Error 

Codes” 

(IV-2663) 

i nval i dHandl er 

“Error 

Codes” 

(IV-2663) 

invalidHotSpotIDErr 

“Error 

Codes” 

(IV-2663) 

i nval idlmagelndex Err 

“Error 

Codes” 

(IV-2663) 
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i  nval i dMedi a 
i  nval i dMovi e 
l  nval  i dNodeFormatErr 
inval  idNodelDErr 
i nval i dRect 

invalidSampleDescIndex 
i nval i dSampl eDescri pti on 
i nval i dSampl eNum 
i nval i dSampl eTabl e 
1 nval i dSpri telDErr 
inval i dSpri tel ndexErr 
i nval i dSpri tePropertyErr 
i nval i dSpri teWorl d Property Err 
i nval i dT i me 
i nval i dT  rack 
1 nval i dVi ewStateErr 
'jpeg' 

kl6BE565Pixel Format 
kl6Bi tBi gEndi an  Format 
k 1 6  B i tin 

k 1 6  B i t  LI ttl eEndi an  Format 
k 1 6  B i tOut 
kl6GrayCodecType 
kl6LE5551Pixel Format 
kl6LE555Pixel Format 
kl6LE565Pixel Format 
k24BGRPi xel Format 
k  2  4  B i tFormat 
k32ABGRPixel Format 
k32Al phaGrayCodecType 
k32ARGBPixel Format 
k32BGRAPixel Format 
k32Bi tFormat 
k32RGBAPixel Format 
k48RGBCodecType 
k64ARGBCodecType 
k8Bi tOffsetBi naryFormat 
k8B1 tRawIn 
k8  B i tRawOut 
k8BitTwosIn 
k8Bi tTwosOut 
kAccessKeySystemFl ag 
kActi on 
kActi onFl ags 
kActi onLi stAtomType 
kActi onParameter 
kActi onParameterMaxVal ue 
kActi onParameterMi nVal ue 
kActi onTarget 


“Error  Codes”  (IV-2663) 
“Error  Codes"  (IV-2663) 
“Error  Codes"  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Error  Codes"  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Error  Codes"  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Error  Codes"  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Error  Codes"  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Error  Codes"  (IV-2663) 
“Error  Codes”  (IV-2663) 
function  SGGetVi deoCompressorType  ( 1 1 1  - 1 7  44 ) 
function  QTVRGetBackBuf ferSetti ngs  (11-1350) 
“Sound  Formats”  (IV-2692) 
“Sound  Device  Features"  (IV-2692) 
“Sound  Formats”  (IV-2692) 
“Sound  Device  Features"  (IV-2692) 
“Codec  Identifiers”  (IV-2655) 
“Pixel  Formats”  (IV- 2686 ) 
function  QTVRGetBackBuf ferSetti ngs  (11-1350) 
function  QTVRGetBackBuf ferSetti ngs  (11-1350) 
function  QTVRGetBackBuf ferSetti ngs  (11-1350) 
“Sound  Formats”  (IV-2692) 
function  QTVRGetBackBuf ferSetti ngs  (11-1350) 
“Codec  Identifiers”  (IV-2655) 
function  QTVRGetBackBuf ferSetti ngs  (11-1350) 
function  QTVRGetBackBuf ferSetti ngs  (11-1350) 
“Sound  Formats”  (IV-2692) 
function  QTVRGetBackBuf ferSetti ngs  (11-1350) 
“Codec  Identifiers”  (IV-2655) 
“Codec  Identifiers”  (IV-2655) 
“Sound  Formats”  (IV-2692) 
“Sound  Device  Features”  (IV-2692) 
“Sound  Device  Features”  (IV-2692) 
“Sound  Device  Features”  (IV-2692) 
“Sound  Device  Features"  (IV-2692) 
function  QTRegi sterAccessKey  (11-1214) 
“Atom  ID  Codes"  (IV-2649) 
“Atom  ID  Codes"  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes"  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
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kALawCompressi on 

kAl phaComposi torTransitionType 

kAl phaGa in  Image Fi 1 terType 

kAni mati onCodecType 

kAudi o End i an At omType 

kAudi o Format At omType 

kAudi oTermi natorAtomType 

kAudi oVBRAtomType 

kAVRJPEGCodecType 

kBaseCodecType 

kBlurlmageFil terType 

kBMPCodecType 

kBrightnessContrastlmageFil terType 

kCDXA2Compressi on 

kCDXA4Compressi on 

kChromaKeyT  ransitionType 

kCi nepakCodecType 

kCl oudCodecType 

kCMYKCodecType 

kColorSyncImageFil terType 

kCol orTi nt Image Fi 1 terType 

kComment At omType 

kComponentCanDoSel ect 

kComponentCl oseSelect 

kComponentExecuteWi redActi onSel ect 

kComponentGetMPWorkFuncti onSel ect 

kComponentGetPubl icResourceSelect 

kComponentOpenSel ect 

kComponentRegi sterSelect 

kComponentTargetSel ect 

kComponentUnregi sterSelect 

kComponentVersi onSel ect 

kComponentVi deoCodecType 

kComponentVi deoSigned 

kComponentVi deoUnsigned 

kCondi ti on a  1  At omType 

kConnecti onActi ve 

kConnectionUseSystemPref 

kControl 1 erAfterTouch 

kControl 1 erBal ance 

kControl 1 erBreath 

kControl 1 erCel este 

kControl 1 erChorus 

kControl lerEditPart 

kControl 1 er Exp  res si  on 

kControl 1 erFoot 

kControl 1 erLeverl 

kControl 1 erl_ever2 

kControl 1 erLever3 


“Sound  Formats” 
“Effects  Codes” 
“Effects  Codes” 
“Codec  Identifiers” 
“Atom  ID  Codes” 
“Atom  ID  Codes” 
“Atom  ID  Codes” 
“Atom  ID  Codes” 
“Codec  Identifiers” 
“Codec  Identifiers” 
“Effects  Codes” 
“Codec  Identifiers” 
“Effects  Codes” 
“Sound  Formats” 
“Sound  Formats” 
“Effects  Codes” 
“Codec  Identifiers” 
“Codec  Identifiers” 
“Codec  Identifiers” 
“Effects  Codes” 
“Effects  Codes” 
“Atom  ID  Codes” 
struct  ComponentParameters 
struct  ComponentParameters 
struct  ComponentParameters 
struct  ComponentParameters 
struct  ComponentParameters 
struct  ComponentParameters 
struct  ComponentParameters 
struct  ComponentParameters 
struct  ComponentParameters 
struct  ComponentParameters 
“Codec  Identifiers” 
atom  'wtxt' 
atom  'wtxt' 
“Atom  ID  Codes” 
struct  QTSTransportPref 
struct  QTSTransportPref 
atom  'wtxt' 
atom  'wtxt' 
atom  'wtxt' 
atom  'wtxt' 
atom  'wtxt' 
atom  'wtxt' 
atom  'wtxt' 
atom  'wtxt' 
atom  'wtxt' 
“Music  Controllers” 
“Music  Controllers” 


(IV-2692) 

(IV-2662) 

(IV-2662) 

(IV-2655) 

(IV-2649) 

(IV-2649) 

(IV-2649) 

(IV-2649) 

(IV-2655) 

(IV-2655) 

(IV-2662) 

(IV-2655) 

(IV-2662) 

(IV-2692) 

(IV-2692) 

(IV-2662) 

(IV-2655) 

(IV-2655) 

(IV-2655) 

(IV-2662) 

(IV-2662) 

(IV-2649) 

(IV-2216) 

(IV-2216) 

(IV-2216) 

(IV-2216) 

(IV-2216) 

(IV-2216) 

(IV-2216) 

(IV-2216) 

(IV-2216) 

(IV-2216) 

(IV-2655) 

(IV-2616) 

(IV-2616) 

(IV-2649) 

(IV-2388) 

(IV-2388) 

(IV-2616) 

(IV-2616) 

(IV-2616) 

(IV-2616) 

(IV-2616) 

(IV-2616) 

(IV-2616) 

(IV-2616) 

(IV-2616) 

(IV-2682) 

(IV-2682) 
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kControl 1 erLever4 
kControl 1 erl_ever5 
kControl 1 erl_ever6 
kControl 1 erLever7 
kControl 1 erl_ever8 
kControl lerMasterTune 
kControl 1 erModul ati onWheel 
kControl 1 erPan 
kControl 1 erPhaser 
kControl lerPitchBend 
kControl 1 e r Port amen toTi me 
kControl 1 erReverb 
kControl lerSoft Pedal 
kControl lerSostenuto 
kControl 1 erSustai n 
kControl 1 erT remol  o 
kControl 1 erVol ume 
kConvol velmageFi 1 terType 
kCreateSound Source 
kCrossFadeTransitionType 
kCustomActi onHandl  er 
kCustomHandl erDesc 
kCustomHandl erlD 
kDataHCanRead 
kDataHCanStreami ngWri te 
kDataHCanWri te 
kDataHChokeToMovi eDataRate 
kDataHChokeToParam 
kDataHExtendedSchedul e 
kDataHMustCheckDataRef 
kDataHSpeci al Read 
kDataHSpeci al ReadFi 1 e 
kDataHSpeci al Wri te 
kDataRatel44ModemRate 
kDataRate288ModemRate 
kDataRateDual ISDNRate 
kData Rate  Inf ini teRate 
kDataRatelSDNRate 
kDataRateTIRate 
kDataReflsSelfContained 
kDDSurf aceLocked 
kDDSurf aceStati c 
kDi rectoryPathOnly 
kDi sabl eWhenEqual 
kDi sabl eWhenGreaterThan 
kDi sabl eWhenLessThan 
kDi sabl eWhenNot Equal 
kDontPassSel ector 


“Music  Controllers”  (IV- 2682 ) 
“Music  Controllers”  (IV- 2682 ) 
“Music  Controllers”  (IV- 2682 ) 
“Music  Controllers”  (IV- 2682 ) 
“Music  Controllers”  (IV- 2682 ) 
atom  'wtxt'  (IV-2616) 
atom  'wtxt'  (IV-2616) 
atom  'wtxt'  (IV-2616) 
atom  'wtxt'  (IV-2616) 
atom  'wtxt'  (IV-2616) 
atom  'wtxt'  (IV-2616) 
atom  'wtxt'  (IV-2616) 
atom  'wtxt'  (IV-2616) 
atom  'wtxt'  (IV-2616) 
atom  'wtxt'  (IV-2616) 
atom  'wtxt'  (IV-2616) 
atom  'wtxt'  (IV-2616) 
“Effects  Codes”  (IV-2662) 
“Sound  Device  Features”  (IV-2692) 
“Effects  Codes”  (IV-2662) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes"  (IV-2649) 
“Atom  ID  Codes"  (IV-2649) 
function  DataHCanUseDataRef  (1-175) 
function  DataHCanUseDataRef  (1-175) 
function  DataHCanUseDataRef  (1-175) 
struct  DataHChokeAtomRecord  (IV-2228) 
struct  DataHChokeAtomRecord  (IV-2228) 
struct  DataHSchedul eRecord  (IV-2229) 
struct  DataHVol umeLi stRecord  (IV-2230) 
function  DataHCanUseDataRef  (1-175) 
function  DataHCanUseDataRef  (1-175) 
function  DataHCanUseDataRef  (1-175) 
struct  QTA1 tDataRateRecord  (IV- 2347 ) 
struct  QTA1 tDataRateRecord  (IV- 2347 ) 
struct  QTA1 tDataRateRecord  (IV- 2347 ) 
struct  QTA1 tDataRateRecord  (IV- 2347 ) 
struct  QTA1 tDataRateRecord  (IV- 2347 ) 
struct  QTA1 tDataRateRecord  (IV- 2347 ) 
struct  ReferenceMovieDataRef Record  (IV- 2400 ) 
function  QTSetDDPrimarySurface  (11-1226) 
function  QTSetDDPrimarySurface  (11-1226) 
function  FSSpecToNati vePathName  (1-379) 
struct  ParameterDataBehavi or  (IV- 2328 ) 
struct  ParameterDataBehavi or  (IV- 2328 ) 
struct  ParameterDataBehavi or  (IV- 2328 ) 
struct  ParameterDataBehavi or  (IV- 2328 ) 
struct  Routi neRecord  (IV-2405) 


kDontUseVal i dateToFi ndGraphi cs Importer 
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function  GetGraphicsImporterForDataRefWithFlags 


kDVAudi oFormat 

kDVCNTSCCodecType 

kDVCPALCodecType 

kDVCProNTSCCodecType 

kDVCProPALCodecType 

kDVIIntel IMAFormat 

kEdgeDetectlmageFilterType 

keepInRam 

keepLocal 

kEffectGeneri cType 
kEffectManufacturerAtom 
kEffectNameAtom 
kEffectRawSource 
kEffectTypeAtom 
kEmbossImageFi 1 terType 
kExpl odeTransitionType 
kExpressi onContai nerAtomType 
kExtendedSoundBufferSi zeVal i d 


“Sound  Formats” 
“Codec  Identifiers” 
“Codec  Identifiers” 
“Codec  Identifiers” 
“Codec  Identifiers” 
“Sound  Formats” 
“Effects  Codes” 
function  LoadMedi alntoRam 
function  NewImageGWorl d 
struct  EffectSource 
“Atom  ID  Codes” 
“Atom  ID  Codes” 
struct  EffectSource 
“Atom  ID  Codes” 
“Effects  Codes” 
“Effects  Codes” 
“Atom  ID  Codes” 


st 

kExtendedSoundSampl eCountNotVali 

st 

keyCodeMask 

keyDown 

keyllp 

k  Fi  1  eNameOnly 
kFilmNoiselmageFil terType 
k  Fi reCodecType 
kFLCCodecType 
k  FI oat32Format 
k  FI oat64Format 
kFragment Needs Prepari ng 
kFul 1 Nati vePath 
kFul 1 Vol ume 

kGeneral EventAtomi clnstrument 
kGeneral EventKnob 
kGeneral EventMIDIChannel 
kGeneral EventNoOp 
kGeneral EventNoteRequest 
kGeneral EventPartChange 
kGeneral EventPartKey 
kGeneral EventPartMix 
kGeneral EventTuneDi fference 
kGeneral EventUsedNotes 
kGeneri cMusicBankO. . . kGeneri  cMus 

kGeneri cMusi cCal 1  Instrument 
kGeneri cMusi cCall Knobs 
kGeneri cMusi cCal 1  Number 


ruct  ExtendedSchedul edSoundHeader 
d 

ruct  ExtendedSchedul edSoundHeader 
struct  EventRecord 
struct  EventRecord 
struct  EventRecord 
function  FSSpecToNati vePathName 
“Effects  Codes” 
“Codec  Identifiers” 
“Codec  Identifiers” 
“Sound  Formats” 
“Sound  Formats” 
struct  Routi neRecord 
function  FSSpecToNati vePathName 
function  GetTrackVol ume 
atom  'wtxt' 
atom  'wtxt' 
atom  'wtxt' 
atom  'wtxt' 
atom  'wtxt' 
atom  'wtxt' 


i cBank32 
f uncti 
f uncti 
f uncti 
f uncti 


“QTMA  Events” 
atom  'wtxt' 
atom  'wtxt' 
atom  'wtxt' 

on  Musi cGeneri cConf i gure 
on  Musi cGeneri cConf i gure 
on  Musi cGeneri cConf i gure 
on  Musi cGeneri cConf i gure 


(1-413) 

(IV-2692) 

(IV-2655) 

(IV-2655) 

(IV-2655) 

(IV-2655) 

(IV-2692) 

(IV-2662) 

(11-779) 

(11-1066) 

(IV-2243) 

(IV-2649) 

(IV-2649) 

(IV-2243) 

(IV-2649) 

(IV-2662) 

(IV-2662) 

(IV-2649) 

( I V  -  2  2  5 1  ) 

( I V  -  2  2  5 1  ) 
(IV-2246) 
(IV-2246) 
(IV-2246) 
(1-379) 
(IV-2662) 
(IV-2655) 
(IV-2655) 
(IV-2692) 
(IV-2692) 
(IV-2405) 
(1-379) 
(1-547) 
(IV-2616) 
( IV-2616) 
(IV-2616) 
(IV-2616) 
(IV-2616) 
(IV-2616) 
(IV-2686) 
(IV-2616) 
(IV-2616) 
(IV-2616) 

(11-982) 

(11-982) 

(11-982) 

(11-982) 
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kGeneri cMusi cCal 1  Parts 
kGenerl cMusi cCal 1 ROMInstrument 
kGeneri cMusi cDoMIDI 
kGeneri cMusi cDrumKnob 
kGeneri cMusi cErsatzMIDI 
kGeneri cMusi clnstrumentKnob 
kGeneri cMusi cKnob 
kGetAtomi clnstAl 1  Knobs 
kGetAtomi clnstNoExpandedSampl es 
kGetAtomi c I  ns tNo Instrument  Info 
kGetAtomi clnstNoKnobLi st 
kGetAtomi clnstNoOri gi nal Sampl  es 
kGetAtomi clnstNoSampl  es 
kGetAtomi clnstOri gi nal KnobLi st 
kGetlnstrumentlnfoMi diUserlnst 
kGetlnstrumentlnfoNoBui 1  tin 
kGet Instrument  Inf oNoIText 


function  Musi cGeneri cConf i gure  (II- 
function  Musi cGeneri cConf i gure  (II- 
function  Musi cGeneri cConf i gure  (II- 
function  Musi cDeri vedSetKnob  (II- 
function  Musi cGeneri cConf i gure  (II- 
function  Musi cDeri vedSetKnob  (II- 
function  Musi cDeri vedSetKnob  (II- 


f uncti 
f uncti 
f uncti 
f uncti 
f uncti 
f uncti 
f uncti 
f uncti 
f uncti 


on  InstrumentGetlnst  (li¬ 
on  InstrumentGetlnst  (li¬ 
on  InstrumentGetlnst  (li¬ 
on  InstrumentGetlnst  (li¬ 
on  InstrumentGetlnst  (li¬ 
on  InstrumentGetlnst  (li¬ 
on  InstrumentGetlnst  (li¬ 
on  InstrumentGetlnfo  (li¬ 
on  InstrumentGetlnfo  (II- 


function  InstrumentGetlnfo  (II- 


kGetMovi elmporterDontConsi derGraphi cs Importers 

function  GetMovielmporterForDataRef  (I- 
kGI FCodecType  “Codec  Identifiers”  (IV- 

kGMSynthComponentSubType  function  InstrumentGetSynthesizerType  (II- 
kGradi entTransi ti onType  “Effects  Codes”  (IV- 

kGraphi csCodecType  “Codec  Identifiers”  (IV- 

kGraphi csExportDescription  “Atom  ID  Codes”  (IV- 

kGraphi csExportExtensi on  “Atom  ID  Codes”  (IV- 

kGraphi csExportFi 1 eType  “Atom  ID  Codes”  (IV- 

kGraphi csExportGroup  “Atom  ID  Codes”  (IV- 

kGraphi csExportMIMEType  “Atom  ID  Codes”  (IV- 

kGraphi cs FI agsGray  struct  ParameterDataBehavi or  (IV- 

kGraphi cs Importer Don tDoGamma Cor recti  on 

function  Graphi cs ImportGetFl ags  (I- 


kGroupAI i gnText 
kGroupMatri x 
kGroupNoName 
kGroupSurroundBox 
kH261CodecType 
kH263CodecType 
kHi ghLevel Event 
kHi ghQual i ty 

kHSLColorBalancelmageFilterType 
kICMPixel Formatlslndexed 
k I  CM Pixel  Format  Is  PI anarMask 
kICMPixel FormatlsSupportedByQD 
kIMACompressi on 
klmpl odeTransi ti onType 
kIndeo4CodecType 

klni ti al i zeQTMLDi sabl eDi rectSound 
klni ti al i zeQTMLNoSoundFl ag 


struct  ParameterDataBehavior  (IV- 
struct  ParameterDataBehavior  (IV- 
struct  ParameterDataBehavior  (IV- 
struct  ParameterDataBehavior  (IV- 
“Codec  Identifiers”  (IV- 
“Codec  Identifiers”  (IV- 
struct  EventRecord  (IV- 
“Sound  Device  Features”  (IV- 
“Effects  Codes"  (IV- 
struct  ICMPixel Formatlnfo  (IV- 
struct  ICMPixel Formatlnfo  (IV- 
struct  ICMPixel Formatlnfo  (IV- 
“Sound  Formats”  (IV- 
“Effects  Codes"  (IV- 
“Codec  Identifiers”  (IV- 
f uncti on  Ini ti al i zeQTML  (II- 
f uncti on  Ini ti al i zeQTML  (II- 


klni ti al i zeQTMLUseExcl usi veFul 1 ScreenModeFl ag 
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k I n 1 1 1  a  1 i zeQTMLUseGDI FI ag 

klnitial Rotation Atom 

klnputMapSublnputlD 

klnstKnobMissing Default 

klnstKnobMissi  nglln  known 

klnstrumentExactMatch 

kl ns t rumen tMatchGMNumber 

klnstrumentMatchName 

kl ns trumentMatch Number 

klnstrumentMatchSynthesi zerName 

klnstrumentMatchSynthesi zerType 

kl ns t rumen tQual 1 ty  Field 

klnstrumentRecommendedSubsti tute 

klnstrumentRol and8BitQuality 

klrisTransitionType 

kITextAtomType 

kITextStri ngAtomType 

kJPEGCodecType 

kKnobFi xedPoi ntl6 

kKnobFi xedPoi nt8 

kKnobGroupStart 

kKnoblnterruptllnsafe 

kKnobKey rangeOverri de 

kKnobReadOnly 

kKnobTypeBool ean 

kKnobTypeButton 

kKnobTypeGroupName 

kKnobTypehlertz 

kKnobType Instrument 

kKnobTypeMilliseconds 

kKnobTypeNote 

kKnobTypeNumber 

kKnobTypePan 

kKnobTypePercentage 

kKnobTypeSetti ng 

kkQTVRDownLeft 

kLensFlarelmageFilterType 

kLi st El ementDataType 

k  L i stEl ementType 

kLittleEndi  an  Format 

kM68kISA 

kMACE3Compressi on 
kMACE6Compressi on 
kMacPai ntCodecType 
kMarkerEventBeat 
kMarkerEventEnd 
kMarkerEventTempo 
' kmat ' 


function  Ini  ti  al  i zeQTML 
function  Ini ti al i zeQTML 
“Atom  ID  Codes” 
“Atom  ID  Codes” 
struct  InstKnobList 
struct  InstKnobList 
struct  GMInstrumentlnfo 
function  MusicFi ndTone 
function  MusicFi ndTone 
function  MusicFi ndTone 
function  Musi cFi ndTone 
function  MusicFi ndTone 
struct  GMInstrumentlnfo 
struct  GMInstrumentlnfo 
struct  GMInstrumentlnfo 
“Effects  Codes” 
“Atom  ID  Codes” 
“Atom  ID  Codes” 
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dec  Identifiers” 

struct 

KnobDescri pti 

on 

struct 

KnobDescri pti 

on 
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KnobDescri pti 

on 
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KnobDescri pti 

on 
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on 
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on 
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struct 

KnobDescri pti 
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struct 
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on 
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on 
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on 
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on 
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on 

struct 

KnobDescri pti 

on 

struct 

KnobDescri pti 

on 

struct 

KnobDescri pti 

on 

struct 

KnobDescri pti 

on 

function  QTVRInteracti onNudge 
“Effects  Codes” 
“Atom  ID  Codes” 
“Atom  ID  Codes” 
“Sound  Formats” 
struct  Routi neRecord 
“Sound  Formats” 
“Sound  Formats” 
“Codec  Identifiers” 
atom  'wtxt' 
atom  'wtxt' 
atom  'wtxt' 
atom  'kmat' 
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(11-981) 
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(11-981) 

(11-981) 

(11-981) 

(IV-2272) 

(IV-2272) 

(IV-2272) 

(IV-2662) 

(IV-2649) 

(IV-2649) 

(IV-2655) 

(IV-2299) 

( I V  -  2  2  9  9  ) 

(IV-2299) 

(IV-2299) 

(IV-2299) 

(IV-2299) 
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(IV-2299) 
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(IV-2299) 

(IV-2299) 

(IV-2299) 

(IV-2299) 

(IV-2299) 

(IV-2299) 

(IV-2299) 

(IV-2299) 

(11-1389) 

(IV-2662) 

(IV-2649) 

(IV-2649) 

(IV-2692) 

(IV-2405) 

(IV-2692) 

(IV-2692) 

(IV-2655) 

(IV-2616) 

(IV-2616) 

(IV-2616) 
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kMatrixTransi ti onType 

kMedi aVideoParamBI ackLevel 

kMedi aVideoParamBri ghtness 

kMedi aVideoParamContrast 

kMedi aVideoParamHue 

kMedi aVideoParamSaturati on 

kMedi aVideoParamSharpness 

kMedi a Vi deoParamWhi te Level 

kMi  crosoftADPCMFormat 

kMi crosoftVi deolCodecType 

kMIDI Import 20  PI ayabl e 

kMIDI ImportSi 1 enceAfter 

kMIDI ImportSi 1 enceBefore 

kMIDI ImportWantLyri cs 

kMoti onJPEGACodecType 

kMoti onJPEGBCodecType 

kMovi  eAnchorDataRef IsDefaul t 

kMovi  eExportAbsol uteT i me 

kMovi eExportRel ati veT i me 

kMovi eExportTextOnly 

kMovi eLoadStateCompl ete 

kMovi eLoadStateError 

kMovi eLoadStateLoadi ng 

kMovi e Load St ate PI ayabl e 

kMovi eMedi aAl tText 

kMovi eMedi aAutoPl ay 

kMovi  eMedi aCl i pBegi n 

kMovi  eMedi aCl i pDurati on 

kMovi eMedi aDataReference 

kMovi eMedi aEnabl eFrameSteppi ng 

kMovi eMedi aHei ght 

kMovi eMedi aLeft 

kMovi eMedi aLoop 

kMovi eMedi aRectangl eAtom 

kMovi eMedi aRegi onAtom 

kMovi eMedi aSl aveAudi o 

kMovi eMedi aSlaveTrackDuration 

kMovi eMedi aSpati al Ad j  ustment 

kMovi eMedi aTi tl e 

kMovi eMedi aTop 

kMovi eMedi aUseMIMEType 

kMovi eMedi aWi dth 

kMovi ePropertyDurati on 

kMovi eProperty Natural  Bounds 

kMovi ePropertyTi meScal e 

kM P EG Layer3 Format 

kMpegYUV420CodecType 

kMusi cLoopTypeNormal 

kMusi cLoopTypePal i ndrome 


“Effects  Codes”  (IV-2662) 
function  Medi aGetVideoParam  (11-868) 
function  Medi aGetVideoParam  (11-868) 
function  Medi aGetVideoParam  (11-868) 
function  Medi aGetVideoParam  (11-868) 
function  Medi aGetVideoParam  (11-868) 
function  Medi aGetVideoParam  (11-868) 
function  Medi aGetVideoParam  (11-868) 
“Sound  Formats”  ( IV-2692) 
“Codec  Identifiers”  (IV-2655) 
function  MIDI ImportGetSetti ngs  (11-917) 
function  MIDI ImportGetSetti ngs  (11-917) 
function  MIDI ImportGetSetti ngs  (11-917) 
function  MIDI ImportGetSetti ngs  (11-917) 
“Codec  Identifiers”  (IV-2655) 
“Codec  Identifiers"  (IV-2655) 
function  GetMovieAnchorDataRef  (1-458) 
function  TextExportGetSetti ngs  (III- 1928 ) 
function  TextExportGetSetti ngs  (III- 1928 ) 
function  TextExportGetSetti ngs  (III- 1928 ) 
function  GetMovi eLoadState  (1-477) 
function  GetMovi eLoadState  (1-477) 
function  GetMovi eLoadState  (1-477) 
function  GetMovi eLoadState  (1-477) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes"  (IV-2649) 
“Atom  ID  Codes"  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes"  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes"  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes"  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes"  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes"  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes"  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
“Sound  Formats”  (IV-2692) 
“Codec  Identifiers”  (IV-2655) 
struct  InstSampl eDescRec  (IV-2296) 
struct  InstSampl eDescRec  (IV-2296) 
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kMusicPacketPortFound 

kMusicPacketPortLost 

kMusicPacketTimeGap 

kNameAtom 

kNonLinearTweenHeader 
kNonReal T i me 

kNoSoundComponentChai n  function  So 

kNoteRequestNoGM 

kNoteRequestNoSynthType 

kNoVol ume 

kOffsetBi nary 

kOnlyDrawToSpri teWorl d 

kOpenDMLJPEGCodecType 

kOperandAtomType 

kOperatorAtomType 

kParameterltemCheckBox 

kParameterltemCol or Pi cker 

kParameterltemControl 

kParameterltemDraglmage 

kParameterltem Edit Double 

kParameterltemEditFixed 

kParameterltem Edit  Long 

kParameterltemEdi tText 

kParameterltemGroupDi vi der 

kParameterltem Line 

kParameterltemPopUp 

kParameterltemRadioCluster 

kParameterltemStati cText 


struct  MusicMIDIPacket  (IV-2320) 
struct  MusicMIDIPacket  (IV-2320) 
struct  MusicMIDIPacket  (IV-2320) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
“Sound  Device  Features”  (IV-2692) 
dComponentPl ay Source Buffer  ( 1 1 1-1854) 
struct  NoteRequestlnfo  (IV-2323) 
struct  NoteRequestlnfo  (IV-2323) 
function  GetTrackVol ume  (1-547) 
“Sound  Formats”  (IV-2692) 
function  SpriteWorldldle  ( 1 1 1-1908) 


Codec  Identifiers” 

(IV-2655) 

“Atom  ID 

Codes” 

(IV-2649) 

“Atom  ID 

Codes” 

(IV-2649) 

atom 

'wtxt ' 

(IV-2616) 

atom 

'wtxt ' 

(IV-2616) 

atom 

'wtxt ' 

(IV-2616) 

atom 

'wtxt ' 

(IV-2616) 

atom 

'wtxt ' 

(IV-2616) 

atom 

'wtxt ' 

(IV-2616) 

atom 

'wtxt ' 

(IV-2616) 

atom 

'wtxt ' 

(IV-2616) 

atom 

'wtxt ' 

(IV-2616) 

atom 

'wtxt ' 

(IV-2616) 

atom 

'wtxt ' 

(IV-2616) 

atom 

'wtxt ' 

(IV-2616) 

atom 

'wtxt ' 

(IV-2616) 

kParameterValidationFinal Validation 


function  ImageCodecValidateParameters 

kParameterValidationNoFlags 

function  ImageCodecValidateParameters 


kPassThrough  function 

kPhotoCDCodecType 
kPi ckDontMi x 
kPi ckEdi tAl 1 owPi ck 
kPi ckSameSynth 
kPi ckUserlnsts 
kPlanarRGBCodecType 
kPNGCodecType 
kPopupStoreAsStri ng 
kPowerPCISA 

kProcDescriptorls Relative 
kPushTransitionType 
kQDesi gn Comp  res si  on 
kQTCol orSyncProfile 
kQTCPUSpeedlRati ng 
kQTCPUSpeed2Rati ng 
kQTCPUSpeed3Rati ng 


oundComponentPl ay Source Buffer 
“Codec  Identifiers” 
function  NAPi ckEdi tlnstrument 
function  NAPi ckEdi tlnstrument 
function  NAPi ckEdi tlnstrument 
function  NAPi ckEdi tlnstrument 
“Codec  Identifiers” 
“Codec  Identifiers” 
struct  ParameterDataBehavi or 
struct  Routi neRecord 
struct  Routi neRecord 
“Effects  Codes” 
“Sound  Formats” 
“Atom  ID  Codes” 
struct  QTA1 tCPURati ngRecord 
struct  QTA1 tCPURati ngRecord 
struct  QTA1 tCPURati ngRecord 


(11-745) 

(11-745) 

( 1 11-1854) 
(IV-2655) 
(11-1033) 
(11-1033) 
(11-1033) 
(11-1033) 
(IV-2655) 
(IV-2655) 
( I V - 2328 ) 
(IV-2405) 
(IV-2405) 
(IV-2662) 
(IV-2692) 
(IV-2649) 
(IV-2346) 
(IV-2346) 
(IV-2346) 
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kQTCPUSpeed4Rati  ng 
kQTCPU Speed 5  Rati ng 
kQTDont Recompress 
kQT Event  Record At omType 
kQTEventType 
kQTInterl aceStyl e 
kQTMLHandl ePort Events 
kQTMLNoIdl eEvents 


struct  QTA1 tCPURati ngRecord  (IV- 
struct  QTA1 tCPURati ngRecord  (IV- 
“Atom  ID  Codes”  (IV- 
“Atom  ID  Codes”  (IV- 
“Atom  ID  Codes"  (IV- 
“Atom  ID  Codes”  (IV- 
function  CreatePortAssoci ati on  (I- 
function  CreatePortAssoci ati on  (I- 


2346) 

2346) 

2649) 

2649) 

2649) 

2649) 

148) 

148) 


kQTParseTextHREFBaseURL 
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ID 

Codes” 

( I V  -  2  64  9 ) 

kQTParseTextHREFCl i ckPoi nt 
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ID 

Codes” 

( I V  -  2  64  9 ) 

kQTParseTextHREFDel i miter 
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ID 
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( I V  -  2 64 9 ) 

kQTParseTextHREFHREF 
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ID 

Codes” 

( I V  -  2  64  9 ) 

kQTParseTextHREFIsAutoHREF 

“Atom 

ID 

Codes” 

( I V  -  2 64 9 ) 

kQTParseTextHREFRecomposeHREF 

“Atom 

ID 
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kQTParseTextHREFTarget 

“Atom 

ID 

Codes” 

( I V  -  2 64 9 ) 

kQTParseTextHREFUseAl tDel im 

“Atom 

ID 

Codes" 

( I V  -  2  64  9 ) 

kQTPNGInterl aceAdam7  function 

Graphi  csExportGetlnterl aceStyl e 

:  (1-575) 

kQTPNGInterl aceNone  function 

Graphi  csExportGetlnterl aceStyl e 

:  (1-575) 

kQTResol uti onSetti ngs 

“Atom 

ID 

Codes” 

( I V  -  2 64 9 ) 

kQTSAnnotati onsChangedNoti f i cati on 

“Atom 

ID 

Codes” 

( I V  -  2  64  9 ) 

kQTSBandwi dthAl ertNoti f i cati on 

“Atom 

ID 

Codes" 

( I V  -  2 64 9 ) 

kQTSBufferTimeAID 

“Atom 

ID 

Codes” 

( I V  -  2  64  9 ) 

kQTSCl i pRectAID 

“Atom 

ID 

Codes” 

( I V  -  2 64 9 ) 

kQTSConnecti onAtomType 

“Atom 

ID 
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( I V  -  2  64  9 ) 

kQTSConnecti onMethodPref sType 
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ID 
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( I V  -  2 64 9 ) 

kQTSConnecti onPrefsType 

“Atom 

ID 
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( I V  -  2  64  9 ) 

kQTSConnecti onPrefsVersi on 
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ID 
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( I V  -  2 64 9 ) 

kQTSDi rectConnectPref sType 
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ID 
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( I V  -  2  64  9 ) 

kQTSDont Proxy Da t a Type 

“Atom 

ID 
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( I V  -  2 64 9 ) 

kQTSDont Proxy P ref s At omType 

“Atom 

ID 

Codes" 

( I V  -  2  64  9 ) 

kQTSDurati onAID 

“Atom 

ID 

Codes” 

( I V  -  2 64 9 ) 

kQTSDurati onlnfo 

“Atom 

ID 

Codes” 

( I V  -  2  64  9 ) 

kQTSErrorNoti f i cati on 

“Atom 

ID 

Codes" 

( I V  -  2 64 9 ) 

kQTSHTTPProxyP ref sType 

“Atom 

ID 

Codes” 

( I V  -  2  64  9 ) 

kQTSHTTPT  ransportType 

“Atom 

ID 

Codes" 

( I V  -  2 64 9 ) 

kQTSLost Percent  Info 

“Atom 

ID 
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( I V  -  2  64  9 ) 

kQTSMedi aDescri pti onTextAID 

“Atom 

ID 

Codes” 

( I V  -  2 64 9 ) 

kQTSMedi aStreamAID 

“Atom 

ID 

Codes” 

( I V  -  2  64  9 ) 

kQTSMedi aStreamHeaderAID 

“Atom 

ID 

Codes” 

( I V  -  2 64 9 ) 

kQTSMedi aTypelnfo 

“Atom 

ID 

Codes" 

( I V  -  2  64  9 ) 

kQTSNamelnfo 

“Atom 

ID 

Codes” 

( I V  -  2 64 9 ) 

kQTSNewPresentati onNoti f i cati on 

“Atom 

ID 

Codes” 

( I V  -  2  64  9 ) 

kQTSNormal St a t us Di men si ons Inf o 

“Atom 

ID 

Codes” 

( I V  -  2 64 9 ) 

kQTSPrerol 1 AckNoti f i cati on 

“Atom 

ID 

Codes” 

( I V  -  2  64  9 ) 

kQTSPresDoneChangi ngNoti f i cati on 

“Atom 

ID 

Codes" 

( I V  -  2 64 9 ) 

kQTSPresentati onAID 

“Atom 

ID 

Codes” 

( I V  -  2  64  9 ) 

kQTSPresentati onChangedNoti f i cati on 

“Atom 

ID 

Codes” 

( I V  -  2 64 9 ) 

kQTSPresentati onGoneNoti f i cati on 

“Atom 

ID 

Codes” 

( I V  -  2  64  9 ) 

kQTSPresentati onHeaderAID 

“Atom 

ID 
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kQTSProxyPrefsAtomType 
kQTSRTSPProxyPrefsType 
kQTSServerNameNoti f i cati  on 
kQTSSOCKSPrefsType 
kQTSSOCKSProxyPrefsType 
kQTSSourceBoundi ngRectlnfo 
kQTSSourceCl i pRectlnfo 
kQTSSourceDi mens i ons Info 
kQTSSourceGraphi csModelnfo 
kQTSSource I nputMapInfo 
kQTSSource Language  Info 
kQTSSourceLayerlnfo 
kQTSSourceMatri xlnfo 
kQTSSourceScal elnfo 
kQTSSourceT  rackFlagsInfo 
kQTSSourceT  rackIDInfo 
kQTSSourceUserDatalnfo 
kQTSSource Vo 1 umeslnfo 


"Atom  ID  Codes’ 
"Atom  ID  Codes’ 
ID  Codes’ 
ID  Codes’ 
ID  Codes’ 


"Atom 

"Atom 

"Atom 


function  RTPMPSetlnfo 
function  RTPMPSetlnfo 
function  RTPMPSetlnfo 
function  RTPMPSetlnfo 
function  RTPMPSetlnfo 
function  RTPMPSetlnfo 
function  RTPMPSetlnfo 
function  RTPMPSetlnfo 
function  RTPMPSetlnfo 
function  RTPMPSetlnfo 
function  RTPMPSetlnfo 
function  RTPMPSetlnfo 
function  RTPMPSetlnfo 


(IV-2649) 
(IV-2649) 
(IV-2649) 
(IV-2649) 
(IV-2649) 
( 1 11-1475) 
( 1 11-1475) 
( 1 11-1475) 
( 1 11-1475 ) 
( 1 11-1475) 
( 1 11-1475) 
( 1 11-1475) 
( 1 11-1475) 
( 1 11-1475) 
( 1 11-1475) 
( 1 11-1475) 
( 1 11-1475) 
( 1 11-1475) 


kQTSStartAckNoti fi cati on 
kQTSStatHel perReturnPascalStringsFlag 

"Atom 

ID 

Codes” 

(IV-2649) 

struct 

QTSStatHel per Next Pa  rams 

( I V - 2382 ) 

kQTSStati sties  Info 

“Atom 

ID 

Codes” 

(IV-2649) 

kQTSStati sti cs Name At omType 

“Atom 

ID 

Codes” 

(IV-2649) 

kQTSStati sti csStreamAtomType 

"Atom 

ID 

Codes” 

(IV-2649) 

kQTSStati  sti  csllni  ts  At  omType 

"Atom 

ID 

Codes” 

(IV-2649) 

kQTSStati  sti  csllni  tsNameAtomType 

"Atom 

ID 

Codes” 

(IV-2649) 

kQTSStatusNoti fi cati on 

“Atom 

ID 

Codes” 

(IV-2649) 

kQTSStreamBegi nChangingNotification 

“Atom 

ID 

Codes” 

(IV-2649) 

kQTSStreamDoneChangi ngNotification 

“Atom 

ID 

Codes” 

(IV-2649) 

kQTSStreamMedi aType 

“Atom 

ID 

Codes” 

(IV-2649) 

kQTSTargetBufferDurati on  Info 

“Atom 

ID 

Codes” 

(IV-2649) 

kQTSTCPT  ransportType 

“Atom 

ID 

Codes” 

(IV-2649) 

kQTSTotal Data  Rate  Info 

“Atom 

ID 

Codes” 

(IV-2649) 

kQTSTotal DataRatelnlnfo 

“Atom 

ID 

Codes” 

(IV-2649) 

kQTSTotal DataRateOutlnfo 

“Atom 

ID 

Codes” 

(IV-2649) 

kQTST  ransAndProxyAtomType 

“Atom 

ID 

Codes” 

(IV-2649) 

kQTST  ransportPrefsAtomType 

“Atom 

ID 

Codes” 

(IV-2649) 

kQTSUDPT  ransportType 

“Atom 

ID 

Codes” 

(IV-2649) 

kQTTargetDataSi ze 
kQTTI FFCompressi on_None 

“Atom 

ID 

Codes” 

(IV-2649) 

function  Graphi csExportSetCompressi onMethod  (1-589) 
kQTTI FFCompressi on_PackBi ts 

function  Graphi csExportSetCompressi onMethod  ( 1-589 ) 
function  QTVREnabl eHotSpot  (11-1340) 
function  QTVRBegi nllpdateStream  (11-1335) 
“Atom  ID  Codes”  (IV-2649) 
struct  QTVRAreaOf Interest  (IV-2392) 
struct  QTVRAreaOf Interest  (IV-2392) 
struct  QTVRAreaOf Interest  (IV-2392) 


kQTVRAll HotSpots 
kQTVRAll Modes 
kQTVRAngl e Range At omType 
kQTVRBackBufferAl ways  Refresh 
kQTVRBackBuf fer Every Idl e 
kQTVRBackBufferEveryUpdate 
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kQTVRCantPanDown 
kQTVRCantPanLeft 
kQTVRCantPanRi  ght 
kQTVRCantPanllp 
kQTVRCantT  ransl ateDown 
kQTVRCantT ransl  ate Left 
kQTVRCantT  ransl ateRi ght 
kQTVRCantT  ranslatellp 
kQTVRCantZoomln 
kQTVRCantZoomOut 
kQTVRCanZoom 

kQTVRCol orCursorAtomType 

kQTVRCol orCursorType 

kQTVRCurrent 

kQTVRCurrentMode 

kQTVRCurrentNode 

kQTVRCursorAtomType 

kQTVRCursorParentAtomType 

kQTVRDef aul t 

kQTVRDef aul tNode 

kQTVRDef aul tRes 

kQTVRDegrees 

kQTVRDontLoopVi ewFrames 

kQTVRDown 

kQTVRDownRi  ght 

kQTVRFi  el  dOfVi  ew 

kQTVRFOVConstrai ntAtomType 

kQTVRFul 1  Cache 

kQTVRFul 1  Correct!  on 

kQTVRFul 1  Res 

kQTVRGetHotSpotTypeSel ector 
kQTV  RH  a  1  f Res 
kQTVRHotSpotAtomType 
kQTVRHotSpotID 
kQTV  RFIotSpot  Inf  oAtomType 
kQTV RHot Spot Pa  rent At omType 
kQTVRHotSpotT  rackRef At omType 
kQTVRHotSpotType 
kQTVRImageT  rackRef At omType 
kQTV R I magi ngCor recti  on 
kQTV R I magi ngCurrentMode 
kQTV R I magi ngDefaultValue 
kQTV R I magi ngDi rectDraw 
kQTV R I magi ng Pa  rent At omType 
kQTVRImagi ngQual i ty 


function  QTVRGetConstrai ntStatus 
function  QTVRGetConstrai  ntStatus 
f uncti on  QTVRGetConstrai  ntStatus 
function  QTVRGetConstrai ntStatus 
f uncti on  QTVRGetConstrai  ntStatus 
function  QTVRGetConstrai  ntStatus 
function  QTVRGetConstrai  ntStatus 
f uncti on  QTVRGetConstrai ntStatus 
function  QTVRGetConstrai  ntStatus 
function  QTVRGetConstrai  ntStatus 
function  QTVRGetControl Setti ng 
“Atom  ID  Codes” 
struct  QTVRCursorRecord 
function  QTVRGetVi ewState 
function  QTVRUpdate 
function  QTVRGoToNodelD 
“Atom  ID  Codes” 
“Atom  ID  Codes” 
function  QTVRGetVi ewState 
function  QTVRGoToNodelD 
functi on  QTVRGetAvai 1 abl eResol uti ons 
function  QTVRGetAngul arUni ts 
function  QTVRGetAni mati on Setti ng 
function  QTVRInteracti onNudge 
function  QTVRInteracti onNudge 
function  QTVRGetConstrai nts 
“Atom  ID  Codes" 
functi on  QTVRGetBackBufferMemlnfo 
functi on  QTVRGetlmagi ng Property 
functi on  QTVRGetAvai 1 abl eResol uti ons 
functi on  QTVRInstal 1 InterceptProc 
functi on  QTVRGetAvai 1 abl eResol uti ons 
“Atom  ID  Codes” 
function  QTVREnabl eHotSpot 
“Atom  ID  Codes” 
“Atom  ID  Codes" 
“Atom  ID  Codes” 
function  QTVREnabl eHotSpot 
“Atom  ID  Codes” 
functi on  QTVRGetlmagi ng Property 
functi on  QTVRGetlmagi ng Property 
functi on  QTVRGetlmagi ng Property 
functi on  QTVRGetlmagi ng Property 
“Atom  ID  Codes” 
functi on  QTVRGetlmagi ng Property 


kQTVRInteracti onMouseCl i ckHysteresi s 

functi on  QTVRGetlnteracti onProperty 
kQTVRInteracti onMouseCl i ckTimeout 

functi on  QTVRGetlnteracti onProperty 


(11-1353) 
(11-1353) 
(11-1353) 
(11-1353) 
(11-1353) 
(11-1353) 
(11-1353) 
(11-1353) 
(11-1353) 
(11-1353) 
(11-1355) 
( I V  -  2649 ) 
(IV-2395) 
(11-1382) 
(11-1445) 
(11-1386) 
( I V  -  2  64  9 ) 
( I V  -  2  64  9 ) 
(11-1382) 
(11-1386) 
(11-1346) 
(11-1344) 
(11-1344) 
(11-1389) 
(11-1389) 
(11-1352) 
( I V  -  2  64  9 ) 
(11-1347) 
(11-1365) 
(11-1346) 
(11-1387) 
(11-1346) 
( I V  -  2  64  9 ) 
(11-1340) 
( I V  -  2  64  9 ) 
( I V  -  2  64  9 ) 
( I V  -  2  64  9 ) 
(11-1340) 
( I V  -  2  64  9 ) 
(11-1365) 
(11-1365) 
(11-1365) 
(11-1365) 
( I V  -  2  64  9 ) 
(11-1365) 

(11-1368) 

(11-1368) 
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f uncti on 
f uncti on 
f uncti on 
f uncti on 
f uncti on 


kQTVRInteracti onMouseMotionScale 

f uncti on 

kQTVRInteracti onNudgeMode  function 
kQTVRInteracti onPanTiltSpeed  function 
kQTVRInteracti onTransl ateOnMouseDown 

f uncti on 

kQTVRInteracti onZoomSpeed 
kQTVRLeft 

kQTVRLi nklnfoAtomType 
kQTVRMi nimumCache 
kQTVRMoti on 
kQTVRMouseDown 
kQTVRMo use Down Sel ector 
kQTVRMouseEnterSel ector 
kQTVRMo use  Lea veSel ector 
kQTVRMo us eSti 1 1  Down Sel ector 
kQTVRMo  us  ellpSel  ector 
kQTVRMo us eWi thinSel ector 
kQTVRNoCor recti  on 
kQTVRNodeHeaderAtomType 
kQTVRNodelDAtomType 
kQTVRNodeLocati onAtomType 
kQTVRNodeParentAtomType 
kQTVRNudgeRotate 
kQTVRNudgeT  ransl ate 
kQTVRObjectHotSpotT  rackRef Atom ID 
kQTVRObjectlmageT  rackRef Atom ID 
kQTVRObjectlmagi ngAtomType 
kQTVRObjectlnfoAtomlD 
kQTVRObjectlnfoAtomType 
kQTVRPal i ndromeVi ew Frames 
kQTVRPal i ndromeVi ews 
kQTVRPan 

kQTVRPanConstrai ntAtomType 
kQTVRPanni ng 

kQTVRPanoImagi ngAtomType 
kQTVRPanoSampl eDataAtomType 
kQTVRParti al Correction 
kQTVRPl ay E ve ry V i ew Frame 
kQTVRPl ayStreamingVi ews 


QTVRGet Interacti onProperty 
QTVRGetlnteracti onProperty 
QTVRGetlnteracti onProperty 

QTVRGetlnteracti onProperty 
function  QTVRGetlnteracti onProperty 
function  QTVRInteracti onNudge 
“Atom  ID  Codes” 
function  QTVRGetBackBufferMemlnfo 
function  QTVRBegi nllpdateStream 
function  QTVRGetVi ewState 
function  QTVRInstal llnterceptProc 
QTVRInstal llnterceptProc 
QTVRInstal llnterceptProc 
QTVRInstal 1 InterceptProc 
QTVRInstal 1 InterceptProc 
QTVRInstall InterceptProc 
function  QTVRGetlmagi ngProperty 
“Atom  ID  Codes” 
“Atom  ID  Codes” 
“Atom  ID  Codes” 
“Atom  ID  Codes” 
function  QTVRGetlnteracti onProperty 
function  QTVRGetlnteracti onProperty 
“Atom  ID  Codes” 
“Atom  ID  Codes” 
“Atom  ID  Codes” 
“Atom  ID  Codes” 
“Atom  ID  Codes” 
functi on  QTVRGetAnimati onSetti ng 
function  QTVRGetAnimati onSetti ng 
function  QTVRGetConstrai nts 
“Atom  ID  Codes” 
function  QTVRGetCurrentMouseMode 
“Atom  ID  Codes” 
“Atom  ID  Codes” 
function  QTVRGetlmagi ngProperty 
function  QTVRGetAnimati onSetti ng 
function  QTVRGetAnimati onSetti ng 


kQTVRP reScreen Every  I dl e 

function  QTVRSetPrescreenlmagi ngCompl eteProc 
kQTVRPrevi ousNode  function  QTVRGoToNodelD 
kQTVRQuarterRes  function  QTVRGetAvai 1 abl eResol uti ons 
kQTVRRadians  function  QTVRGetAngul  arllni  ts 
kQTVRReverseHControl  function  QTVRGetControl Setti ng 
kQTVRReverseVControl  function  QTVRGetControl Setti ng 
kQTVRRight  function  QTVRInteracti onNudge 


(11-1368) 

(11-1368) 

(11-1368) 

(11-1368) 

(11-1368) 

(11-1389) 

(IV-2649) 

(11-1347) 

(11-1335) 

(11-1382) 

(11-1387) 

(11-1387) 

(11-1387) 

(11-1387) 

(11-1387) 

(11-1387) 

(11-1365) 

(IV-2649) 

(IV-2649) 

(IV-2649) 

(IV-2649) 

(11-1368) 

(11-1368) 

(IV-2649) 

(IV-2649) 

(IV-2649) 

(IV-2649) 

(IV-2649) 

(11-1344) 

(11-1344) 

(11-1352) 

(IV-2649) 

(11-1358) 

(IV-2649) 

(IV-2649) 

(11-1365) 

(11-1344) 

(11-1344) 

(11-1432) 

(11-1386) 

(11-1346) 

(11-1344) 

(11-1355) 

(11-1355) 

(11-1389) 
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kQTVRScrol 1 i ng 
kQTVRSel ecti ng 
kQTVRSetFi el dOfVi  ewSel  ector 
kQTVRSetPanAngl  eSel  ector 
kQTVRSetT i 1 tAngl  eSel  ector 
kQTVRSetVi ewCenterSel  ector 
kQTVRStartFi rstVi  ewFrames 
kQTVRStati c 
kQTVRStdCursorType 
kQTVRStri ngAtomType 
kQTVRStri ngEncodi ngAtomType 
kQTVRSugges ted Cache 
kQTVRSwapFIVControl 
kQTVRSyncVi ewToFrameRate 
kQTVRTilt 

kQTVRT i 1 tConstrai ntAtomType 

kQTVRT  rackRef ArrayAtomType 

kQTVRT ransi ti onDi recti  on 

kQTVRT  ransi ti on Speed 

kQTVRT  ransi ti onSwi ng 

kQTVRT  ransi ati ng 

kQTVRT  ransi ati on 

kQTVRT ri gger Hot Spot Sel  ector 

kQTVRUnconstrai  ned 

kQTVRUNudgeSameAs Mouse 

kQTVRUp 

kQTVRUpLeft 

kQTVRUpRi  ght 

kQTVRUseDef aul  tCursor 

kQTVRUseMovi eGeometry 

kQTVRVerti cal Cyl i nder 

kQTVRVi ewCenterH 

kQTVRVi ewCenterV 

kQTVRWorl  dFleaderAtomType 

kQTVRWrapPan 

kQTVRWrapTi 1 t 

kQTVRZoomi ng 

kQUALCOMMCompressi  on 

kQui ckDrawCodecType 

kQui ckDrawGXCodecType 

kRadi al Transi ti onType 

kRateConvert 

kRawCodecType 


kReverse 

kRGBColorBalancelmageFilterType 
kRol and8Bi tQual i ty 
k Rout inelsDispatched Default Routine 
kRTPMPHasUserSetti ngsDi al ogCharacteri sti c 

f uncti on 


function  QTVRGetCurrentMouseMode  (11-1358) 
function  QTVRGetCurrentMouseMode  (11-1358) 
function  QTVRInstal 1 InterceptProc  (11-1387) 
function  QTVRInstal 1 InterceptProc  (11-1387) 
function  QTVRInstal 1 InterceptProc  (11-1387) 
function  QTVRInstal 1 InterceptProc  (11-1387) 
function  QTVRGetAnimati onSetti ng  (11-1344) 
function  QTVRBegi nUpdateStream  (11-1335) 
struct  QTVRCursorRecord  (IV-2395) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
function  QTVRGetBackBufferMemlnfo  (11-1347) 
function  QTVRGetControl Setti ng  (11-1355) 
function  QTVRGetAnimati onSetti ng  (11-1344) 
function  QTVRGetConstrai nts  (11-1352) 
“Atom  ID  Codes"  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
function  QTVRSetTransi ti onProperty  (11-1435) 
function  QTVRSetTransi ti onProperty  (11-1435) 
function  QTVREnabl eTransi ti on  (11-1341) 
function  QTVRGetCurrentMouseMode  (11-1358) 
function  QTVRGetControl Setti ng  (11-1355) 
function  QTVRInstal 1 InterceptProc  (11-1387) 
function  QTVRGetConstrai ntStatus  (11-1353) 
function  QTVRGetlnteractionProperty  (11-1368) 
function  QTVRInteractionNudge  (11-1389) 
function  QTVRInteractionNudge  (11-1389) 
function  QTVRInteractionNudge  (11-1389) 
struct  QTVRCursorRecord  (IV-2395) 
function  QTVRGetBackBufferMemlnfo  (11-1347) 
function  QTVRGetBackBufferMemlnfo  (11-1347) 
function  QTVRWrapAndConstrai n  (11-1446) 
function  QTVRWrapAndConstrai n  (11-1446) 
“Atom  ID  Codes”  (IV-2649) 
function  QTVRGetControl Setti ng  (11-1355) 
function  QTVRGetControl Setti ng  (11-1355) 
function  QTVRGetCurrentMouseMode  (11-1358) 
“Sound  Formats”  (IV-2692) 
“Codec  Identifiers”  (IV-2655) 
“Codec  Identifiers"  (IV-2655) 
“Effects  Codes”  (IV-2662) 
“Sound  Device  Features”  (IV-2692) 
“Codec  Identifiers”  (IV-2655) 
“Sound  Device  Features”  (IV-2692) 
“Effects  Codes"  (IV-2662) 
struct  GMInstrumentlnfo  (IV-2272) 
struct  Routi neRecord  (IV-2405) 


RTPMPHasCharacteri sti c  (II 1-1471 ) 


Inside  QuickTime:  Index  of  Constants 


V-2977 


IXC 


Index  of  Constants 


kRTPMPMi nPacketDurati on  function  RTPMPGetlnfo  (III- 

kRTPMPMi nPayl oadSi ze  function  RTPMPGetlnfo  (III- 

kRTPMPNoSampleDataRequiredCharacteristic 

function  RTPMPHasCharacteri sti c  (III- 
kRTPMPPayl oadTypeDynami cFl ag  struct  RTPMPPayl oadTypeParams  (IV- 

kRTPMPPayl oadTypelnfo  function  RTPMPGetlnfo  (III- 

kRTPMPPayl oadTypeStati cFl ag  struct  RTPMPPayl oadTypeParams  (IV- 

kRTPMPPrefersReliableTransportCharacteristic 

function  RTPMPHasCharacteri sti c  (III- 
kRTPMPReal ti meModeFl ag  function  RTPMPIni ti al i ze  (III- 

kRTPMPRequi redSampl eDescripti onlnfo  function  RTPMPGetlnfo  (III- 

kRTPMPRequiresOutOfBandDimensionsCharacteristic 

function  RTPMPHasCharacteri Stic  (III- 

kRTPMPRTPTi meScal elnfo 
kRTPMPSti 11  Processing Data 
kRTPMPSuggestedRepeatedPktSpacinglnfo 
kRTPMPSuggestedRepeatPktCountlnfo 
kRTPMPSyncSampleFlag 
kRTPMPWantsMoreDataFlag 


kRTPRssmE very Packet AC hunk FI  ag 
kRTPRssm Lost Some Packets 
kRTPRssmNoReorderingRequiredFlag 


function  RTPMPGetlnfo  (Ill- 
function  RTPMPIdle  (Ill- 
function  RTPMPGetlnfo  (Ill- 
function  RTPMPGetlnfo  (in¬ 
struct  RTPMPSampl eDataParams  (IV- 
function  RTPMPSetSampl eData  (Ill- 
function  RTPRssmGetCapabi 1 i ti es  (Ill- 
function  RTPRssmSendPacketLi  st  (HI- 


1464) 

1464) 

1471) 

2407) 

1464) 

2407) 

1471) 

1473) 

1464) 

1471) 
1464) 

1472) 
1464) 
1464) 
2407) 
1480) 
1505) 
1518) 


function  RTPRssmGetCapabi 1 i ti es  (III -1505 ) 


kRTPRssmQueueAndUseMarkerBi  t FI  ag 


kRTPRssmTrackLostPacketsFlag 

kScheduledSoundDoCallBack 

kScheduledSoundDoScheduled 

kSchedul edSoundExtendedHdr 

kScreenFloodMethodAlpha 

kScreenFl oodMethodKeyCol or 

kScreenFloodMethodNone 

kScriptlsJavaScript 

kScriptlsLingoEvent 

kScri ptlsProjectorCommand 

kScri ptlsUnknownType 

kScri ptlsVBEvent 

kSel ectorsArelndexabl  e 

kSel ectorsAreNotlndexabl  e 


function  RTPRssmGetCapabi 1 i ti es  (Ill- 
function  RTPRssmGetCapabi  1  i  ti  es  (in¬ 
struct  ExtendedSchedul edSoundHeader  (IV- 
struct  ExtendedSchedul edSoundHeader  (IV- 
struct  Schedul edSoundHeader  (IV- 
struct  CodecDecompressParams  (IV- 
struct  CodecDecompressParams  (IV- 
struct  CodecDecompressParams  (IV- 
struct  QTDoScri ptRecord  (IV- 
struct  QTDoScri ptRecord  (IV- 
struct  QTDoScri ptRecord  (IV- 
struct  QTDoScri ptRecord  (IV- 
struct  QTDoScri ptRecord  (IV- 
struct  Routi neDescri ptor  (IV- 
struct  Routi neDescri ptor  (IV- 


kSetAtomi clnstCallerTosses 

function  NANewNoteChannel FromAtomi clnstrument  (II 
kSetAtomi clnstDontPreprocess 

function  NANewNoteChannel FromAtomi clnstrument  (II 
kSetAtomi clnstKeepOriginal Instrument 

function  NANewNoteChannel FromAtomi clnstrument  (II 
kSetAtomi clnstShareAcrossParts 

function  NANewNoteChannel FromAtomi clnstrument  (II 

kSGICodecType 
kSharpenlmageFilterType 


‘Codec  Identifiers’ 
“Effects  Codes’ 


(IV 

(IV 


-1505) 

-1505) 

-2251) 

-2251) 

-2419) 

-2190) 

-2190) 

-2190) 

-2352) 

-2352) 

-2352) 

-2352) 

-2352) 

-2404) 

-2404) 

-1031) 

-1031) 

-1031) 

-1031) 

-2655) 

-2662) 
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kSl i deTransi ti onType 
kSoftSynthComponentSubType  function 
kSol arizelmageFi 1 terType 
kSorensonCodecType 
kSorensonYUV9CodecType 
kSoundConverterDi dntFi llBuffer 


“Effects  Codes”  (IV-2662) 
InstrumentGetSynthesi zerType  (11-768) 
“Effects  Codes"  (IV-2662) 
“Codec  Identifiers”  (IV-2655) 
“Codec  Identifiers"  (IV-2655) 


f uncti on  SoundConverterFi llBuffer  (III- 1864 ) 


kSoundConverterHasLeftOverData 


kSoundNotCompressed 

kSourcePaused 


function  SoundConverterFi  llBuffer  (III- 1864 ) 
“Sound  Formats”  (IV-2692) 
function  SoundComponentPl aySourceBuf fer  (III- 1854 ) 


kSpri teAtomType 

“Atom 

ID 

Codes” 

(IV- 

-2649) 

kSpri teBehavi orsAtomType 

“Atom 

ID 

Codes” 

(IV- 

-2649) 

kSpri teCursorBehavi orAtomType 

“Atom 

ID 

Codes” 

(IV- 

-2649) 

kSpri teFl oati ngPoi ntVari abl eAtomType 

“Atom 

ID 

Codes” 

(IV- 

-2649) 

kSpri telmageAtomType 

“Atom 

ID 

Codes" 

(IV- 

-2649) 

kSpri telmageBehavi orAtomType 

“Atom 

ID 

Codes” 

(IV- 

-2649) 

kSpri telmageDataAtomType 

“Atom 

ID 

Codes” 

(IV- 

-2649) 

kSpri telmageDataRefAtomType 

“Atom 

ID 

Codes” 

(IV- 

-2649) 

kSpri telmageDataRefTypeAtomType 

“Atom 

ID 

Codes" 

(IV- 

-2649) 

kSpri  telmageDef aul tlmagelndexAtomType 

“Atom 

ID 

Codes" 

(IV- 

-2649) 

kSpri telmageGroupIDAtomType 

“Atom 

ID 

Codes” 

(IV- 

-2649) 

kSpri telmageNameAtomType 

“Atom 

ID 

Codes” 

(IV- 

-2649) 

kSpri telmageRegi strati onAtomType 

“Atom 

ID 

Codes” 

(IV- 

-2649) 

kSpri telmagesContai nerAtomType 

“Atom 

ID 

Codes" 

(IV- 

-2649) 

kSpri teNameAtomType 

“Atom 

ID 

Codes” 

(IV- 

-2649) 

kSpri tePropertyActi onHandl i ngSpri telD 

atom 

’ sprt ’ 

(IV- 

-2584) 

kSpri tePropertyGraphi csMode  f uncti on 

kSpri tePropertylmageDataPtr  f uncti on 

kSpri te Property ImageDescri pti on  f uncti on 

kSpri te Property  I mage  Index 

kSpri teProperty Layer  function 

kSpri tePropertyMatri x  f uncti on 

kSpri tePropertyVi si bl e  f uncti on 

kSpri teSharedDataAtomType 
kSpri teSta tus St ri ngsBehavi orAtomType 
kSpri teStri ngVari abl eAtomType 
kSpri  tellses  ImagelDsAtomType 
kSpri teVari abl esContai nerAtomType 
kSpri teWorl d  D i dDraw  function 

kSpri teWorl dNeedsToDraw  fun ct ion 

kSpri teWorl dPreFl i ght  f uncti on 

kStereoIn  “Sound 

kStereoOut  “Sound 

kSynthesi zerConnecti onFMS 
kSynthesi zerConnecti onMMgr 
kSynthesi zerConnecti onMono 
kSynthesi zerConnecti  onOMS 
kSynthesi zerConnecti onQT 


GetSpri teProperty  (I- 
GetSpri teProperty  (I- 
GetSpri teProperty  (I- 
atom  'sprt'  (IV- 
GetSpri teProperty  (I- 
GetSpri teProperty  (I- 
GetSpri teProperty  (I- 


“Atom 

“Atom 

“Atom 

“Atom 

“Atom 


Codes’ 

Codes’ 

Codes’ 

Codes’ 

Codes’ 


Spri teWorl dldl e 
Spri teWorl did! e 
Spri teWorl dldl e 
Device  Features’ 
Device  Features' 


struct  Synthesi zerConnecti ons 
struct  Synthesi zerConnecti ons 
struct  Synthesi zerConnecti ons 
struct  Synthesi zerConnecti ons 
struct  Synthesi zerConnecti ons 


(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(III 

(III 

(III 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 

(IV- 


512) 

512) 

512) 

2584) 

512) 

512) 

512) 

2649) 

2649) 

2649) 

2649) 

2649) 

1908) 

1908) 

1908) 

2692) 

2692) 

2464) 

2464) 

2464) 

2464) 

2464) 
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kSynthesi zerDynamicChannel 
kSynthesi zerDynami cVoi ce 
kSynthesi zerGM 
kSynthesi zerHardware 
kSynthesi zerHasSamples 
kSynthesi zerHogsSystemChannel 
kSynthesi zerMicrotone 
kSynthesi zerMi xedDrums 
kSynthesi zerOff 1 i ne 
kSynthesi zerSl owSetPart 
kSynthesi zer Software 
kSynthesi zerUsesMIDIPort 


struct  Synthesi zerDescri pti on  (IV-2465) 
struct  Synthesi zerDescri pti on  (IV-2465) 
struct  Synthesi zerDescri pti on  (IV-2465) 
struct  Synthesi zerDescri pti on  (IV-2465) 
struct  Synthesi zerDescri pti on  (IV-2465) 
struct  Synthesi zerDescri pti on  (IV-2465) 
struct  Synthesi zerDescri pti on  (IV-2465) 
struct  Synthesi zerDescri pti on  (IV-2465) 
struct  Synthesi zerDescri pti on  (IV-2465) 
struct  Synthesi zerDescri pti on  (IV-2465) 
struct  Synthesi zerDescri pti on  (IV-2465) 
struct  Synthesi zerDescri pti on  (IV-2465) 


kTargaCodecType 

“Codec  Identifiers’ 

’  ( I V  -  2  6  5  5  ) 

kTargetChildMovieMovielD 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kTargetChildMovieTrackID 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kTargetChildMovieTrackName 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kTargetMovi elD 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kTargetParentMovi  e 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kTargetRootMovi  e 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kTargetSpritelndex 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kTargetT  rackID 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kTargetT  rackName 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kTI FFCodecType 

“Codec  Identifiers’ 

’  (IV-2655) 

kT  rackModi fierlnput 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kT  rackModi fierlnputName 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kT  rackModi fierObjectID 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kT  rackModi fierObjectQTEventSend 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kT  rackModi fierPan Angle 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kT  rackModi fier Reference 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kT  rackModi f i erTi 1 tAngl e 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kT  rackModi f i erType 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kT  rackModi fierVertical FieldOfVi ewAngl e 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kTrackPropertylnstantiation 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kT  rackPropertyMedi aType 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kTrackReferenceChapterList 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kTrackReferenceModi f i er 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kTrackReferenceTi meCode 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kTuneDontClipNotes 

function 

T  uneQueue 

(  1 1 1-1964 ) 

kT  uneExcl udeEdgeNotes 

function 

F  uneQueue 

(  1 1 1-1964 ) 

kT  uneLoopUnti 1 

function 

F  uneQueue 

(  1 1 1-1964 ) 

kT  uneMi xMute 

function  TuneGetPartMix 

(  1 1 1-1960 ) 

kT  uneMi xSol  o 

function  TuneGetPartMix 

(  1 1 1-1960 ) 

kTuneQuickStart 

function 

T  uneQueue 

(  1 1 1-1964 ) 

kTuneStartNewMaster 

function 

T  uneQueue 

(  1 1 1-1964 ) 

kTuneStartNow 

function 

F  uneQueue 

( 1 1 1-1964 ) 

kTween3dInitial Condition 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kTweenData 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kTweenDurati on 

“Atom 

ID 

Codes’ 

’  (IV-2649) 

kTweenEntry 

“Atom 

ID 

Codes’ 

’  (IV-2649) 
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kTweenFlags  “Atom  ID  Codes”  (IV- 
kTweenlnterpol  ati  onID  “Atom  ID  Codes”  (IV- 
kTweenOutputMax  “Atom  ID  Codes"  (IV- 
kTweenOutputMi n  “Atom  ID  Codes"  (IV- 
kTweenPi ctureData  “Atom  ID  Codes”  (IV- 
kTweenRegi onData  “Atom  ID  Codes”  (IV- 
kTweenSequenceEl  ement  “Atom  ID  Codes”  (IV- 
kTweenStartOffset  “Atom  ID  Codes”  (IV- 
kTweenType  “Atom  ID  Codes”  (IV- 
kTweenType3dAngl eAspectCameraData  “Atom  ID  Codes”  (IV- 
kTweenType3dCameraData  “Atom  ID  Codes"  (IV- 
kTweenType3dMatrix  “Atom  ID  Codes”  (IV- 
kTweenType3dMatrixNonLinear  “Atom  ID  Codes”  (IV- 
kTweenType3dQuaterni on  “Atom  ID  Codes”  (IV- 
kTweenType3dRotate  “Atom  ID  Codes”  (IV- 
kTweenType3dRotateAboutAxi s  “Atom  ID  Codes"  (IV- 
kTweenType3dRotateAboutPoi nt  “Atom  ID  Codes"  (IV- 
kTweenType3dRotateAboutVector  “Atom  ID  Codes”  (IV- 
kTweenType3dScal e  “Atom  ID  Codes”  (IV- 
kTweenType3dSoundLocal i zati onData  “Atom  ID  Codes"  (IV- 
kTweenType3dTransl ate  “Atom  ID  Codes"  (IV- 
kTweenType3dVR0bject  “Atom  ID  Codes”  (IV- 
kTweenTypeAtomLi st  “Atom  ID  Codes”  (IV- 
kTweenTypeMul ti Matrix  “Atom  ID  Codes”  (IV- 
kTweenTypePathToFixedPoint  “Atom  ID  Codes"  (IV- 
kTweenTypePathToMatrixRotation  “Atom  ID  Codes”  (IV- 
kTweenTypePathToMatrixTransl ation  “Atom  ID  Codes”  (IV- 
kTweenTypePathToMatrixTransl ati onAndRotati on  “Atom  ID  Codes”  (IV- 
kTweenTypePathXtoY  “Atom  ID  Codes”  (IV- 
kTweenTypePathYtoX  “Atom  ID  Codes"  (IV- 
kTweenTypePolygon  “Atom  ID  Codes”  (IV- 
kTweenTypeSpi n  “Atom  ID  Codes”  (IV- 
kTwosCompl ement  “Sound  Formats”  (IV- 
kULawCompressi on  “Sound  Formats”  (IV- 
kUseNati velSA  struct  Routi neRecord  (IV- 
kUseOpti onal OutputDevi ce  function  SndNewChannel  (III- 
kUserDataMovi eControl 1 erType  "User  Data  Identifiers”  (IV- 
kUserDataName  "User  Data  Identifiers”  (IV- 
kUserDataTextAuthor  "User  Data  Identifiers”  (IV- 
kUserDataTextChapter  “User  Data  Identifiers"  (IV- 
kUserDataTextComment  "User  Data  Identifiers”  (IV- 
kUserDataTextCopyri ght  "User  Data  Identifiers”  (IV- 
kUserDataTextCreati onDate  "User  Data  Identifiers”  (IV- 
kUserDataTextDescri pti on  "User  Data  Identifiers”  (IV- 
kUserDataTextDi rector  “User  Data  Identifiers"  (IV- 
kUserDataTextDi scl aimer  "User  Data  Identifiers”  (IV- 
kUserDataTextEdi tDatel  “User  Data  Identifiers”  (IV- 
kUserDataTextFul 1  Name  "User  Data  Identifiers”  (IV- 
kUserDataTextHostComputer  "User  Data  Identifiers”  (IV- 
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kUserDataTextlnformati on 

"User 

Data 

Identi f i ers” 

(IV-2696) 

kUse r Da taText Keywords 

“User 

Data 

Identi f i ers” 

(IV-2696) 

kllserDataTextMake 

"User 

Data 

Identi f i ers” 

(IV-2696) 

kllserDataTextModel 

"User 

Data 

Identi f i ers” 

(IV-2696) 

kUserDataTextOri ginal Format 

"User 

Data 

Identi f i ers” 

(IV-2696) 

kUserDataTextOri ginal Source 

"User 

Data 

Identi f i ers” 

(IV-2696) 

kUser Da taText Performers 

“User 

Data 

Identi f i ers” 

(IV-2696) 

kUser Da taText Producer 

"User 

Data 

Identi f i ers” 

(IV-2696) 

kUser Da taText Product 

"User 

Data 

Identi f i ers” 

(IV-2696) 

kUserDataTextSoftware 

"User 

Data 

Identi f i ers” 

(IV-2696) 

kUserDataTextSpeci alPlaybackRequi remen ts 

"User 

Data 

Identi f i ers” 

(IV-2696) 

kUserDataTextWarni ng 

“User 

Data 

Identi f i ers” 

(IV-2696) 

kUserDataTextWri ter 

"User 

Data 

Identi f i ers” 

(IV-2696) 

kUYVY422Pi xel Format 

"Pixel  Formats” 

(IV-2686) 

kVectorCodecType 

"Codec 

Identi f i ers” 

(IV-2655) 

kVersi onCheckMask 
kVersi onCheckMi n 
kVi deoCodecType 
kVMAwareness 
kWaterRippleCodecType 
kWhi chActi on 
kWi ndowsRawCodecType 
kWi peTransi ti onType 
kY  U  V  2 1 1 P i xel Format 
kY  U  V41 1 P i xel Format 
kYUV420CodecType 
kYUVSPi xel Format 
kYUVUPi xel Format 
kYVU9Pi xel Format 
kYVYU422Pi xel Format 
kZoomT  ransiti onType 
1 angAf ri kaans 
1 angAl bani an 
1 angAmhari c 
1 angArabi c 
1 angArmeni an 
1 angAssamese 
1 angAymara 
1 angAzerbai janAr 
1 angAzerbai jani 
1 angBasque 
1  angBel orussi an 
1 angBengal i 
1  angBreton 
1 angBul gari an 
1 angBurmese 
1 angByel orussi an 
1 angCatal an 
1 angChewa 


struct  QTA1 tVersi onCheckRecord  (IV- 2348 ) 
struct  QTA1 tVersi onCheckRecord  (IV- 2348 ) 
“Codec  Identifiers”  (IV-2655) 
“Sound  Device  Features”  (IV-2692) 
“Codec  Identifiers”  (IV-2655) 
“Atom  ID  Codes”  (IV-2649) 
“Codec  Identifiers”  (IV-2655) 
“Effects  Codes”  (IV-2662) 
“Pixel  Formats”  (IV-2686) 
“Pixel  Formats”  (IV-2686) 
“Codec  Identifiers”  (IV-2655) 
“Pixel  Formats”  (IV-2686) 
“Pixel  Formats”  (IV-2686) 
“Pixel  Formats”  (IV-2686) 
“Pixel  Formats”  (IV-2686) 
“Effects  Codes”  (IV-2662) 
"Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
"Localization  Codes”  (IV-2673) 
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1 angCroati an 

“Local i zati on 

Codes” 

(IV-2673) 

1 angCzech 

“Local i zati on 

Codes” 

( IV-2673) 

1 angDani sh 

“Local i zati on 

Codes” 

(IV-2673) 

1 angDutch 

“Local i zati on 

Codes" 

(IV-2673) 

1 angDzongkha 

“Local i zati on 

Codes” 

(IV-2673) 

1 angEngl i sh 

“Local i zati on 

Codes” 

(IV-2673) 

1 angEsperanto 

“Local i zati on 

Codes” 

(IV-2673) 

1 angEstoni an 

“Local i zati on 

Codes” 

(IV-2673) 

1 angFaroese 

“Local i zati on 

Codes” 

(IV-2673) 

1 angFarsi 

“Local i zati on 

Codes” 

(IV-2673) 

langFinnish 

“Local i zati on 

Codes" 

(IV-2673) 

1  angFl  emi  sh 

“Local i zati on 

Codes” 

(IV-2673) 

1 angFrench 

“Local i zati on 

Codes” 

(IV-2673) 

1 angGal i cl  an 

“Local i zati on 

Codes” 

(IV-2673) 

1 angGeorgi an 

“Local i zati on 

Codes” 

(IV-2673) 

1 angGerman 

“Local i zati on 

Codes" 

(IV-2673) 

1 angGreek 

“Local i zati on 

Codes” 

(IV-2673) 

1 angGreekPoly 

“Local i zati on 

Codes” 

(IV-2673) 

1 angGreenl andi c 

“Local i zati on 

Codes” 

(IV-2673) 

1 angGuarani 

“Local i zati on 

Codes" 

(IV-2673) 

1 angGujarati 

“Local i zati on 

Codes" 

(IV-2673) 

1 angHebrew 

“Local i zati on 

Codes” 

(IV-2673) 

1 angHi ndi 

“Local i zati on 

Codes” 

(IV-2673) 

1 angHungari an 

“Local i zati on 

Codes” 

(IV-2673) 

1 anglcel andi c 

“Local i zati on 

Codes” 

(IV-2673) 

1 anglndonesi an 

“Local i zati on 

Codes” 

(IV-2673) 

1 anglnukti tut 

“Local i zati on 

Codes” 

(IV-2673) 

1  anglri shGael i c 

“Local i zati on 

Codes” 

(IV-2673) 

1  anglri shGael i c. 

atom 

'wtxt ' 

(IV-2616) 

1 anglri shGael i cScri pt 

“Local i zati on 

Codes” 

(IV-2673) 

1 anglri shGael i cScri pt. 

atom 

'wtxt' 

(IV-2616) 

1 angltal i an 

“Local i zati on 

Codes” 

(IV-2673) 

1 angJapanese 

“Local i zati on 

Codes” 

(IV-2673) 

1 angJavaneseRom 

“Local i zati on 

Codes” 

(IV-2673) 

1 angKannada 

“Local i zati on 

Codes" 

(IV-2673) 

1 angKashmi ri 

“Local i zati on 

Codes” 

(IV-2673) 

1 angKazakh 

“Local i zati on 

Codes” 

(IV-2673) 

1 angKhmer 

“Local i zati on 

Codes” 

(IV-2673) 

1 angKi nyarwanda 

“Local i zati on 

Codes” 

(IV-2673) 

1  angKi  rghi  z 

“Local i zati on 

Codes" 

(IV-2673) 

1 angKorean 

“Local i zati on 

Codes” 

(IV-2673) 

1 angKurdi sh 

“Local i zati on 

Codes” 

(IV-2673) 

1 angLao 

“Local i zati on 

Codes” 

(IV-2673) 

1 angLati n 

“Local i zati on 

Codes” 

(IV-2673) 

1 angLatvi an 

“Local i zati on 

Codes" 

(IV-2673) 

1 angLi thuani an 

“Local i zati on 

Codes” 

(IV-2673) 

1 angMacedoni an 

“Local i zati on 

Codes” 

(IV-2673) 

1 angMal agasy 

“Local i zati on 

Codes” 

(IV-2673) 

1 angMal ayal am 

“Local i zati on 

Codes" 

(IV-2673) 
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1  angMal ayArabi c 

“Local i zati on 

Codes” 

(IV-2673) 

1 angMal ayRoman 

“Local i zati on 

Codes” 

(IV-2673) 

1 angMal tese 

“Local i zati on 

Codes” 

(IV-2673) 

1 angManxGael i c 

“Local i zati on 

Codes” 

(IV-2673) 

1 angMarathi 

“Local i zati on 

Codes” 

(IV-2673) 

1 angMol davi an 

“Local i zati on 

Codes” 

(IV-2673) 

1 angMongol i an 

“Local i zati on 

Codes” 

(IV-2673) 

1 angMongol i anCy r 

“Local i zati on 

Codes” 

(IV-2673) 

1 angNepal i 

“Local i zati on 

Codes” 

(IV-2673) 

1 angNorwegi an 

“Local i zati on 

Codes” 

(IV-2673) 

1 angNyanja 

“Local i zati on 

Codes” 

(IV-2673) 

1 angOriya 

“Local i zati on 

Codes” 

(IV-2673) 

1 angOromo 

“Local i zati on 

Codes” 

(IV-2673) 

1 angPashto 

“Local i zati on 

Codes” 

(IV-2673) 

1 angPersi an 

“Local i zati on 

Codes” 

(IV-2673) 

1 angPol i sh 

“Local i zati on 

Codes” 

(IV-2673) 

1 angPortuguese 

“Local i zati on 

Codes” 

(IV-2673) 

1 angPunjabi 

“Local i zati on 

Codes” 

(IV-2673) 

1 angQuechua 

“Local i zati on 

Codes” 

(IV-2673) 

1 angRomani an 

“Local i zati on 

Codes” 

(IV-2673) 

1 angRuanda 

“Local i zati on 

Codes” 

(IV-2673) 

1 angRundi 

“Local i zati on 

Codes” 

(IV-2673) 

1 angRussi an 

“Local i zati on 

Codes” 

(IV-2673) 

1 angSami 

“Local i zati on 

Codes” 

(IV-2673) 

1 angSanskri t 

“Local i zati on 

Codes” 

(IV-2673) 

1 angScotti shGael i c 

“Local i zati on 

Codes” 

(IV-2673) 

1 angSerbi an 

“Local i zati on 

Codes” 

(IV-2673) 

1  angSi mpChi nese 

“Local i zati on 

Codes” 

(IV-2673) 

1  angSi mpChi nese , 

atom 

'wtxt ' 

(IV-2616) 

1 angSi ndhi 

“Local i zati on 

Codes” 

(IV-2673) 

1 angSi nhal ese 

“Local i zati on 

Codes” 

(IV-2673) 

1 angSi ovak 

“Local i zati on 

Codes” 

(IV-2673) 

1 angSi oveni an 

“Local i zati on 

Codes” 

(IV-2673) 

1 angSomal i 

“Local i zati on 

Codes” 

(IV-2673) 

1 angSpani sh 

“Local i zati on 

Codes” 

(IV-2673) 

1 angSundaneseRom 

“Local i zati on 

Codes” 

(IV-2673) 

1 angSwahi 1 i 

“Local i zati on 

Codes” 

(IV-2673) 

1 angSwedi sh 

“Local i zati on 

Codes” 

(IV-2673) 

1 angTagal og 

“Local i zati on 

Codes” 

(IV-2673) 

langTajiki 

“Local i zati on 

Codes” 

(IV-2673) 

1 angTami  1 

“Local i zati on 

Codes” 

(IV-2673) 

1 angTatar 

“Local i zati on 

Codes” 

(IV-2673) 

1 angTel ugu 

“Local i zati on 

Codes” 

(IV-2673) 

1 angThai 

“Local i zati on 

Codes” 

(IV-2673) 

1 angT i betan 

“Local i zati on 

Codes” 

(IV-2673) 

1 angT i gri nya 

“Local i zati on 

Codes” 

(IV-2673) 

1 angTongan 

“Local i zati on 

Codes” 

(IV-2673) 

1 angT  radChi nese 

“Local i zati on 

Codes” 

(IV-2673) 

1 angT  radChi nese , 

atom 

'wtxt ' 

(IV-2616) 
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1 angTurki sh 
1 angTurkmen 
1 angUi ghur 
1 angUkrai ni an 
1 angUnspeci f i ed 
1  angllrdu 
1  angllzbek 
1 angVi etnamese 
1 angWel sh 
1 angY i ddi sh 
1 eftOverBl ockSi ze 
1 i mi tReachedErr 
1 inearMatrixType 
1 i nearTransl ateMatri xType 
'link' 

1 i nkSoundComponentsCmd 
' 1 oad ' 

1 oadBackwardT  rackEdi ts 
1 oadForwardT  rackEdi ts 
LoadSetti ngsAID 
lockPortBitsBadPortErr 
lockPortBitsBadSurfaceErr 
lockPortBitsSurfaceLostErr 
1 ockPortBi tsWi ndowCl i ppedErr 
1 ockPortBi tsWi ndowMovedErr 
1 ockPortBi tsWi ndowResi zed  Err 
lockPortBitsWrongGDeviceErr 
' LOOP' 

1 oopT i meBase 
' MAC3 ' 

' MAC6 ' 

magentaCol or 
mai nScreen 
mapPix 
mAtEnd 
matri xErr 
matrixFl  agScal  elx 
matrixFl  agScal  e2x 
matrixFl  agScal  eHalf 
'matt ' 

MatteAID 

MatteCompAID 

'maxr' 

maxSi zeToGrowTooSmal 1 
mcActi onActi vate 
mcActi on Ad j ustCursor 
mcActi onBadgeCl i ck 
mcActi  onCl  i  ckAndhlol  dPoi  nt 
mcActi onControllerSi zeChanged 


‘‘Localization  Codes”  (IV-2673) 
‘‘Localization  Codes"  (IV-2673) 
‘‘Localization  Codes"  (IV-2673) 
‘‘Localization  Codes”  (IV-2673) 
‘‘Localization  Codes"  (IV-2673) 
‘‘Localization  Codes”  (IV-2673) 
‘‘Localization  Codes"  (IV-2673) 
‘‘Localization  Codes”  (IV-2673) 
‘‘Localization  Codes”  (IV-2673) 
‘‘Localization  Codes"  (IV-2673) 
struct  LeftOverBl ock  (IV-2301) 
“Error  Codes"  (IV-2663) 
function  GetMatrixType  (1-419) 
function  GetMatrixType  (1-419) 
atom  'link'  (IV-2556) 
“Sound  Commands”  (IV-2691) 
atom  'load'  (IV-2556) 
function  LoadMedialntoRam  (11-779) 
function  LoadMedialntoRam  (11-779) 
“Atom  ID  Codes"  (IV-2649) 
“Error  Codes"  (IV-2663) 
“Error  Codes"  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Error  Codes"  (IV-2663) 
“Error  Codes"  (IV-2663) 
“Error  Codes"  (IV-2663) 
atom  'LOOP'  (IV-2557) 
function  GetTimeBaseFl ags  (1-515) 
function  GetCompressi onlnfo  (1-398) 
function  GetCompressionlnfo  (1-398) 
“Color  Constants”  (IV-2657) 
struct  GDevice  (IV-2264) 
function  NewImageGWorl d  (11-1066) 
function  Medialdle  (11-874) 
atom  'wtxt'  (IV-2616) 
struct  CodecDecompressParams  (IV-2190) 
struct  CodecDecompressParams  (IV-2190) 
struct  CodecDecompressParams  (IV-2190) 
atom  'matt'  (IV-2557) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
atom  'maxr'  (IV-2558) 
“Error  Codes”  (IV-2663) 
“Movie  Controller  Actions"  (IV - 2680 ) 
“Movie  Controller  Actions"  (IV - 2680 ) 
“Movie  Controller  Actions"  (IV - 2680 ) 
“Movie  Controller  Actions”  (IV- 2680 ) 
“Movie  Controller  Actions”  (IV- 2680 ) 
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mcActi onCustomButtonClick 
mcActi on  Deactivate 
mcActi onDoScri pt 
mcActi onDraw 

mcActi on  Eva  1 uateExpressi on 

mcActi onExecuteAl 1  Actions ForQT Event 

mcActi onExecuteOneActi onForQTEvent 

mcActi on  Fetch  Parameter As 

mcActi onForceTi meTabl eUpdate 

mcActi onGetChapterTime 

mcActi onGetCursorBylD 

mcActi onGetCursorSettingEnabled 

mcActi on GetDrag Enabled 

mcActi on Get  External  Movie 

mcActi onGetFl ags 

mcActi onGetlndChapter 

mcActi onGetKeysEnabl ed 

mcActi on Get  Loop i ng 

mcActi on Get  Loop Is  Pa  1 i ndrome 

mcActi on Get Next URL 

mcActi on Get PI  ay  Every  Frame 

mcActi onGetPl ay Rate 

mcActi onGetPlaySelection 

mcActi onGetSelectionBegin 

mcActi onGetSelectionDuration 

mcActi onGetTi meSl i derRect 

mcActi onGetUseBadge 

mcActi onGetVol ume 

mcActionGoToTime 

mcActi onldl e 

mcActi onKey 

mcActi onLinkToURL 

mcActi on Mo use Down 

mcActi onMovieChanged 

mcActi onMovi eCl i ck 

mcActi onMovi eEdi ted 

mcActi onPerformActi on  List 

mcActi onPl ay 

mcActi onPrerollAndPlay 

mcActi on  Res tart AtT i me 

mcActi onResume 

mcActi onSetColorTable 

mcActi onSetControll  erKeysEnabl  ed 

mcActi onSetControllerTi  me  Limits 

mcActi onSetCursorSettingEnabled 

mcActi onSetDragEnabled 

mcActi onSetFl  ags 

mcActi onSetGrowBoxBounds 

mcActi onSet Key sEnabl  ed 


‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
‘Movie  Controller  Actions”  (IV-2680) 
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mcActi onSetLoopi ng 

mcActi onSetLoopIsPal i ndrome 

mcActi onSetPl ayEveryFrame 

mcActi onSetPl aySel ecti on 

mcActi onSetSel ecti onBegi n 

mcActi onSetSel ecti onDurati on 

mcActi onSetUseBadge 

mcActi onSetVol ume 

mcActi onShowBal 1 oon 

mcActi onShowMessageStri ng 

mcActi onShowStatusStri ng 

mcActi onStep 

mcActi onSuspend 

mcActi  onllseTrackForTi meTabi  e 

mcFlagSuppressMovieFrame 

mcFlagSuppressSpeakerButton 

mcFlagSuppressStepButtons 

me FI agsUseWi ndowPal ette 

mclnfoCI earAvai 1  a  bl e 

mclnfoCopyAvai 1 abl  e 

mclnfoCutAvai  1  abl  e 

mclnfoEdi ti ngEnabl ed 

mclnfoHasSound 

mclnfoIsInPal i ndrome 

mclnfoIsLoopi ng 

mclnfoIsPI ayi ng 

mclnfoPasteAvai 1 abl e 

mclnfoUndoAvai 1 abl e 

mcMenuCl ear 

mcMenuCopy 

mcMenuCut 

mcMenuPaste 

mcMenuUndo 

mcNotVi si bl e 

mcPosi  ti  onDontlnval idate 

mcScal eMovi eToFi t 

mcTopLeftMovi e 

mcWi thBadge 

mcWi thFrame 

'mdat' 

'mdhd ' 

'mdi a ' 
mDi dDraw 
Medi aAID 

Medi aHandl erType 
Medi aHeaderAID 
Medi alnfoAID 
medi aQual i tyBest 
medi aQual i tyBetter 


“Movi e 
“Movi e 
“Movi e 


“Movi e 
“Movi e 
“Movi e 


“Movie  Controller  Actions” 
“Movie  Controller  Actions” 
Controller  Actions” 
Controller  Actions” 
Controller  Actions” 
“Movie  Controller  Actions” 
“Movie  Controller  Actions” 
“Movie  Controller  Actions” 
Controller  Actions” 
Controller  Actions” 
Controller  Actions” 
“Movie  Controller  Actions” 
“Movie  Controller  Actions” 
“Movie  Controller  Actions” 
atom  'wtxt' 
atom  'wtxt' 
atom  'wtxt' 
atom  'wtxt' 
MCGetControl 1 erlnfo 
MCGetControl 1 erlnfo 
MCGetControl 1 erlnfo 
MCGetControl 1 erlnfo 
MCGetControl 1 erlnfo 
MCGetControl 1 erlnfo 
MCGetControl 1 erlnfo 
MCGetControl 1 erlnfo 
MCGetControl 1 erlnfo 
function  MCGetControl 1 erlnfo 
function  MCGetMenuStri ng 
MCGetMenuStri ng 
MCGetMenuStri ng 
MCGetMenuStri ng 
MCGetMenuStri ng 
function  NewMovi eControl 1 er 
function  MCPosi ti onControl 1 er 
function  MCPosi ti onControl 1 er 
function  MCPosi ti onControl 1 er 
function  NewMovi eControl 1 er 
function  NewMovi eControl 1 er 
atom  'mdat' 
atom  'mdhd' 
atom  'mdi a' 
function  Medialdle 
“Atom  ID  Codes” 
“Component  Identifiers” 
“Atom  ID  Codes” 
“Atom  ID  Codes” 
function  GetMedi aQual i ty 
function  GetMedi aQual i ty 


f uncti 
f uncti 
f uncti 
f uncti 
f uncti 
f uncti 
f uncti 
f uncti 
f uncti 


on 

on 

on 

on 

on 

on 

on 

on 

on 


f uncti on 
f uncti on 
f uncti on 
f uncti on 


( I V  -  2  68  0 ) 

( I V  -  2680 ) 

(IV-2680) 

(IV-2680) 

(IV-2680) 

(IV-2680) 

(IV-2680) 

(IV-2680) 

(IV-2680) 

(IV-2680) 

(IV-2680) 

(IV-2680) 

(IV-2680) 

(IV-2680) 

(IV-2616) 

(IV-2616) 

(IV-2616) 

(IV-2616) 

(11-808) 

(11-808) 

(11-808) 

(11-808) 

(11-808) 

(11-808) 

(11-808) 

(11-808) 

(11-808) 

(11-808) 

(11-814) 

(11-814) 

(11-814) 

(11-814) 

(11-814) 

(11-1071) 

(11-824) 

(11-824) 

(11-824) 

(11-1071) 

(11-1071) 

(IV-2558) 

( I V  -  2  5  5  9 ) 

(IV-2560) 

(11-874) 

( I V  -  2 64 9 ) 
( I V  -  2  6  5  7  ) 
( I V  -  2 64 9 ) 
( I V  -  2  64  9 ) 
(1-441) 
(1-441) 
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medi aQual i tyDraft 
medi aQual i tyNormal 
medi a Samp 1 e Not Sync 
medi aTypesDontMatch 
'  mi  cr ' 

midi ManagerAbsentOSErr 
'mill  ' 

mi  1 1  i  seconds 
'mime' 

'  mi  nf ' ( base ) 

'  mi  nf ' ( generi c ) 

' mi nf ' (sound ) 

' mi nf ' ( vi deo ) 

missing RequiredParameterErr 

mMustDraw 

mNeedsToDraw 

' moov ' 

mouseDown 

mouseMovedMessage 

mousellp 

Movi eAID 

Movi eBufferHi ntsAID 

MovieControll erComponentType 

Movi eDataAtomType 

Movi eDataRefAl i as AID 

movi eDrawi ngCal 1 A1 ways  function 

movieDrawingCallWhenChanged 

f uncti on 

movi eExportDurati on  callback 

movi eExportHei ght  callback 

movi eExportMustGetSourceMedi aType 
movi e Export Needs  Resource  Fork 
Movi eExportType 

movi eExportVi deoFi 1  ter  callba 

movi eExportWi dth  callba 

movi e  F i 1 eSpecVal i d 
Movi eHeaderAID 
movielmportCreateTrack 
movi elmportlnParal lei 
movi el mportMustUseT rack 
movielmportResultUsedMultipleTracks 
movielmportSubTypelsFil eExtensi on 
Movi elmportType 
movielnDataForkResID 
Movi eMedi aType 
movieProgressClose 
movi eProgressOpen 
movieProgressUpdatePercent 
Movi eResourceAtomType 


function  GetMedi aQual i ty  (1-441) 
function  GetMedi aQual i ty  (1-441) 
function  AddMedi aSampl e  (1-27) 

“Error  Codes”  (IV-2663) 
atom  'wtxt'  (IV-2616) 
“Error  Codes”  (IV-2663) 
atom  'wtxt'  (IV-2616) 
function  SPBRecord  (III -1878 ) 
atom  'mime'  (IV-2561) 
atom  'minf'(base)  (IV-2561) 
atom  'minf' (generic)  (IV-2562) 
atom  ' mi nf ' (sound )  (IV- 2564 ) 
atom  ' mi nf ' ( vi deo )  (IV-2565) 
“Error  Codes”  (IV-2663) 
function  Medialdle  (11-874) 
function  Medialdle  (11-874) 
atom  'moov'  (IV-2566) 
struct  EventRecord  (IV-2246) 
struct  EventRecord  (IV-2246) 
struct  EventRecord  (IV-2246) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
“Component  Identifiers”  (IV-2657) 
“Atom  ID  Codes”  (IV-2649) 
“Atom  ID  Codes”  (IV-2649) 
Set Movi eDrawi ngCompl eteProc  (III-1617) 

Set Movi eDrawi ngCompl eteProc  (III-1617) 
Movi e Expo rtGetP rope rtyP roc  (III -2102 ) 
Movi e Expo rtGetP rope rtyP roc  (III -2102 ) 
struct  ComponentDescri pti on  (IV-2212) 
struct  ComponentDescri pti on  (IV-2212) 
“Component  Identifiers”  (IV-2657) 
ck  Movi eExportGetPropertyProc  (III -2102 ) 
ck  Movi eExportGetPropertyProc  (III -2102 ) 
function  ConvertFileToMovieFile  (1-129) 
“Atom  ID  Codes”  (IV-2649) 
function  MovielmportFile  ( 11-942 ) 
function  MovielmportFile  (11-942) 
function  MovielmportFile  (11-942) 
function  MovielmportFile  (11-942) 
struct  ComponentDescri pti on  (IV-2212) 
“Component  Identifiers”  (IV-2657) 
function  AddMovi eResource  (1-36) 
“Component  Identifiers”  (IV-2657) 
callback  Movi eProgressProc  (III-2105) 
callback  Movi eProgressProc  (III-2105) 
callback  Movi eProgressProc  (III-2105) 
“Atom  ID  Codes”  (IV-2649) 
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movieScrapDontZeroScrap 
movi eScrapOnly PutMovi  e 
movi eTextNot Found  Err 
movieToFi 1 eOnly Export 
movi eTool boxUni ni ti al i zed 
movi eT  rackCharacteri Stic 
movieTrackEnabledOnly 
movi eTrackMedi a Type 
mParti al Draw 
MPEGMedi aType 
mPref  1  i  ghtDraw 
Musi  cMedi aType 
'mvhd ' 

'name' (sprite) 

' name ' ( userdata  ) 

' ndhd ' 
newDepth 
newMovi eActi ve 

newMovi eDontAs kUn resol  vedData 

newMovi eDontAutoAl  ternate 

newMovi eDontResolveDataRefs 

newRowBytes 

nextTimeEdgeOK 

nextTimelgnoreActi veSegment 

nextTi meMedi a  Ed i  t 

nextTimeMedi aSampl  e 

nextTimeStep 

nextTi meSyncSampl e 

nextTi meT  rackEdi t 

'  nl  oc ' 

noCodecErr 

noDataHandl er 

noDefaul tDataRef 

noDef aul tOpcodes 

noDMAErr 

noDri ver 

noErr  funct 

noExportProcAvai 1 abl eErr 
noMedi aHandl er 

noMemoryNodeFai 1 edlni  ti  al  i  ze 
noMoreKeyCol orsErr 
noMovi eFound 
'NONE' 

noNewDevi ce 
nonMatchi ngEdi t St ate 
noPathMappi ngErr 
noRecordOf App 
noSoundTracklnMovieErr 
noSourceT  reeFoundErr 


function  PutMovi eOnScrap  (II- 
function  PutMovi eOnScrap  (II- 
“Error  Codes"  (IV- 
function  ConvertFi 1 eToMovieFi 1 e  (I- 
“Error  Codes"  (IV- 
function  GetMovielndTrackType  (I- 
function  GetMovielndTrackType  (I- 
function  GetMovielndTrackType  (I- 
function  Medialdle  (II- 
“Component  Identifiers”  (IV- 
function  Medialdle  (II- 
“Component  Identifiers”  (IV- 
atom  'mvhd'  (IV- 
atom  'name' (sprite)  (IV- 
atom  ' name '( userdata  )  (IV- 
atom  'ndhd'  (IV- 
function  NewImageGWorl d  (II- 
function  CreateMovi eFi 1 e  (I- 
Refs  function  NewMovieFromDataFork  (II- 
function  CreateMovi eFi 1 e  (I- 
function  NewMovieFromDataFork  (II- 
function  NewImageGWorl d  (II- 
function  GetMedi aNext Interesti ngTime  (I- 
function  GetMovieNextlnterestingTime  (I- 
function  GetMedi aNextlnteresti ngTime  (I- 
function  GetMedi aNextlnteresti ngTime  (I- 
function  MediaGetNextStepTime  (II- 
function  GetMedi aNextlnteresti  ngTime  (I- 
function  GetMovieNextlnterestingTime  (I- 

atom  'nloc'  (IV- 
“Error  Codes"  (IV- 
“Error  Codes”  (IV- 
“Error  Codes”  (IV- 
function  StdPix  (Ill- 
atom  'wtxt'  (IV- 
struct  GDevice  (IV- 
ion  QTIsStandardParameterDi  al  ogEvent  (II- 

“Error  Codes”  (IV- 
“Error  Codes"  (IV- 
“Error  Codes”  (IV- 
atom  'wtxt'  (IV- 
“Error  Codes”  (IV- 
function  GetCompressionlnfo  (I- 
function  NewImageGWorl d  (II- 
“Error  Codes”  (IV- 
“Error  Codes”  (IV- 
atom  'wtxt'  (IV- 
“Error  Codes"  (IV- 
“Error  Codes”  (IV- 
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notAl 1 owedToSaveMovi eErr 

“Error  Codes” 

(IV-2663) 

notAQTVRMovi eErr 

“Error  Codes” 

(IV-2663) 

notCompressed 

function  GetCompressi onlnfo  (1-398) 

noteChannel NotAl locatedOSErr 

“Error  Codes” 

(IV-2663) 

notEnoughDataErr 

“Error  Codes” 

(IV-2663) 

notExactMatri xErr 

atom  'wtxt' 

(IV-2616) 

notExactSi zeErr 

atom  'wtxt' 

(IV-2616) 

notlmpl ementedMusi cOSErr 

“Error  Codes” 

(IV-2663) 

notLeaf AtomErr 

“Error  Codes” 

(IV-2663) 

notPatBi c 

“Graphics  Transfer  Modes” 

(IV-2670) 

notPatCopy 

“Graphics  Transfer  Modes” 

(IV-2670) 

notPatOr 

“Graphics  Transfer  Modes” 

(IV-2670) 

notPatXor 

“Graphics  Transfer  Modes” 

(IV-2670) 

notSrcBi c 

“Graphics  Transfer  Modes” 

(IV-2670) 

notSrcBi c , 

atom  'wtxt' 

(IV-2616) 

notSrcCopy 

“Graphics  Transfer  Modes” 

(IV-2670) 

notSrcCopy , 

atom  'wtxt' 

(IV-2616) 

notSrcOr 

“Graphics  Transfer  Modes” 

(IV-2670) 

notSrcOr , 

atom  'wtxt' 

(IV-2616) 

notSrcXor 

“Graphics  Transfer  Modes” 

(IV-2670) 

notSrcXor , 

atom  'wtxt' 

(IV-2616) 

noVideoTracklnMovieErr 

“Error  Codes” 

(IV-2663) 

ntscln 

function  VDGetVBl ankRect 

( 1 1 1  -2021 ) 

nul  1  Cmd 

“Sound  Commands” 

(IV-2691) 

nul 1  Event 

struct  EventRecord 

(IV-2246) 

'nump' 

atom  'nump' 

(IV-2570) 

' obi d ' 

oddFieldlToEvenFieldOut 

atom  '  o b i d ' 

(IV-2571) 

f uncti on 

oddFieldlToOddFieldOut 

ImageCodecExtractAndCombi neFi el ds 

(11-705) 

f uncti on 

oddField2ToEvenField0ut 

ImageCodecExtractAndCombi neFi el ds 

(11-705) 

f uncti on 

oddField2To0ddField0ut 

ImageCodecExtractAndCombi neFi  el  ds 

(11-705) 

f uncti on 

ImageCodecExtractAndCombi neFi  el  ds 

(11-705) 

opti onKey 

function  QTVRMouseDown 

(11-1391) 

osEvt 

struct  EventRecord 

(IV-2246) 

osEvtMessageMask 

struct  EventRecord 

(IV-2246) 

pal  In 

function  VDGetVBl ankRect 

( 1 1 1  -2021 ) 

pal i ndromeLoopT i me Base 

function  GetTimeBaseFlags  (1-515) 

pastelnParal 1  el 

function  PasteHandl elntoMovi e 

(11-1137) 

patBi c 

“Graphics  Transfer  Modes” 

(IV-2670) 

patCopy 

“Graphics  Transfer  Modes” 

(IV-2670) 

pathNotVerifiedErr 

“Error  Codes” 

(IV-2663) 

pathTooLongErr 

“Error  Codes” 

(IV-2663) 

patOr 

“Graphics  Transfer  Modes” 

(IV-2670) 

patXor 

“Graphics  Transfer  Modes” 

(IV-2670) 

pauseCmd 

“Sound  Commands” 

(IV-2691) 

' payt ' 

atom  'payt' 

(IV-2571) 
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ImageCodecStanda 

ImageCodecStanda 


pdActi onActi vateSubPanel 

function  ImageCodecStanda 
pdActi onConductStopAl  er 

function  QTStanda 
pdActi onConductStopAl  ert 

function  ImageCodecStanda 
pdActi onConfi rmDi al og 

f uncti on 
pdActi onGetDi al ogVal ues 
f uncti on 
pdActi onGetSubPanel  Menu 
f uncti on 

pdActi onSetAppl  eMenu 

f uncti on 
pdActi onSetCol orPi  ckerEventProc 

function  ImageCodecStanda 
pdActi onSetDi al ogTi tl e 
f uncti on 

pdActi onSetEdi tMenu 

f uncti on 
pdActi onSetPrevi ewPi cture 

function  ImageCodecStanda 
pdActi  onSetPrevi  ewllserltem 

function  ImageCodecStanda 

' pdat ' 

pdOpti onsAl 1 owOpti onal Interpol ati ons 

function  ImageCodecCrea 
pdOpti ons Col  1 ectOneVal  ue 

function  ImageCodecCrea 
perspecti veMatrixType 
pixel  sLocked 
pi xel  sPurgeabl  e 
pixPurge 
'  pmax' 

' pnot ' 

prel oadAl ways 
preloadOnlylfEnabled 
prog  res sOpAddMovi eSel ecti on 
progressOpCopy 
progressOpCut 
p r ogress Op Expo rtMovi  e 
progressOpFl  atten 
progressOpImportMovi  e 
progressOpInsertMovi eSegment 
progressOpInsertT  rackSegment 
prog ressOpLoadMedialnto Ram 
progressOpLoadMovielntoRam 
progressOpLoadTracklntoRam 


rdParameterDi al ogDoActi on  (11-740) 


rdParameterDi al ogDoActi 
rdParameterDi al ogDoActi 
ImageCodecStandardParameterDi al  ogDoActi 
ImageCodecStandardParameterDi al ogDoActi 
ImageCodecStanda 
ImageCodecStanda 


rdParameterDi al ogDoActi 
rdParameterDi al ogDoActi 


rdParameterDi al ogDoActi 
rdParameterDi al ogDoActi 
rdParameterDi al ogDoActi 
rdParameterDi al ogDoActi 


on  (11-1313) 


on  (li¬ 
on  (II- 


740) 


740) 


on  (11-740) 


on  (li¬ 
on  (II- 


740) 


740) 


on  (11-740) 


on  (li¬ 
on  (II- 


740) 


740) 


on  (11-740) 


rdParameterDi al ogDoActi on  (11-740) 
atom  'pdat'  ( IV-2572) 

teSta nda rdParameterDi al og  (11-692) 


fun 

fun 

ca 

ca 

ca 

ca 

ca 

ca 

ca 

ca 

ca 

ca 

ca 


teStandardParameterDi al og  (II 
function  GetMatrixType  (I 
function  NewImageGWorl d  (II 
function  NewImageGWorl d 
function  NewImageGWorl d 
atom  'pmax' 
atom  'pnot' 
ction  GetTrackLoadSetti ngs  (I 
ction  GetTrackLoadSetti ngs  (I 
llback  MovieProgressProc  (III 
llback  MovieProgressProc 
llback  MovieProgressProc 
llback  MovieProgressProc 
llback  MovieProgressProc 
llback  MovieProgressProc 
llback  MovieProgressProc 
llback  MovieProgressProc 
llback  MovieProgressProc 
llback  MovieProgressProc 
llback  MovieProgressProc 


(II 

(II 

(IV 

(IV 


(III 

(III 

(III 

(III 

(III 

(III 

(III 

(III 

(III 

(III 


-692) 

-419) 

-1066) 

-1066) 

-1066) 

-2572) 

-2573) 

-532) 

-532) 

-2105) 

-2105) 

-2105) 

-2105) 

-2105) 

-2105) 

-2105) 

-2105) 

-2105) 

-2105) 

-2105) 
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progressOpPaste 

callback  Movi eProgressProc 

( 1 1 1 -2105 ) 

p rog res sP roc Aborted 

“Error 

Codes” 

( I V  -  2  6  6  3  ) 

PropertyAtomAID 

“Atom  ID 

Codes” 

(IV-2649) 

proper tyNotSupported By NodeErr 

“Error 

Codes” 

( I V  -  2  6  6  3  ) 

' qdrg ' 

atom 

'qdrg' 

(IV-2574) 

qfcbNotCreatedErr 

“Error 

Codes” 

(IV-2663) 

qfcbNotFoundErr 

“Error 

Codes” 

(IV-2663) 

qtActi onNotHandledErr 

“Error 

Codes” 

(IV-2663) 

qtcbNeedsRateChanges 

struct  QTCall BackHeader 

(IV-2349) 

qtcbNeedsStartStopChanges 

struct  QTCal 1 BackHeader 

(IV-2349) 

qtcbNeedsTimeChanges 

struct  QTCal 1 BackHeader 

(IV-2349) 

qtml Dll  Entry NotFoundErr 

atom 

'wtxt ' 

(IV-2616) 

qtml D1 1 LoadErr 

atom 

'wtxt ' 

(IV-2616) 

qtml Uni ni ti al i zed 

“Error 

Codes” 

(IV-2663) 

qtNetworkAl readyAl locatedErr 

“Error 

Codes” 

(IV-2663) 

qtParamErr 

atom 

'wtxt ' 

(IV-2616) 

qtvrLi braryLoadErr 

“Error 

Codes” 

(IV-2663) 

qtvrUni ni ti al i zed 

“Error 

Codes” 

(IV-2663) 

quickTimelmageFileColorSyncProfil eAtom 

“Atom  ID 

Codes” 

(IV-2649) 

qui ckTi melmageFi 1  el mage Data Atom 

“Atom  ID 

Codes” 

(IV-2649) 

qui ckTi melmageFi 1 elmageDescri pti on Atom 

“Atom  ID 

Codes” 

(IV-2649) 

qui ckTi melmageFi 1 eMeta Data Atom 

“Atom  ID 

Codes” 

(IV-2649) 

qui etCmd 

“Sound  Commands” 

(IV-2691) 

rAl i asType 

atom 

'wtxt ' 

(IV-2616) 

ramlni  t 

struct  GDevice 

( I V - 2264 ) 

ratell025hz 

“Sound  Sample 

Rates” 

(IV-2695) 

ratellkhz 

“Sound  Sample 

Rates” 

(IV-2695) 

ratel6khz 

“Sound  Sample 

Rates” 

(IV-2695) 

rate22050hz 

“Sound  Sample 

Rates” 

(IV-2695) 

rate22khz 

“Sound  Sample 

Rates” 

(IV-2695) 

rate32khz 

“Sound  Sample 

Rates” 

(IV-2695) 

rate44khz 

“Sound  Sample 

Rates” 

(IV-2695) 

rate48khz 

“Sound  Sample 

Rates” 

(IV-2695) 

rate8khz 

“Sound  Sample 

Rates” 

(IV-2695) 

rateMul ti pi i erCmd 

“Sound  Commands” 

(IV-2691) 

'raw  '  function 

SGGet Sound  Input Parameters 

( I I I - 1733 ) 

' rdrf ' 

atom 

'  rdrf ' 

(IV-2575) 

real  1 ocPi x 

function  NewImageGWorl d 

(11-1066) 

redCol or 

“Color  Constants” 

( I V  -  2  6  5  7  ) 

ReferenceMovieAlternateGroupAID 

“Atom  ID 

Codes” 

(IV-2649) 

ReferenceMovi eComponentCheckAID 

“Atom  ID 

Codes” 

(IV-2649) 

ReferenceMovieCPURatingAID 

“Atom  ID 

Codes” 

(IV-2649) 

ReferenceMovi eDataRateAID 

“Atom  ID 

Codes” 

(IV-2649) 

ReferenceMovi eData Ref AID 

“Atom  ID 

Codes” 

(IV-2649) 

ReferenceMovi eDescri ptor AID 

“Atom  ID 

Codes” 

(IV-2649) 

ReferenceMovi e La nguageA ID 

“Atom  ID 

Codes” 

(IV-2649) 

ReferenceMovi eQuali tyAID 

“Atom  ID 

Codes” 

(IV-2649) 

ReferenceMovi eRecordAID 

“Atom  ID 

Codes” 

(IV-2649) 

ReferenceMovi eVersionCheckAID 

“Atom  ID 

Codes” 

(IV-2649) 
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regi sterCmpGl obal 
regi sterCmpNoDupl i cates 
regi sterCompAfter 
relni tCmd 
REQUIRED„TEXT 
' reso ' 

ResourceDataHandlerSubType 

resumeCmd 

resumeFl ag 

rgbComponentln 

RgnCl ipAID 

'  rl  e  ' 

' rmcd ' 

' rmcs ' 

' rmda ' 

' rmdr ' 

' rml a ' 

' rmqu ' 

' rmra ' 

' rmvc ' 

' rpza ' 

sampl edSynth 

sampl  esAl  readylnMedi a  Err 
Sampl eTabl eAID 
seal eMatri xType 
scaleTranslateMatrixType 
scAl 1 owZeroFrameRate 
scAl 1 owZeroKeyFrameRate 
scCodecFl agsType 
scCol orTabl eType 
scDataRateSetti ngsType 
sc Extend edProcsType 
schedul edSoundCmd 
scLi stEveryCodec 
scPreferCroppi ng 
scP reference FI agsType 
scPreferScal i ng 
scPreferScal i ngAndCroppi ng 
scProgressProcType 
' sept ' 

screenActi ve 
screenDevi ce 
scSequencelDType 
scSetti ngsStateType 
scShowBestDepth 
scSoundChannelCountType 
scSoundCompressi onType 
scSoundSampl eRateType 
scSound Sampl eSi zeType 


function  Regi sterComponent  (III- 1451 ) 
function  Regi sterComponent  (III- 1451 ) 
function  Regi sterComponent  (III- 1451 ) 
“Sound  Commands”  (IV-2691) 
function  CreateShortcutMovi eFi 1 e  (1-149) 
atom  'reso'  (IV-2576) 
“Component  Identifiers”  (IV-2657) 
“Sound  Commands”  (IV-2691) 
struct  EventRecord  (IV - 2246 ) 
function  VDGetlnputFormat  (III -2005 ) 
“Atom  ID  Codes”  (IV-2649) 
function  SGGetVideoCompressorType  ( 1 1 1  - 1 7  44 ) 

atom  'rmcd'  (IV-2576) 
atom  'rmcs'  (IV-2577) 
atom  'rmda'  (IV-2577) 
atom  'rmdr'  (IV-2578) 
atom  ' rml a '  (IV-2579) 
atom  'rmqu'  (IV-2579) 
atom  'rmra'  (IV-2580) 
atom  'rmvc'  (IV-2581) 
function  SGGetVideoCompressorType  ( 1 1 1  - 1 7  44 ) 
function  SndNewChannel  (III- 1839 ) 
“Error  Codes”  (IV-2663) 
“Atom  ID  Codes”  (IV-2649) 
function  GetMatrixType  (1-419) 
function  GetMatrixType  (1-419) 
f uncti on  SCGet Inf o  (  1 1 1 -1545 ) 
function  SCGet Inf o  (  1 1 1 -1545 ) 
f uncti on  SCGet Inf o  (  1 1 1 -1545 ) 
f uncti on  SCGet Info  (  1 1 1 -1545 ) 
function  SCGet Info  (  1 1 1 -1545 ) 
f uncti on  SCGet Info  (  1 1 1 -1545 ) 
“Sound  Commands”  (IV-2691) 
f uncti on  SCGet Inf o  (  1 1 1 -1545 ) 
function  SCSetTestlmagePi ct Fi 1 e  (  1 1 1 -1564) 
function  SCGet Info  (  1 1 1 -1545 ) 
function  SCSetTestlmagePi ctFi 1 e  (  1 1 1 -1564) 
function  SCSetTestlmagePi ctFi 1 e  (  1 1 1 -1564) 
f uncti on  SCGet Inf o  (  1 1 1 -1545 ) 
atom  'sept'  (IV-2581) 
struct  GDevice  (IV-2264) 
struct  GDevice  (IV-2264) 
function  SCGet Info  (  1 1 1 -1545 ) 
f uncti on  SCGet Info  (  1 1 1 -1545 ) 
function  SCGet Inf o  (  1 1 1 -1545 ) 
callback  Movi eExportGetPropertyProc  (III -2102 ) 
callback  Movi eExportGetPropertyProc  (III -2102 ) 
callback  Movi eExportGetPropertyProc  (III -2102 ) 
callback  Movi eExportGetPropertyProc  (III -2102 ) 
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scSpatialSettingsType 
scTemporal SettingsType 
scTypeNotFoundErr 
scUseMovabl eModal 
scWindowPositionType 
'  sdp  ' 

' sean ' 
secamln 
' seco ' 

selectorNotSupportedByNodeErr 
' Sel 0 ' 

seqGrabAppendToFi 1 e 
SeqGrabChannelType 
SeqGrabComponentType 
SeqGrabCompressi onPanelType 
seqGrabDontAddMovi e Resource 
seqGrabDontMakeMovi e 
seqGrabDontUseTempMemory 
seqGrabHasBounds 
seqGrabHasDiscreteSamples 
seqGrabHasVol ume 
SeqGrabPanel Type 
seqGrabPause 
seqGrabPauseForMenu 
seqGrabPl ay During Record 
seqGrabPrevi ew 
seqGrabRecord 

seqGrabSettingsPrevi ewOnly 

SeqGrabSourcePanelType 

seqGrabToDi sk 

seqGrabToMemory 

seqGrabUnpause 

seqGrabWri te Append 

seqGrabWri te  F ill 

seqGrabWri te Re serve 

settingNotSupportedByNodeErr 

sf ItemBal 1 oonHel p 

sf ItemCancel Button 

sfltemDesktopButton 

sfltemDividerLinePict 

sf ItemEjectButton 

sf ItemFi 1 eLi stUser 

sf ItemFi 1 eNameTextEdi t 

sfltemNewFolderUser 

sf ItemOpenButton 

sfltemPopUpMenuUser 

sf ItemPromptStati cText 

sf ItemVol umeUser 


function  SCGetlnfo  (III -1545 ) 
function  SCGetlnfo  (III -1545 ) 
“Error  Codes”  (IV-2663) 
function  SCGetlnfo  ( 1 1 1 - 1 545 ) 
function  SCGetlnfo  (  1 1  1 - 1 545 ) 
atom  'sdp  '  (IV- 2582 ) 
atom  'sean'  (IV-2582) 
function  VDGetVBl ankRect  (III-2021) 
atom  'wtxt'  (IV-2616) 
“Error  Codes”  (IV-2663) 
atom  'Sel O'  (IV-2582) 
function  SGGetDataOutput  (III-1711) 
“Component  Identifiers”  (IV-2657) 
“Component  Identifiers”  (IV-2657) 
“Component  Identifiers”  (IV-2657) 
function  SGGetDataOutput  (III-1711) 
function  SGGetDataOutput  (III-1711) 
function  SGGetDataOutput  (III-1711) 
function  SGGetChannel Info  (III -1702 ) 
function  SGGetChannel Info  (III -1702 ) 
function  SGGetChannel Info  (III -1702 ) 
“Component  Identifiers”  (IV-2657) 
function  SGGetPause  (III -1730 ) 
function  SGGetPause  (III -1730 ) 
function  SGGetChannel Usage  (III -1709 ) 
function  SGGetChannel Usage  (III -1709 ) 
function  SGGetChannel Usage  (III -1709 ) 
function  SGSettingsDialog  (1 11-1808) 
“Component  Identifiers”  (IV-2657) 
function  SGGetDataOutput  (III-1711) 
function  SGGetDataOutput  (III-1711) 
function  SGGetPause  (III -1730 ) 
function  SGAddExtendedMovi eData  (III -1678 ) 
function  SGAddExtendedMovi eData  (III -1678 ) 
function  SGAddExtendedMovi eData  (III -1678 ) 
“Error  Codes”  (IV-2663) 
callback  DlgHookProc  (III -2079 ) 
callback  DlgHookProc  (III -2079 ) 
callback  DlgHookProc  (III -2079 ) 
callback  DlgHookProc  (III -2079 ) 
callback  DlgHookProc  (III -2079 ) 
callback  DlgHookProc  (III -2079 ) 
callback  DlgHookProc  (III -2079 ) 
callback  DlgHookProc  (III -2079 ) 
callback  DlgHookProc  (III -2079 ) 
callback  DlgHookProc  (III -2079 ) 
callback  DlgHookProc  (III -2079 ) 
callback  DlgHookProc  (III -2079 ) 


sgDevi ceLi stDontCheckAvai lability 
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sgDevI ceLi stWi thlcons 
sgDevi ceNameFl a g Devi ceUnavai 1 abl e 
sgFlagControl  led  Grab 
shi ft Key 

ShowFi 1 ePrevi ewComponentType 
showUserSetti ngsDi al og 


si gAdobePremi ere 
si gAfterDark 
si g Al dusSuper3D 
si gAutoCAD 
si gCl i p3D 
si gCol orMacCheese 
si gCri cketDraw 
si gCri cketGraph 
si gDel tagraphPro 
si gDesi gn2 
si gDesi gnCAD 
si gDesi gnStudi o 
si g  Di gDarkroom 
si gDreams 

si gDynaperspecti  ve 


f uncti on  SGGetChannel Devi ceLi st  ( 1 1 1  -1701 ) 
f uncti on  SGGetChannel Devi ceLi st  ( 1 1 1  -1701 ) 
struct  SGDeviceName  (IV- 2434 ) 
function  SGGet FI ags  (III-1718) 
function  QTVRMouseDown  (11-1391) 
“Component  Identifiers”  (IV-2657) 
function  ConvertFi 1 eToMovieFi 1 e  (1-129) 


si  Acti veChannel s 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si  Acti veLevel s 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si  AGCOnOf f 

“Sound 

Informati on 

Sel ectors" 

(IV-2693) 

si Async 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si AVDi spl ayBehavi or 

“Sound 

Informati on 

Sel ectors" 

(IV-2693) 

si BestQual i ty 

f uncti on 

SndRecord 

(III - 1843 ) 

si BetterQual i ty 

f uncti on 

SndRecord 

(III - 1843 ) 

si  Channel Avai 1 abl e 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si Compressi onAvai  1  abl  e 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si Compressi onChannels 

“Sound 

Informati on 

Sel ectors" 

(IV-2693) 

si Compressi on  Fact or 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si Compressi onHeader 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si Compressi onNames 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si Compressi on  Pa  rams 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si Compressi onSampl eRate 

“Sound 

Informati on 

Sel ectors" 

(IV-2693) 

si Compressi onType 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si  Conti nuous 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si  Decomp res  si  on  Pa  rams 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si  Devi ceBuffer Info 

“Sound 

Informati on 

Sel ectors" 

(IV-2693) 

si  Devi ceConnected 

“Sound 

Informati on 

Sel ectors" 

(IV-2693) 

si  Devi celcon 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si  Devi ceName 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si EQSpectrumBands 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si EQSpectrumLevel s 

“Sound 

Informati on 

Sel ectors" 

(IV-2693) 

si EQSpectrumOnOf f 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si EQToneControl Gain 

“Sound 

Informati on 

Sel ectors" 

(IV-2693) 

si EQToneControl OnOff 

“Sound 

Informati on 

Sel ectors" 

(IV-2693) 

‘File  Types 
‘File  Types 
‘File  Types 
‘File  Types 
‘File  Types 
‘File  Types 
‘File  Types 
‘File  Types 
‘File  Types 
‘File  Types 
‘File  Types 
‘File  Types 
‘File  Types 
‘File  Types 


and  Creators' 
and  Creators’ 
and  Creators' 
and  Creators’ 
and  Creators’ 
and  Creators’ 
and  Creators’ 
and  Creators' 
and  Creators’ 
and  Creators' 
and  Creators’ 
and  Creators’ 
and  Creators’ 
and  Creators’ 


‘File  Types  and  Creators” 


(IV 

(IV 

(IV 

(IV 

(IV 

(IV 

(IV 

(IV 

(IV 

(IV 

(IV 

(IV 

(IV 

(IV 

(IV 


■2668) 

■2668) 

■2668) 

■2668) 

■2668) 

■2668) 

■2668) 

■2668) 

■2668) 

■2668) 

■2668) 

■2668) 

■2668) 

■2668) 

■2668) 
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si gGeneri cCADD 

si gGraphMaster 

si glmageStudi o 

si glnf i ni D 

si gKal ei daGraph 

si  g Ki dPi x 

sigLabVIEW 

si gMacDraft 

si gMacDraw 

si gMacFl ow 

si gMacSpi n 

si gMi ni Cad 

si gModel Shop 

si gMovi ePl ayer 

si gMovi eRecorder 

si gOasi s 

sigOBJECTMASTER 

si gOfoto 

si gOmni s5 

si GoodQual i ty 

si gOpti x 

si gPhotoMac 

si gPi ctu reCompressor 

si gPICTVi ewer 

si gPi xel Pai nt 

si gScreenPl ay 

si gSmoothi e 

si gStudi ol 

si gStudi o32 

si gStudi 08 

si gSwi vel 3D 

si gVersaCad 

si HardwareBal ance 

si HardwareBal anceSteps 

si HardwareBass 

si HardwareBassSteps 

si HardwareBusy 

si HardwareFormat 

si HardwareMute 

si HardwareT  rebl e 

si HardwareT  rebleSteps 

si HardwareVol ume 

si HardwareVol umeSteps 

si HeadphoneMute 

si HeadphoneVol ume 

siHeadphoneVol umeSteps 

si InputAvai 1 abl e 

si InputGai n 

si InputSource 


"File  Types  and  Creators”  (IV- 2668 ) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

function  SndRecord  (III - 1843 ) 
"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

"File  Types  and  Creators”  (IV-2668) 

“Sound  Information  Selectors”  (IV-2693) 
“Sound  Information  Selectors”  (IV-2693) 
“Sound  Information  Selectors”  (IV-2693) 
“Sound  Information  Selectors”  (IV-2693) 
“Sound  Information  Selectors”  (IV-2693) 
“Sound  Information  Selectors”  (IV-2693) 
“Sound  Information  Selectors”  (IV-2693) 
“Sound  Information  Selectors”  (IV-2693) 
“Sound  Information  Selectors”  (IV-2693) 
“Sound  Information  Selectors”  (IV-2693) 
“Sound  Information  Selectors”  (IV-2693) 
“Sound  Information  Selectors”  (IV-2693) 
“Sound  Information  Selectors”  (IV-2693) 
“Sound  Information  Selectors”  (IV-2693) 
“Sound  Information  Selectors”  (IV-2693) 
“Sound  Information  Selectors”  (IV-2693) 
“Sound  Information  Selectors”  (IV-2693) 
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si InputSourceNames 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si  Level MeterOnOf f 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

siModemGain 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si Moni torAvai 1 abl e 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si Moni torSource 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si  NumberChannel s 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si  Opti onsDi al og 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si  OSTypelnputAvai 1 abl e 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

siOSTypelnputSource 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si  PI ayThruOnOf f 

“Sound 

Informati on 

Sel ectors" 

(IV-2693) 

si PostMi xer Sound Component 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si PreMi xer Sound Component 

“Sound 

Informati on 

Sel ectors" 

(IV-2693) 

si Qual i ty 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si RateMul ti pi i er 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si ReadPermi ssi on 

function  SPBOpenDevi ce 

(II 1-1876) 

si Recordi ngQual i ty 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si Sampl eRate 

“Sound 

Informati on 

Sel ectors" 

(IV-2693) 

si Sampl eRateAvai 1 abl e 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si Sampl eSi ze 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si  Sampl  eSi zeAvai 1 abl e 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si  SetupCDAudi o 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si  SetupModemAudi o 

“Sound 

Informati on 

Sel ectors" 

(IV-2693) 

si  SI opeAnd Intercept 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si SoundCl ock 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si SpeakerMute 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si SpeakerVol ume 

“Sound 

Informati on 

Sel ectors" 

(IV-2693) 

siSSpCPULoadLimit 

“Sound 

Informati on 

Sel ectors" 

(IV-2693) 

si SSpLocal i zati on 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si SSpSpeakerSetup 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si  StereoInputGai n 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si SubwooferMute 

“Sound 

Informati on 

Sel ectors" 

(IV-2693) 

siTwosCompl ementOnOff 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

siUseThisSoundClock 

“Sound 

Informati on 

Sel ectors" 

(IV-2693) 

si Vol ume 

“Sound 

Informati on 

Sel ectors" 

(IV-2693) 

si VoxRecordlnfo 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si VoxStopInfo 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si Wi deStereo 

“Sound 

Informati on 

Sel ectors” 

(IV-2693) 

si Wri tePermi ssi on 

function  SPBOpenDevi ce 

(II 1-1876) 

sixToOne 

struct  CmpSoundHeader 

( IV-2176) 

sixToOne Packet Size 

struct  CmpSoundHeader 

( IV-2176) 

'skip' 

atom  'skip' 

(IV-2583) 

Ski pAtomType 

“Atom  ID  Codes” 

( I V  -  2 64 9 ) 

smArabi c 

"Localization  Codes” 

(IV-2673) 

smArmeni an 

"Localization  Codes” 

(IV-2673) 

smBengal i 

“Localization  Codes” 

(IV-2673) 

smBurmese 

"Localization  Codes” 

(IV-2673) 

'  smc  ' 

function  SGGetVi deoCompressorType 

(II 1-1744) 

smCentral EuroRoman 

atom  'wtxt' 

(IV-2616) 

smCurrentScri pt 

f uncti on  FI attenMovi eData  (1-374) 
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smCy ri  111c 

smDevanagari 

smEthi opi c 

smExtArabi c 

smGeez 

smGeorgi an 

smGreek 

smGujarati 

smGurmukhi 

' smhd ' 

smHebrew 

smJapanese 

smKannada 

smKhmer 

smKorean 

smLao 

smMal ayal am 
smMongol 1  an 
smOriya 
smRoman 
smRSymbol 
smSi mpChi nese 
smSi nhal ese 
smSystemScri pt 
smTami 1 
smTel ugu 
smThal 
smT i betan 
smT  radChi nese 
smllni  codeScri  pt 
smllni  nterp 
smVi etnamese 
soundCmd 

Sound LocalizationAID 

SoundMedialnfoHeaderAID 

SoundMedi aType  function 

soundSupport Not Aval  1 abl eErr 

sourceNotFoundErr 

spriteHitTestBounds 

spriteHitTestlmage 

spriteHitTestlnvisIbleSprites 

spriteHitTestlsCUck 

spriteHitTestLocInDi splay Coordinates 

Spri teMedi aType 

' sprt ' 

' sptl  ' 

squareWaveSynth 
srcBi c 
srcBi c , 


"Local i zati on 

Codes” 

(IV-2673) 

"Local i zati on 

Codes” 

(IV-2673) 

"Local i zati on 

Codes” 

(IV-2673) 

“Local i zati on 

Codes” 

(IV-2673) 

"Local i zati on 

Codes” 

(IV-2673) 

"Local i zati on 

Codes” 

(IV-2673) 

"Local i zati on 

Codes” 

(IV-2673) 

"Local i zati on 

Codes” 

(IV-2673) 

“Local i zati on 

Codes” 

(IV-2673) 

atom 

'  smhd ' 

(IV-2584) 

“Local i zati on 

Codes” 

(IV-2673) 

"Local i zati on 

Codes” 

(IV-2673) 

"Local i zati on 

Codes” 

(IV-2673) 

"Local i zati on 

Codes” 

(IV-2673) 

"Local i zati on 

Codes” 

(IV-2673) 

“Local i zati on 

Codes” 

(IV-2673) 

"Local i zati on 

Codes” 

(IV-2673) 

"Local i zati on 

Codes” 

(IV-2673) 

"Local i zati on 

Codes” 

(IV-2673) 

"Local i zati on 

Codes” 

(IV-2673) 

atom 

'wtxt ' 

(IV-2616) 

"Local i zati on 

Codes” 

(IV-2673) 

“Local i zati on 

Codes” 

(IV-2673) 

function  FI attenMovi eData 

(1-374) 

"Local i zati on 

Codes” 

(IV-2673) 

"Local i zati on 

Codes” 

(IV-2673) 

"Local i zati on 

Codes” 

(IV-2673) 

“Local i zati on 

Codes” 

(IV-2673) 

"Local i zati on 

Codes” 

(IV-2673) 

"Local i zati on 

Codes” 

(IV-2673) 

"Local i zati on 

Codes” 

(IV-2673) 

"Local i zati on 

Codes” 

(IV-2673) 

"Sound  Commands” 

(IV-2691) 

"Atom  ID 

Codes” 

(IV-2649) 

"Atom  ID 

Codes” 

(IV-2649) 

GetMediaHandlerDescription 

(1-432) 

"Error 

Codes” 

(IV-2663) 

"Error 

Codes” 

(IV-2663) 

function  Spri  teHi  tTest  (III- 1885 ) 
function  Spri  teHi  tTest  (III- 1885 ) 
function  Spri  teHi tTest  (III - 1885 ) 
function  Spri  teHi tTest  (III- 1885 ) 
function  Spri  teHi tTest  (III- 1885 ) 
“Component  Identifiers”  (IV-2657) 
atom  'sprt'  (IV-2584) 
atom  ' sptl  '  ( IV-2586 ) 
function  SndNewChannel  (III - 1839 ) 
struct  CGrafPort  (IV-2168) 
atom  'wtxt'  (IV-2616) 
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srcCopy 

“Graphics  Transfer 

Modes" 

(IV-2670) 

srcCopy , 

atom 

'wtxt' 

(IV-2616) 

srcOr 

struct  CGrafPort 

(IV-2168) 

srcOr, 

atom 

'wtxt ' 

(IV-2616) 

srcXor 

struct  CGrafPort 

(IV-2168) 

srcXor, 

atom 

'wtxt' 

(IV-2616) 

'ssrc' 

atom 

'ssrc' 

(IV-2586) 

stal eEdi tState 

“Error 

Codes” 

(IV-2663) 

StandardCompressi onSubType 

“Component  Identifiers” 

(IV-2657) 

StandardCompressi onSubTypeSound 

“Component  Identifiers” 

(IV-2657) 

StandardCompressi onType 

“Component  Identifiers” 

(IV-2657) 

stateBl ockSi ze 

struct  StateBlock 

( I V - 2463 ) 

' stbl  ' 

atom 

' stbl ' 

( I V  -  2 58 7  ) 

STChunkOf f set64AID 

“Atom  ID 

Codes” 

( I V  -  2  64  9 ) 

STChunkOffsetAID 

“Atom  ID 

Codes” 

( I V  -  2  64  9 ) 

' stco ' 

atom 

' stco ' 

( I V  -  2  589 ) 

stdSH 

struct  CmpSoundHeader 

( IV-2176) 

'STR  ' 

struct  ResourceSpec 

(IV-2402) 

streami ngNodeNot Ready Err 

“Error 

Codes” 

(IV-2663) 

stretchPi x 

function  NewImageGWorl d 

(11-1066) 

' strt ' 

atom 

'  strt ' 

( I V  -  2 589 ) 

STSampl eDescAID 

“Atom  ID 

Codes” 

( I V  -  2  64  9 ) 

STSampl elDAID 

“Atom  ID 

Codes” 

( I V  -  2  64  9 ) 

STSampl eSi zeAID 

“Atom  ID 

Codes” 

( I V  -  2  64  9 ) 

STSampl eToChunkA ID 

“Atom  ID 

Codes" 

( I V  -  2  64  9 ) 

' stsc ' 

atom 

' stsc ' 

(IV-2590) 

' stsd ' 

atom 

' stsd ' 

( I V  -  2  5  9 1  ) 

' stsh ' 

atom 

' stsh ' 

(IV-2592) 

STShadowSyncAID 

“Atom  ID 

Codes” 

( I V  -  2  64  9 ) 

' stss ' 

atom 

' stss ' 

(IV-2593) 

STSyncSampl eAID 

“Atom  ID 

Codes” 

( I V  -  2  64  9 ) 

' stsz ' 

atom 

' stsz ' 

(IV-2594) 

STTimeToSampAID 

“Atom  ID 

Codes” 

( I V  -  2  64  9 ) 

' stts ' 

atom 

' stts ' 

(IV-2595) 

subOver 
subPi n 

suppressDi ther 
s us  pend  Res umeMes sage 
sVi deoln 
'  sync ' 
syncCmd 

synthes i ze rNot Respond  i  ngOSErr 
synthesi zerOSErr 
sysBeepDi sable 
sysBeepEnabl e 
systemMi crosecondCl  ock 
systemMi 1 1 i secondCl  ock 
systemSecondCl  ock 
systemT i ckCl  ock 


function  SetDSequenceTransferMode  (III 
function  SetDSequenceTransferMode  (III 
function  DrawTrimmedPi cture  (I 
struct  EventRecord  (IV 
function  VDGetlnputFormat  (III 
atom  'sync 
“Sound  Commands 
“Error  Codes 
“Error  Codes 
function  SndGetSysBeepState 
function  SndGetSysBeepState 
“Component  Identifiers 


“Component  Identifiers' 
“Component  Identifiers' 
“Component  Identifiers' 


(IV 

(IV 

(IV 

(IV 

(III 

(III 

(IV 

(IV 

(IV 

(IV 


1591) 

1591) 

311) 

2246) 

2005) 

2596) 

2691) 

2663) 

2663) 

1833) 

1833) 

2657) 

2657) 

2657) 

2657) 
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' tbox ' 

atom  'tbox' 

(IV-2597) 

tc24HourMax 

struct  TimeCodeDef 

(IV-2482) 

tcCounter 

struct  TimeCodeDef 

(IV-2482) 

tcdfShowT i meCode 

function  TCGetTimeCodeFl ags  (III -1921 ) 

tcDropFrame 

struct  TimeCodeDef 

(IV-2482) 

' tcmi ' 

atom  ' tcmi ' 

(IV-2597) 

tcNegT i mesOK 

struct  TimeCodeDef 

(IV-2482) 

tctNegFl ag 

struct  TimeCodeTime 

(IV-2485) 

teCenter 

function  SGSetJusti f i cati on  (III-1795) 

teFl  ushDefaul  t 

function  SGSetJustifi cation  (III-1795) 

teFl ushLeft 

function  SGSetJustifi cation  (III-1795) 

teFl  ushRi  ght 

function  SGSetJustifi cati on  (III-1795) 

TextMedi aType 

function  GetMedi aHandlerDescription 

(1-432) 

Three DeeMedi aType 

“Component  Identifiers” 

( I V  -  2  6  5  7  ) 

threeToOne 

struct  CmpSoundHeader 

(IV-2176) 

threeToOnePacketSize 

struct  CmpSoundHeader 

(IV-2176) 

'tick' 

atom  'wtxt' 

(IV-2616) 

ti meBaseAfterStopT i me 

function  GetTi meBaseStatus 

(1-519) 

timeBaseBeforeStartTime 

function  GetTi meBaseStatus 

(1-519) 

T i meCodeMedi aType 

“Component  Identifiers” 

( I V  -  2  6  5  7  ) 

ti meNotlnMedi a 

“Error  Codes” 

(IV-2663) 

ti meNotlnT rack 

“Error  Codes” 

(IV-2663) 

ti meNotlnVi ewErr 

“Error  Codes” 

(IV-2663) 

' tkhd ' 

atom  'tkhd' 

(IV-2598) 

' tmax ' 

atom  'tmax' 

(IV-2598) 

' tmcd ' 

atom  'tmcd' 

( I V  -  2  5  9  9  ) 

' tmi n ' 

atom  'tmin' 

( I V  -  2  5  9  9  ) 

'  tpyl  ' 

atom  '  tpyl  ' 

(IV-2600) 

T  rackAID 

“Atom  ID  Codes” 

(IV-2649) 

T  rackEnabl e 

struct  TrackHeader 

(IV-2489) 

T  rackHeaderAID 

“Atom  ID  Codes” 

(IV-2649) 

trackIDNotFound 

“Error  Codes” 

(IV-2663) 

T  racklnMovi e 

struct  TrackHeader 

(IV-2489) 

T  racklnPoster 

struct  TrackHeader 

(IV-2489) 

T  racklnPrevi ew 

struct  TrackHeader 

(IV-2489) 

trackNotlnMovi e 

“Error  Codes” 

(IV-2663) 

TrackReferenceAID 

“Atom  ID  Codes” 

(IV-2649) 

trackUsagelnMovi  e 

function  GetTrackUsage 

(1-545) 

trackUsagelnPoster 

function  GetTrackUsage 

(1-545) 

trackUsagelnPreview 

function  GetTrackUsage 

(1-545) 

' trak' 

atom  'trak' 

(IV-2600) 

translateMatrixType 

function  GetMatri xType 

(1-419) 

transparent 

function  SetDSequenceTransferMode  (III -1591 ) 

' tref ' 

atom  'tref' 

(IV-2602) 

tri ggerAtStart 

function  NewCallBack 

(11-1053) 

tri ggerAtStop 

function  NewCallBack 

(11-1053) 

tri ggerRateChange 

function  CallMeWhen 

(1-67) 

tri ggerRateEqual 

function  CallMeWhen 

(1-67) 

tri ggerRateGT 

function  CallMeWhen 

(1-67) 
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t rl  ggerRateGTE 
tri  ggerRateLT 
tri  ggerRateLTE 
tri ggerRateNotEqual 
tri ggerT i meBwd 
tri ggerT i meEi ther 
tri ggerT i meFwd 
'trpy ' 

tuneParseOSErr 
tune PI ayerFui 1 OSErr 
' twdt ' 

' twdu ' 

TweenMedi aType 
' twen ' 

' twnt ' 

' twos ' 

' twst ' 

■  ty' 

' udta ' 

unkeepInRam 

unknownFormatErr 

unsupportedAuxi 1 i ary  Import Data 

unsupportedOSErr 

unsupported  Process  or  Err 

unusedl 

updateEvt 

URLDataHandlerSubType 

urlDataHFTPBadNameListErr 

urlDataHFTPBadPasswordErr 

urlDataHFTPBadUserErr 

urlDataHFTPDataConnectionErr 

urlDataHFTPFilenameErr 

urlDataHFTPNeed Pass word  Err 

url DataHFTPNoDi rectoryErr 

urlDataHFTPNoNetDriverErr 

url DataHFTPNoPass word  Err 

url DataHFTPPermi ssi onsErr 

urlDataHFTPProtocolErr 

urlDataHFTPQuotaErr 

urlDataHFTPServerDisconnectedErr 

urlDataHFTPServerErr 

url DataHFTPShutdownErr 

url DataHFTPURLErr 

url DataHHTTPNoNetDri verErr 

url DataHHTTPProtocol Err 

url DataHHTTPRedi rectErr 

url DataHHTTPURLErr 

userCancel edErr  function  QTIs 

UserDataAID 


function  CallMeWhen  (1-67) 
function  CallMeWhen  (1-67) 
function  CallMeWhen  (1-67) 
function  CallMeWhen  (1-67) 
function  CallMeWhen  (1-67) 
function  CallMeWhen  (1-67) 


function  CallMeWhen  (1-67) 

atom 

'trpy' 

(IV-2603) 

“Error 

Codes” 

(IV-2663) 

“Error 

Codes” 

(IV-2663) 

atom 

' twdt ' 

(IV-2604) 

atom 

' twdu ' 

(IV-2604) 

“Component  Identifiers” 

(IV-2657) 

atom 

' twen ' 

( I V  -  2 60 5 ) 

atom 

' twnt ' 

( I V  -  2 60 5 ) 

struct  InstSampl eDescRec 

(IV-2296) 

atom 

' twst ' 

(IV-2606) 

atom 

'  ty' 

(IV-2606) 

atom 

' udta ' 

( I V  -  2 607 ) 

function  LoadMedi alntoRam 

(11-779) 

“Error 

Codes" 

(IV-2663) 

“Error 

Codes” 

(IV-2663) 

“Error 

Codes” 

(IV-2663) 

“Error 

Codes” 

(IV-2663) 

function  SPBRecord 

(III  - 1878 ) 

struct  EventRecord 

(IV-2246) 

“Component  Identifiers” 

(IV-2657) 

“Error 

Codes" 

(IV-2663) 

“Error 

Codes” 

(IV-2663) 

“Error 

Codes” 

(IV-2663) 

“Error 

Codes” 

(IV-2663) 

“Error 

Codes” 

(IV-2663) 

“Error 

Codes" 

(IV-2663) 

“Error 

Codes” 

(IV-2663) 

“Error 

Codes" 

(IV-2663) 

“Error 

Codes” 

(IV-2663) 

“Error 

Codes” 

(IV-2663) 

“Error 

Codes” 

(IV-2663) 

“Error 

Codes” 

(IV-2663) 

“Error 

Codes" 

(IV-2663) 

“Error 

Codes” 

(IV-2663) 

“Error 

Codes” 

(IV-2663) 

“Error 

Codes” 

(IV-2663) 

“Error 

Codes” 

(IV-2663) 

“Error 

Codes" 

(IV-2663) 

“Error 

Codes” 

(IV-2663) 

“Error 

Codes” 

(IV-2663) 

andardParameterDi al og Event 

(11-1186) 

“Atom  ID 

Codes” 

( I V  -  2 64 9 ) 
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userDataltemNotFound 

“Error 

Codes” 

(IV-2663) 

userLong 

function  SPBRecord 

( I 11-1878) 

useTempMem 

function  NewImageGWorl d 

(11-1066) 

variabl eCompressi on 

function  GetCompressi onlnfo  (1-398) 

vdTypeAl pha 

struct  Di gi ti zerlnfo 

(IV-2234) 

vdTypeBasi c 

struct  Di gi ti zerlnfo 

( I V - 2234 ) 

vdTypeKey 

struct  Di gi ti zerlnfo 

(IV-2234) 

vdTypeMask 

struct  Di gi ti zerlnfo 

(IV-2234) 

vdUseAny Fi el d 

function  VDGetFi el dPreference 

( I I I -2001 ) 

vdUseEvenFi el d 

function  VDGetFi el dPreference 

( I I I -2001 ) 

vdUseOddFi el d 

function  VDGetFi el dPreference 

( I I I -2001 ) 

verAf ri kaans 

"Local i zati on 

Codes” 

(IV-2673) 

verArabi c 

"Local i zati on 

Codes” 

(IV-2673) 

verArmeni  an 

"Local i zati on 

Codes” 

(IV-2673) 

verAustral  i  a 

"Local i zati on 

Codes” 

(IV-2673) 

verAustri a 

“Local i zati on 

Codes” 

(IV-2673) 

verBengal  i 

"Local i zati on 

Codes” 

(IV-2673) 

verBhutan 

"Local i zati on 

Codes” 

(IV-2673) 

verBrazi 1 

"Local i zati on 

Codes” 

(IV-2673) 

verBreton 

"Local i zati on 

Codes” 

(IV-2673) 

verBri tai n 

“Local i zati on 

Codes” 

(IV-2673) 

verBul gari a 

"Local i zati on 

Codes” 

(IV-2673) 

verByel oRussi an 

“Local i zati on 

Codes” 

(IV-2673) 

verCatal oni  a 

"Local i zati on 

Codes” 

(IV-2673) 

verChi na 

"Local i zati on 

Codes” 

(IV-2673) 

verCroati  a 

"Local i zati on 

Codes” 

(IV-2673) 

verCyprus 

"Local i zati on 

Codes” 

(IV-2673) 

verCzech 

“Local i zati on 

Codes” 

(IV-2673) 

verDenmark 

"Local i zati on 

Codes” 

(IV-2673) 

verEngCanada 

"Local i zati on 

Codes” 

(IV-2673) 

verEsperanto 

"Local i zati on 

Codes” 

(IV-2673) 

verEstoni a 

"Local i zati on 

Codes” 

(IV-2673) 

verFarEastGeneri c 

atom 

'wtxt ' 

(IV-2616) 

verFaroelsl 

"Local i zati on 

Codes” 

(IV-2673) 

verFi  nl  and 

“Local i zati on 

Codes” 

(IV-2673) 

verFl  emi  sh 

"Local i zati on 

Codes” 

(IV-2673) 

verFrance 

"Local i zati on 

Codes” 

(IV-2673) 

verFrBel gi urn 

"Local i zati on 

Codes” 

(IV-2673) 

verFrCanada 

"Local i zati on 

Codes” 

(IV-2673) 

verFrenchUni versal 

“Local i zati on 

Codes” 

(IV-2673) 

verFrSwi ss 

"Local i zati on 

Codes” 

(IV-2673) 

verGeorgi an 

"Local i zati on 

Codes” 

(IV-2673) 

verGermany 

"Local i zati on 

Codes” 

(IV-2673) 

verGreece 

atom 

'wtxt ' 

(IV-2616) 

verGreecePoly 

atom 

'wtxt ' 

(IV-2616) 

verGreenl and 

"Local i zati on 

Codes” 

(IV-2673) 

verGrSwi ss 

“Local i zati on 

Codes” 

(IV-2673) 

verGujarati 

"Local i zati on 

Codes” 

(IV-2673) 

verHungary 

"Local i zati on 

Codes” 

(IV-2673) 
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verlcel and 
verlndi a  H i ndi 
verlndi aUrdu 
verlnternati onal 
verl ran 
verl rel and 

verl ri shGael i cScri pt 

verlsrael 

verltal i anSwi ss 

verltaly 

verJapan 

verKorea 

verLatvi a 

verLi thuani a 

verMacedoni an 

verMagyar 

verMal ta 

verManxGael i c 

verMarathi 

verMul ti 1 i ngual 

verNepal 

verNetherl ands 

verNorway 

verNunavut 

verNynorsk 

verPaki stanUrdu 

verPol and 

verPortugal 

verPun jabi 

verRomani a 

verRussi a 

verSami 

verScotti shGael i c 
verScri ptGeneri  c 
verSerbi an 
verSi ngapore 
versi onCmd 
verSi ovak 
verSl oveni an 
verSpai n 

verSpLati nAmeri ca 

verSweden 

verTaiwan 

verThai 1  and 

verTi betan 

verTonga 

verTurkey 

verTurki shModi f i ed 
verUkrai ne 


Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
atom  'wtxt'  (IV-2616) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes"  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes"  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
atom  'wtxt'  (IV-2616) 
Localization  Codes"  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
atom  'wtxt'  (IV-2616) 
Localization  Codes"  (IV-2673) 
Localization  Codes”  (IV-2673) 
“Sound  Commands”  (IV-2691) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
atom  'wtxt'  (IV-2616) 
atom  'wtxt'  (IV-2616) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes"  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes”  (IV-2673) 
Localization  Codes"  (IV-2673) 
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verUS 
verUzbek 
verVi etnam 
verWel sh 
'vide' 

vi deoDi gi ti zerComponentType 
VideoMedialnfoHeaderAID 
Vi deoMedi aType 
videoOutputlnllseErr 
Visual MediaCharacteristic 
'vmhd' (media) 

' vmhd ' (transfer ) 
vol umeCmd 
'  vrcp' 

' vrni ' 

' vrnp' 

' vrsc ' 

wackBadFi 1 eErr 
wackBadMetaDataErr 
wackForkNotFoundErr 
wai tCmd 

waveTabl eSynth 
wf Fi 1 eNotFound 
whi teCol or 
'wide' 

Wi deAtomPl aceholderType 
Wi redActi onHandlerType 
' WLOC ' 

'wtxt ' 

yel 1 owCol or 

zl i bDataCompressorSubType 


“Localization  Codes”  (IV-2673) 
“Localization  Codes”  (IV-2673) 
“Localization  Codes”  (IV-2673) 
“Localization  Codes”  (IV-2673) 
atom  'vide'  (IV-2610) 
“Component  Identifiers”  (IV-2657) 
“Atom  ID  Codes”  (IV-2649) 
function  GetMedi aHandlerDescription  (1-432) 
“Error  Codes”  (IV-2663) 
function  GetMovi eNextlnteresti ngTi me  (1-480) 
atom  'vmhd' (media)  (IV-2611) 
atom  ' vmhd '( transfer )  (IV-2612) 
“Sound  Commands”  (IV-2691) 
atom  'vrcp'  (IV-2612) 
atom  '  vrni '  ( IV-2613) 
atom  'vrnp'  (IV-2614) 
atom  'vrsc'  (IV-2614) 
“Error  Codes”  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Error  Codes”  (IV-2663) 
“Sound  Commands”  (IV-2691) 
function  SndNewChannel  (III - 1839 ) 
“Error  Codes”  (IV-2663) 
“Color  Constants”  (IV-2657) 
atom  'wide'  (IV-2614) 
“Atom  ID  Codes”  (IV-2649) 
“Component  Identifiers”  (IV-2657) 
atom  'WLOC'  (IV-2615) 
atom  'wtxt'  (IV-2616) 
“Color  Constants”  (IV-2657) 
atom  'dcom'  (IV-2527) 


V-3004 


Inside  QuickTime:  Index  of  Constants 


Functions  By 


QuickTime  Header  Files 


Components . h 

I V-3005 

End i an  .  h 

I V -3007 

ImageCodec . h 

I V -3007 

ImageCompressi on . h 

I V -3009 

Medi aHandl ers . h 

I V -30 1 6 

Movi es .  h 

I V -30 1 7 

Movi esFormat .  h 

I V -3029 

QTML.h 

I V -3029 

QTSMovi e .  h 

I V -3030 

QTStreami ngComponents .  h 

I V -3030 

Qui  ckTi meComponents  .  h 

I V -3032 

Qui  ckTimeMusi c. h 

IV  304! 

Qui  ckTimeStreami ng  .  h 

I V -3044 

Qui  ckTimeVR. h 

I V -3046 

Qui  ckTi meVRFormat .  h 

I V -3048 

Sound . h 

I V -3048 

Components.h 

NewComponentFuncti onUPP  11-1056 
Di sposeComponentFuncti onUPP  1-258 
Regi sterComponent  1 1 1 - 145 1 
Regi sterComponent Resource  1 1 1-1453 
Unregi sterComponent  III-1979 
Fi ndNextComponent  1-360 
CountComponents  1-143 
GetComponentlnfo  1-389 
GetComponentLi stModSeed  1-391 
GetComponentTypeModSeed  1-395 
OpenAComponent  11-1126 
OpenComponent  11-1130 
Cl oseComponent  I  - 1 0 0 
GetComponentlnstanceError  1-390 
SetComponentlnstanceError  1 1 1-1571 
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File 
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Components.h 


GetComponentRefcon  1-394 

SetComponentRefcon  1 1 1-1573 

OpenComponentResFi 1 e  11-1130 

OpenAComponentResFi 1 e  11-1127 

Cl oseComponentResFi 1 e  I -101 

GetComponentResource  1-394 

GetComponentlndStri ng  1-388 

Resol veComponentAl i as  1 1 1-1462 

GetComponentPubl i cResource  1-392 

GetComponentPubl icResourceList  1-393 

Get Component InstanceStorage  1-391 

SetComponentlnstanceStorage  1 1 1-1572 

GetComponentInstanceA5  1-390 

SetComponentInstanceA5  1 1 1-1570 

CountComponentlnstances  1-142 

Cal  1 ComponentFuncti on  1-61 

Call ComponentFuncti onWithStorage  1-61 

Call ComponentFuncti onWithStorageProcInfo  1-62 

Del egateComponentCal 1  1-249 

SetDef aul tComponent  1 1 1 - 1 581 

OpenDefaul tComponent  11-1131 

OpenADefaul tComponent  11-1129 

CaptureComponent  1-74 

UncaptureComponent  III -1979 

Regi sterComponentResourceFi 1 e  1 1 1 -1455 

GetComponentlconSui te  1-387 

ComponentFuncti on  Imp 1 emented  I  -1 1 1 

GetComponentVersi on  1-395 

ComponentSetTarget  1-112 

Cal  1 ComponentOpen  1-65 

Cal  1 ComponentCl ose  1-59 

Cal  1 ComponentCanDo  1-58 

Cal  1 ComponentVersi on  1-67 

Cal  1 ComponentRegi ster  1-65 

Cal  1 ComponentTarget  1-66 

Cal  1 ComponentUnregi ster  1-66 

Call ComponentGetMPWorkFuncti on  1-63 

Call ComponentGetPubl i cResource  1-64 

Cal  1  Component  1-58 

Cal  1 ComponentDi spatch  1-59 

NewComponentMPWorkFuncti onUPP  11-1056 

NewComponentRouti neUPP  11-1057 

NewGetMi ssi ngComponentResourceUPP  11-1059 

Di sposeComponentMPWorkFuncti onUPP  1-258 

Di sposeComponentRouti neUPP  1-259 

DisposeGetMissi ngComponentResourceUPP  1-261 
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End i  anS16_BtoN  1-317 
End i  anS16_NtoB  1-319 
End i anS16_LtoN  1-318 
End i anS16_NtoL  1-320 
End i anS16_LtoB  1-318 
End i anS16_BtoL  1-317 
End i a  n  U 1 6_B t  oN  1-326 

End i a  n  U 1 6 _ N t  oB  1-327 

End i a  n  U 1 6_Lt oN  1-327 

End i a  n  U 1 6 _ N t  o  L  1-328 

End i a  n  U 1 6_Lt oB  1-326 
End i a  n  U 1 6_Bt  o  L  1-326 
End i anS32_BtoN  1-321 
End i anS32_NtoB  1-322 
End i anS32_LtoN  1-322 
End i  anS32_NtoL  1-323 
End i anS32_LtoB  1-321 
End i anS32_BtoL  1-321 
End i anU32_BtoN  1-329 

End i a  n  U3  2 _ N t  oB  1-331 

End i anU32_LtoN  1-330 
End i anU32_NtoL  1-332 
End i anU32_LtoB  1-330 
End i anU32_BtoL  1-329 
End i anS64_BtoN  1-324 
End i anS64_NtoB  1-325 
End i anS64_LtoN  1-324 
End i anS64_NtoL  1-325 
End i anS64_LtoB  1-324 
End i anS64_BtoL  1-323 
End i anU64_BtoN  1-333 
End i anU64_NtoB  1-334 
End i anU64_LtoN  1-334 
End i anU64_NtoL  1-334 
End i anU64_LtoB  1-333 
End i anU64_BtoL  1-332 
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NewImageCodecTi meTri ggerUPP  11-1065 
Di sposelmageCodecTi meTri ggerUPP  1-267 
NewImageCodecMPDrawBandUPP  11-1065 
DisposelmageCodecMPDrawBandUPP  1-266 
ImageCodecGetCodecInfo  11-710 
ImageCodecGetCompressi onTime  11-711 
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ImageCodecGetMaxCompressi onSize  11-714 
ImageCodecPreCompress  11-730 
ImageCodecBandCompress  11-688 
ImageCodecPreDecompress  11-731 
ImageCodecBandDecompress  11-689 
ImageCodecBusy  11-691 
ImageCodecGetCompressedlmageSi ze  11-710 
ImageCodecGetSi mi  1 ari ty  11-720 
ImageCodecTri mlmage  11-743 
ImageCodecRequestSettings  11-735 
ImageCodecGetSetti ngs  11-719 
ImageCodecSetSetti ngs  11-737 
ImageCodecFl ush  11-708 
ImageCodecSetTi meCode  11-738 
ImageCodec I slmageDescripti on  Equivalent  11-725 
ImageCodecNewMemory  11-729 
ImageCodecDi sposeMemory  11-696 
ImageCodecHi tTestData  11-722 
ImageCodecNewImageBufferMemory  11-727 
ImageCodec Ext r act AndCombi neFields  11-705 
ImageCodecGetMaxCompressi onSizeWithSources  11-716 
ImageCodecSetTi meBase  11-738 
ImageCodecSourceChanged  11-739 
ImageCodecFl ushFrame  11-708 
ImageCodecGetSetti ngsAsText  11-720 
ImageCodecGetParameterListHandle  11-718 
ImageCodecGetParameterList  11-717 
ImageCodecCreateStandardParameterDialog  11-692 
ImageCodecIsStandardParameterDialogEvent  11-726 
ImageCodecDi smissStandardParameterDialog  11-695 
ImageCodecStandardParameterDial ogDoActi on  11-740 
ImageCodecNewImageGWorl d  11-728 
ImageCodecDi spose I mageGWorld  11-696 
ImageCodecHi tTestDataWith Flags  11-723 
ImageCodecValidateParameters  11-745 
ImageCodecGetBaseMPWorkFunction  11-709 
ImageCodecPref 1 i ght  11-732 
ImageCodecInitialize  11-724 
ImageCodecBegi nBand  11-690 
ImageCodecDrawBand  11-697 
ImageCodecEndBand  11-704 
ImageCodecQueueStarti ng  11-733 
ImageCodecQueueStoppi ng  11-734 
ImageCodecDroppi ngFrame  11-698 
ImageCodecSchedul eFrame  11-736 
ImageCodecCancel Tri gger  11-692 
QTPhotoSetSampl i ng  11-1213 
QT PhotoSet Restartlnterval  11-1213 
QTPhotoDefi neHuffmanTabl e  11-1211 
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QTPhotoDefineQuantizationTable  11-1212 
ImageCodecEf fectSetup  11-704 
ImageCodecEf fectBegi n  11-698 
ImageCodecEffectRenderFrame  11-702 
ImageCodecEf fectC on vert  Effect Sou rceTo Format  11-699 
ImageCodecEf fectCancel  11-699 
ImageCodecEf fectGetSpeed  11-700 
ImageCodecEffectPrepareSMPTEFrame  11-701 
ImageCodecEffectDisposeSMPTEFrame  11-700 
ImageCodecEf feet RenderSMPTEFrame  11-702 
CurveGetLength  1-155 
CurveLengthToPoi nt  1-159 
CurveNewPath  1-160 
CurveCountPointsInPath  1-153 
CurveGetPathPoi nt  1-157 
CurvelnsertPoi ntlntoPath  1-158 
CurveSetPathPoi nt  1-162 
CurveGetNearestPathPoi nt  1-156 
CurvePathPoi ntToLength  1-161 
CurveCreateVectorStream  1-154 
CurveAddAtomToVectorStream  1-151 
CurveAddPathAtomToVectorStream  1-152 
CurveAddZeroAtomToVectorStream  1-152 
CurveGetAtomDataFromVectorStream  1-154 
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NewICMDataUPP  11-1062 
NewICMFl ushUPP  11-1063 
NewICMCompl eti onUPP  11-1061 
NewICMProgressUPP  11-1064 
NewStdPi xUPP  11-1118 
NewQDPi xUPP  11-1096 
NewICMAl i gnmentUPP  11-1060 
NewICMCursorShi el dedUPP  11-1062 
NewICMMemoryDi sposedUPP  11-1063 
NewICMConvertDataFormatUPP  11-1061 
Di sposelCMDataUPP  1-264 
Di sposelCMFl ushUPP  1-264 
Di sposelCMCompl eti onUPP  1-263 
Di sposelCMProgressUPP  1-265 
Di sposeStdPi xUPP  1-299 
Di sposeQDPi xUPP  1-281 
Di sposelCMAl i gnmentUPP  1-262 
DisposelCMCursorShi el dedUPP  1-264 
Di sposelCMMemoryDi sposedUPP  1-265 
Di sposelCMConvertDataFormatUPP  1-263 
CodecManagerVersi on  1-103 
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GetCodecNameLi st  1-386 
Di sposeCodecNameLi st  1-257 
GetCodecInfo  1-385 
GetMaxCompressi onSi ze  1-420 
GetCSequenceMaxCompressi onSize  1-405 
GetCompressi onTi me  1-401 
Compress  Image  1-113 
FCompress Image  1-344 
Decompress  Image  1-235 
FDecompress Image  1-355 
CompressSequenceBegi n  1-119 
CompressSequenceFrame  1-124 
DecompressSequenceBegi n  1-238 
DecompressSequenceBegi nS  1-239 
DecompressSequenceFrame  1-242 
DecompressSequenceFrameS  1-243 
Decomp ressSequenceFrameW hen  1-245 
CDSequenceFl ush  1-80 
SetDSequenceMatri x  1 1 1 - 1 587 
GetDSequenceMatri x  1-410 
SetDSequenceMatte  1 1 1 - 1 588 
SetDSequenceMask  1 1 1-1586 
SetDSequenceT ransferMode  1 1 1 -1591 
SetDSequenceDataProc  1 1 1 - 1 584 
SetDSequenceAccuracy  1 1 1 - 1 583 
SetDSequenceSrcRect  1 1 1 - 1 589 
SetDSequenceFl ags  1 1 1 - 1 585 
GetDSequencelmageBuffer  1-409 
GetDSequenceScreenBuffer  1-410 
SetCSequenceQual i ty  1 1 1 - 1 580 
SetCSequencePrev  1 1 1-1579 
SetCSequenceFl ushProc  1 1 1-1575 
SetCSequence Key  Frame Rate  1 1 1-1577 
GetCSequenceKeyFrameRate  1-405 
GetCSequencePrevBuffer  1-406 
CDSequenceBusy  1-75 
CDSequenceEnd  1-77 

CDSequenceEquivalentlmageDescription  1-78 
GetCompressedlmageSi ze  1-396 
GetSi mi  1 ari ty  1-508 
GetlmageDescriptionCTable  1-417 
SetlmageDescriptionCTable  1 1 1 -1593 
GetlmageDescripti on  Ext en si  on  1-418 
Add ImageDescripti on  Extension  1-25 
Remove  I mageDescri pti on  Ext en si  on  1 1 1 -1457 
CountlmageDescripti on  Ext en si onType  1-143 
Get Next  I mageDescri pti on  Ext en si onType  1-501 
FindCodec  1-358 
CompressPi cture  1-116 
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FCompressPi cture  1-348 

CompressPi ctureFi 1 e  1-118 

FCompressPi ctureFi 1 e  1-352 

GetPi ctureFi 1 eHeader  1-504 

DrawPi ctureFi 1 e  1-310 

DrawTrimmedPi cture  1-311 

DrawTrimmedPi ctureFi 1 e  1-313 

MakeThumbnai IFromPi cture  11-790 

MakeThumbnai 1 FromPi ctureFi 1 e  11-791 

MakeThumbnai 1 FromPixMap  11-792 

Trimlmage  III-1956 

Convertlmage  1-131 

GetCompressedPixMapInfo  1-397 

Set Compressed  Pi xMapInfo  1 1 1-1573 

StdPix  1 1 1-1912 

TransformRgn  III -1955 

SFGetFi 1 ePrevi ew  1 1 1-1674 

SFPGetFi 1 ePrevi ew  III-1676 

StandardGetFi 1 ePrevi ew  1 1 1-1910 

CustomGetFi 1 ePrevi ew  1-163 

MakeFi 1 ePrevi ew  11-784 

Add  F i 1 ePrevi ew  1-24 

A1 i gnScreenRect  1-46 

AlignWindow  1-47 

DragAl i gnedWi ndow  1-306 

DragAl i gnedGrayRgn  1-304 

SetCSequenceDataRateParams  1 1 1-1574 

SetCSequenceFrameNumber  III -1576 

SetCSequencePref erred  Packet Si ze  1 1 1-1578 

NewImageGWorl d  11-1066 

GetCSequenceDataRateParams  1-403 

GetCSequenceFrameNumber  1-404 

GetBestDevi ceRect  1-382 

SetSequenceProgressProc  1 1 1 - 1639 

GDHasScale  1-381 

GDGetScale  1-380 

GDSetScale  1-382 

ICMShi el dSequenceCursor  11-679 

ICMDecompressCompl ete  11-671 

ICMDecompressCompl eteS  11-672 

ICMSequenceLockBi ts  11-675 

ICMSequenceUnl ockBi ts  11-677 

ICMGetPixel Formatlnfo  11-673 

ICMSetPixel Formatlnfo  11-678 

ICMSequenceGetChai nMember  11-674 

SetDSequenceT i meCode  1 1 1-1590 

CDSequenceNewMemory  1-84 

CDSequenceDi sposeMemory  1-77 

CDSequenceNewDataSource  1-82 
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CDSequenceDi sposeDataSource  1-76 

CDSequenceSetSourceData  1-86 

CDSequenceChangedSourceData  1-76 

CDSequenceSetSourceDataQueue  1-87 

CDSequenceGetDataSource  1-81 

PtlnDSequenceData  11-1147 

Hi tTestDSequenceData  1-667 

GetGraphicsImporterForFile  1-414 

GetGraphicsImporterForDataRef  1-412 

GetGraphicsImporterForFileWithFlags  1-416 

GetGraphicsImporterForDataRefWithFlags  1-413 

QTGetFi 1 e Name  Ext en si  on  11-1177 

ImageTranscodeSequenceBegin  11-754 

ImageTranscodeSequenceEnd  11-755 

ImageTranscodeFrame  11-750 

ImageTranscodeDisposeFrameData  11-749 

CDSequencelnval i date  1-82 

CDSequenceSetTi meBase  1-88 

ImageFi el dSequenceBegi n  11-746 

ImageFi el dSequenceExtractCombi ne  11-747 

ImageFi el dSequenceEnd  11-747 

QTNewGWorl d  11-1204 

QTNewGWorl dFromPtr  11-1206 

QTUpdateGWorl d  11-1318 

MakelmageDescriptionForPixMap  11-787 

MakelmageDescripti on  For  Effect  11-785 

QTGetPi xel Si ze  11-1179 

QTGetPi xMapPtrRowBytes  11-1183 

QTGetPi xMapHandl eRowBytes  11-1181 

QTSetPi xMapPtrRowBytes  11-1231 

QTSetPi xMapHandl eRowBytes  11-1228 

QuadToQuadMatrix  11-1447 

GetMatri xType  1-419 

CopyMatrix  1-139 

EqualMatrix  1-338 

Setldenti tyMatrix  1 1 1-1593 

Transl ateMatri x  III -1956 

RotateMatrix  III -1462 

ScaleMatrix  1 1 1-1527 

SkewMatrix  III - 1827 

TransformFi xedPoi nts  III -1951 

TransformPoi nts  III -1953 

TransformFi xedRect  III -1952 

TransformRect  III -1954 

InverseMatrix  11-774 

ConcatMatrix  1-128 

RectMatrix  1 1 1-1451 

MapMatrix  11-794 

CompAdd  1-107 
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CompSub  1-127 
CompNeg  I  - 1 1 1 
CompShift  1-127 
CompMul  1-109 
CompDiv  1-108 
CompFixMul  1-108 
CompMulDiv  1-109 
CompMul Di vTrunc  I  - 1 1 0 
CompCompare  1-107 
CompSquareRoot  1-127 
FixMulDiv  1-362 
Unsi gnedFixMul Di v  1 1 1-1981 
FracSinCos  1-378 
Ft xExp2  1-361 
Fi xLog2  1-362 
FixPow  1-363 

Graphi cs Import Set Data  Reference  1-653 

Graph icsImportGet Data  Reference  1-626 

Graphi csImportSetDataFile  1-651 

Graphi csImportGetDataFile  1-621 

Graphi cs Import Set Data  Hand  1 e  1-652 

Graphi cs Import Get Data  Hand  1 e  1-623 

GraphicsImportGetlmageDescription  1-638 

Graphi cs Import Get Data Of f set And Si ze  1-624 

Graphi cs ImportReadData  1-645 

Graphi cs ImportSetCl i p  1-650 

Graphi cs ImportGetCl i p  1-620 

Graphi cs Import Set Source Rect  1-664 

Graphi cs Import Get Source Rect  1-645 

Graphi csImportGet Natural  Bounds  1-642 

Graphi cs ImportDraw  1-616 

Graphi cs Import Set GWorl d  1-660 

Graphi cs ImportGetGWorl d  1-636 

Graphi cs ImportSetMatri x  1-661 

Graphi cs ImportGetMatri x  1-639 

Graphi cs Import Set Bounds Rect  1-649 

Graphi csImportGet Bounds Rect  1-619 

Graphi csImportSaveAsPi cture  1-647 

Graphi cs Import Set Graphi csMode  1-659 

Graph i cs I mportGet Graph icsMode  1-635 

Graphi cs ImportSetQual i ty  1-663 

Graphi cs ImportGetQual i ty  1-643 

Graphi cs Import SaveAsQui ckTimelmageFi 1 e  1-648 

Graphi cs Import Set Data  Ref erenceOf f set And  Li  mi t  1-654 

Graphi cs I mportGet Data  Ref erenceOf f set And  Li  mi t  1-627 

Graphi cs I mportGet A1 i ased Data  Reference  1-618 

Graph i cs I mportVali date  1-665 

Graphi cs ImportGetMetaData  1-640 

Graphi csl mportGet MIMETypeList  1-641 
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Graph icsImportDoesDrawAllPixe Is  1-613 

Graphics  I mportGetAsPicture  1-618 

Graph i cs Import  Export  I  mage Fi 1 e  1-616 

Graph i cs Import Get  Export ImageTypeLi st  1-632 

Graph i cs Import Do  Export  I  mage Fi leDialog  1-614 

Graph i cs ImportGetExportSetti ngsAsAtomContai ner  1-633 

Graphics  I mportSetExportSetti ngsFromAtomContai ner  1-657 

Graphics  I mportSetProgressProc  1-662 

Graphics  I mportGetProgressProc  1-643 

Graphics  Import Get  I mageCount  1-637 

GraphicsImportSetlmagelndex  1-661 

Graph icsImportGetlmagelndex  1-638 

Graph i cs ImportGetDataOff setAndSi ze64  1-625 

Graphi cs ImportReadData64  1-646 

Graph i cs ImportSetDataReferenceOff set And  Li  mi t64  1-656 

Graphi cs ImportGetDataReferenceOff set And  Li  mi t64  1-628 

Graphi cs I mportGetDefaul tMatri x  1-630 

Graphi csImportGetDefaultCl ip  1-629 

Graphics  I mportGetDefaultGraphicsMode  1-630 

Graphics  I mportGetDefaultSourceRect  1-631 

Graphi csImportGetCol or SyncProfile  1-621 

Graphi cs ImportSetDestRect  1-657 

Graphi cs ImportGetDestRect  1-632 

Graphi cs ImportSetFl ags  1-658 

Graphi cs ImportGetFl ags  1-634 

Graphi csExportDoExport  1-554 

Graphi csExportCanTranscode  1-552 

Graphi csExportDoTranscode  1-555 

Graphi csExportCanUseCompressor  1-553 

Graphi csExportDoUseCompressor  1-556 

Graphi csExportDoStandal one  Export  1-554 

Graphics  Export GetDefaultFil eTypeAndCreator  1-561 

Graphi csExportGetDefaul t  Fi 1 eNameExtensi on  1-560 

Graphi csExportGetMIMETypeLi st  1-577 

Graphi csExportRequestSetti ngs  1-588 

Graphics ExportSetSetti ngsFromAtomContai ner  1-610 

Graphics  Export GetSetti ngsAsAtomContai ner  1-583 

Graphics ExportGetSetti ngsAsText  1-584 

Graphi cs Expo r t Set Don t Recompress  1-592 

Graphi cs Expo r t Get Don t Recompress  1-562 

Graphi cs Export Set Interl aceStyle  1-603 

Graph icsExportGetlnterlaceStyle  1-575 

Graphi csExportSetMetaData  1-604 

Graphi csExportGetMetaData  1-576 

Graphi csExportSetTargetDataSi ze  1-611 

Graphi csExportGetTargetDataSi ze  1-585 

Graphi cs Export Set Comp  res si onMethod  1-589 

Graphi cs Export Get Comp  res si onMethod  1-559 

Graphi cs Expo rt Set Comp  res si onQual i ty  1-590 
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Graphi cs Export Get Comp res  si onQuality  1-559 

Graphi cs Export Set  Resol ution  1-609 

Graphi csExportGetResolut ion  1-583 

Graphi csExportSetDepth  1-591 

Graphi csExportGetDepth  1-562 

Graphics  Expo rt Set Col  or SyncProfile  1-589 

Graph icsExportGet Col  or SyncProfile  1-558 

Graphi cs Export Set  Prog  res sProc  1-608 

Graphics ExportGetProgressProc  1-582 

Graphi cs Export Set  In put Data  Reference  1-593 

Graphics ExportGetlnputData Reference  1-563 

Graphi cs Export Set  I nputFi 1 e  1-594 

Graphics ExportGetlnputFile  1-565 

Graphics  Expo rt Set InputHandle  1-597 

Graphi cs Export Get  I nputHandl e  1-568 

Graphi csExportSetlnputPtr  1-602 

Graphi csExportGetlnputPtr  1-574 

Graphi cs Export Set  Input Graphi cslmporter  1-595 

Graphics ExportGetlnputGraphicsImporter  1-566 

Graphics  Expo rt Set InputPicture  1-599 

Graphics ExportGetlnputPicture  1-572 

Graphi cs Export Set InputGWorl d  1-596 

Graph i csExportGet Input GWorld  1-567 

Graphics  Expo rt Set InputPi xmap  1-600 

Graphics  Expo rt Get InputPi xmap  1-573 

Graphi cs Export Set  In put Of f set And  Li  mi t  1-598 

Graphi csExportGet In put Of f set And  Li  mi t  1-572 

Graphics ExportMay Expo rter Re adlnputData  1-585 

Graphics ExportGetlnputDataSize  1-564 

Graphics  Export  Re adlnputData  1-586 

Graph icsExportGetlnputlmageDescript ion  1-570 

Graph icsExportGetlnputlmageDi mens  ions  1-571 

Graphics ExportGetlnputlmageDepth  1-569 

Graphics ExportDrawInputI mage  1-557 

Graphi cs Export Set Out put Data  Reference  1-604 

Graphics ExportGetOutputData Reference  1-578 

Graphi cs Export Set Out put Fi 1 e  1-605 

Graphics ExportGetOutputFile  1-578 

Graphi cs Export Set Out put Ha ndl e  1-606 

Graphics ExportGetOutputHandle  1-580 

Graphi csExportSetOutputOffsetAndMaxSi ze  1-608 

Graphi csExportGetOutputOffsetAndMaxSi ze  1-581 

Graph ics Expo rt Set OutputFil eTypeAndCreator  1-606 

Graphics ExportGetOutputFil eTypeAndCreator  1-579 

Graph ics ExportWriteOutputData  1-611 

Graphi cs Export Set Out put Mark  1-607 

Graphics ExportGetOutputMark  1-580 

Graphics  Export  Re adOutputData  1-587 

I mageTranscoderBeg inSequence  11-751 
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ImageTranscoderConvert  11-752 
ImageTranscoderDisposeData  11-753 
ImageTranscoderEndSequence  11-754 


MediaHandlers.h 


Call  Component  Exec uteWi redActi on  1-60 

Medi alniti al ize  11-877 

MediaSetHandlerCapabilities  II -894 

Medialdle  11-874 

Medi aGetMedi a  Info  11-853 

MediaPutMedialnfo  11-884 

Medi aSetActi ve  11-889 

MediaSetRate  11-903 

Medi aGGetStatus  11-869 

Medi aTrackEdi ted  11-914 

Medi aSetMedi aTi meScal e  11-898 

Medi aSetMovi eTi meScal e  11-899 

Medi aSetGWorl d  11-893 

Medi aSetDi mensi ons  11-891 

MediaSetClip  11-890 

Medi aSetMatri x  11-897 

Medi aGetTrackOpaque  11-865 

Medi aSetGraphi csMode  11-892 

Medi aGetGraphi csMode  11-852 

Medi aGSetVol ume  11-871 

Medi aSetSoundBal ance  11-904 

Medi aGetSoundBal ance  11-860 

Medi aGetNextBoundsChange  11-855 

Medi aGetSrcRgn  11-865 

MediaPreroll  11-883 

MediaSampleDescriptionChanged  II -887 

Medi aHasCharacteri stic  11-872 

Medi aGetOffscreenBufferSi ze  11-858 

Medi aSetHi nts  11-896 

MediaGetName  11-855 

Medi aForceUpdate  11-847 

Medi aGetDrawi ngRgn  11-849 

Medi aGSetActi veSegment  11-870 

Medialnval idateRegion  11-879 

Medi aGetNextStepTi me  11-856 

MediaSetNonPrimarySourceData  11-899 

Medi aChangedNonPrimary Source  11-843 

MediaTrackReferencesChanged  11-915 

Medi a GetSampleData Pointer  11-859 

Medi a  Re leaseSampleData Pointer  II -886 

Medi aT  rackPropertyAtomChanged  11-915 

Medi aSetT  racklnputMapReference  11-908 
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Medi aSetVideoParam  11-910 

Medi a  Get Vi deo Pa  ram  11-868 

MediaCompare  11-844 

Medi aGetCl ock  11-849 

Medi a  Set Sou ndOut put Component  11-908 

Medi a  Get Sou ndOut put Component  11-864 

MediaSet Sound  Local izationData  11-907 

Medi aGetlnval idRegi on  11-853 

Medi a  Samp 1 eDescri pti onB2N  11-887 

Medi a  Samp 1 eDescri pti onN2B  1 1-888 

Medi aQueueNonPrimary Sour ceData  11-885 

MediaFlushNonPrimarySourceData  11-847 

Medi aGetURLLi nk  11-866 

Medi aMakeMedi a  T i meTabl e  11-879 

MediaHitTestForTargetRefCon  11-873 

MediaHitTestTargetRefCon  11-873 

Medi a  Get Act i onsForQT Event  1 1-848 

Medi a  D i sposeTargetRefCon  11-845 

Medi aTargetRefConsEqual  11-912 

Medi a  Set Ac ti onsCallback  1 1-888 

Medi aPrePrerol 1 Begi n  11-882 

Medi aPrePrerol 1  Cancel  11-883 

Medi aEnterEmptyEdi t  11-846 

Medi aCurrentMediaQueued Data  II -844 

Medi aGetEf f ecti veVol ume  11-851 

Medi aResol veTargetRefCon  11-886 

MediaGetSoundLevelMeteringEnabled  11-863 

MediaSetSoundLevelMeteringEnabled  11-906 

Medi a  Get Sound  Level  Meter  Info  11-863 

MediaGet Effect iveSoundBalance  11-850 

Medi aSetScreenLock  11-904 

Medi aSetDoMCActi onCallback  11-892 

Medi aGetErrorStri ng  11-851 

Med iaGet Sound  Equal izerBands  11-862 

Med iaSet Sound  Equal izerBands  11-906 

Med iaGet Sound  Equal izerBandLevels  11-862 

Medi a  Do  I d 1 eActi ons  11-845 

MediaSetSoundBassAndTreble  11-905 

MediaGetSoundBassAndTreble  11-861 

Medi aTimeBaseC hanged  11-913 

MediaMCIsPlayerEvent  11-881 

Medi aGetMedi a LoadState  11-854 

NewPrePrerol 1 Compl eteUPP  11-1095 

DisposePrePreroll Compl eteUPP  1-280 
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CheckQui ckTimeRegi strati  on  1-89 
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EnterMovies  1-337 

ExitMovies  1-340 

GetMovi esError  1-492 

Cl earMovi esSti ckyError  1-90 

GetMovi esSti cky Error  1-494 

SetMovi esErrorProc  1 1 1-1633 

MoviesTask  11-973 

PrerollMovie  11-1142 

PrePrerol 1 Movi e  11-1141 

AbortPrePrerol 1 Movi e  1-21 

LoadMovi elntoRam  11-781 

LoadTracklntoRam  11-782 

LoadMedi alntoRam  11-779 

SetMovi eActi ve  III -1609 

GetMovi eActi ve  1-456 

StartMovie  1 1 1-1911 

StopMovie  III -1914 

GoToBegi nni ngOfMovi e  1-550 

GoToEndOfMovi e  1-551 

IsMovieDone  11-774 

GetMovi ePrevi ewMode  1-487 

SetMovi ePrevi ewMode  1 1 1 - 1 628 

ShowMovi ePoster  III - 1827 

PI ayMovi ePrevi ew  11-1140 

GetMovi eTi meBase  1-496 

SetMovi eMasterT i meBase  1 1 1-1621 

SetMovi eMasterCl ock  1 1 1-1620 

GetMovi eGWorl d  1-471 

SetMovi eGWorl d  1 1 1-1619 

SetMovi eDrawi ngCompl eteProc  1 1 1-1617 

GetMovi eNatural BoundsRect  1-479 

GetNextTrackForComposi ti ng  1-502 

GetPrevTrackForComposi ti ng  1-506 

SetTrackGWorl d  1 1 1 - 1659 

GetMoviePict  1-483 

GetTrackPict  1-540 

GetMovi ePosterPi ct  1-484 

UpdateMovie  1 1 1 - 1981 

Inval i dateMovi eRegi on  11-771 

GetMovieBox  1-460 

SetMovieBox  1 1 1-1611 

GetMovi e  D i spl ayCl i pRgn  1-469 

SetMovi e  D i spl ayCl i pRgn  III -1616 

GetMovi eCl i pRgn  1-462 

SetMovi eCl i pRgn  1 1 1-1612 

GetTrackCl i pRgn  1-524 

SetTrackCl i pRgn  III -1656 

GetMovi e  D i spl ayBoundsRgn  1-468 

GetTrackDi spl ayBoundsRgn  1-528 
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GetMovi eBoundsRgn  1-459 
GetTrackMovieBoundsRgn  1-537 
GetTrackBoundsRgn  1-523 
GetTrackMatte  1-534 
SetTrackMatte  1 1 1 - 1663 
DisposeMatte  1-267 
NewMovie  11-1069 
PutMovielntoHandle  11-1151 
PutMovi elntoDataFork  11-1150 
PutMovieIntoDataFork64  11-1150 
DisposeMovie  1-268 
GetMovi eCreati onTime  1-465 
GetMovi eModi fi cat i onTi me  1-479 
GetMovieTimeScal e  1-496 
SetMovi eTimeScal e  1 1 1  - 1635 
GetMovi eDurati on  1-470 
GetMovieRate  1-490 
SetMovieRate  1 1 1-1631 
GetMovi ePref erredRate  1-485 
SetMovi ePref erredRate  1 1 1-1626 
GetMovi ePreferredVol ume  1-486 
SetMovi ePreferredVol ume  1 1 1 -1627 
GetMovi eVol ume  1-500 
SetMovi eVol ume  1 1 1 - 1637 
GetMovi eMatri x  1-478 
SetMovi eMatri x  1 1 1-1622 
GetMovi ePrevi ewTime  1-487 
SetMovi ePrevi ewTime  III-1629 
GetMovi ePosterTime  1-485 
SetMovi ePosterTi me  1 1 1-1625 
GetMovi eSel ecti on  1-491 
SetMovi eSel ecti on  1 1 1  - 1632 
SetMovi eActi veSegment  III-1609 
GetMovi eActi veSegment  1-457 
GetMovi eTime  1-495 
SetMovieTime  1 1 1 - 1634 
SetMovi eTimeVal ue  1 1 1 -1635 
GetMovi eUserData  1-499 
GetMovi eTrackCount  1-498 
GetMovi eTrack  1-497 
GetMovielndTrack  1-473 
GetMovielndTrackType  1-475 
GetTrackID  1-531 
GetTrackMovi e  1-536 
NewMovi eTrack  11-1092 
Di sposeMovi eTrack  1-278 
GetTrackCreati onTime  1-524 
GetTrackModi fi cati onTime  1-536 
GetTrackEnabl ed  1-531 
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SetTrackEnabl ed  III -1658 

GetTrackUsage  1-545 

SetTrackUsage  1 1 1 - 1 668 

GetTrackDurati on  1-529 

GetTrackOf fset  1-539 

SetTrackOffset  1 1 1 - 1664 

GetTrackLayer  1-532 

SetTrackLayer  III -1660 

GetTrackAl ternate  1-522 

SetTrackAl ternate  1 1 1 - 1656 

SetAutoTrackAlternates Enabled  1 1 1-1570 

Sel ectMovi eAl ternates  1 1 1-1569 

GetTrackVol ume  1-547 

SetTrackVol ume  III -1669 

GetTrackMatri x  1-533 

SetTrackMatri x  1 1 1-1662 

GetTrackDi mensi ons  1-527 

SetTrackDi mensi ons  III -1657 

GetTrackUserData  1-546 

GetTrackDi spl ayMatri x  1-528 

GetTrackSound Local izationSettings  1-543 

SetTrackSound Local izationSettings  1 1 1-1666 

NewTrackMedi a  11-1120 

Di sposeTrackMedi a  1-301 

GetTrackMedi a  1-535 

GetMedi aTrack  1-455 

GetMedi aCreati onTi me  1-424 

GetMedi aModi fi cati onTi me  1-437 

GetMedi aTi meScal e  1-455 

SetMedi aTi meScal e  1 1 1 - 1 608 

GetMedi aDurati on  1-430 

GetMedi aLanguage  1-436 

SetMedi aLanguage  III -1600 

GetMedi aQual i ty  1-441 

SetMedi aQual i ty  1 1 1-1605 

GetMedi aHandlerDescription  1-432 

GetMedi aUserData  1-456 

GetMedialnputMap  1-435 

SetMedialnputMap  1 1 1-1599 

GetMedi aHandl er  1-432 

SetMedi aHandl er  1 1 1 - 1 598 

Begi nMedi a  Ed i ts  1-56 

EndMedi a  Ed i ts  1-335 

SetMedi aDefaultDataReflndex  1 1 1-1597 

GetMedi aDataHandlerDescription  1-426 

GetMedi aDataHandl er  1-425 

SetMedi aDataHandl er  1 1 1 - 1594 

GetDataHandl er  1-407 

OpenADataHandl er  11-1127 
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Get Med i a  Samp 1 eDescri pti onCount  1-447 
GetMedi aSampl eDescri pti on  1-445 
SetMedi aSampl eDescri pti on  III -1606 
GetMedi aSampl eCount  1-445 
GetMedi aSyncSampl eCount  1-454 
Sampl eNumToMediaTime  III -1526 
Medi a  T i meToSampl eNum  11-913 
AddMedi aSampl e  1-27 
AddMedi aSampl eReference  1-31 
AddMedi aSampl eReferences  1-33 
AddMedi aSampl eReferences64  1-34 
GetMedi aSampl e  1-443 
GetMedi aSampl eReference  1-447 
GetMedi aSampl eReferences  1-449 
GetMedi aSampl e Ref erences 64  1-451 

SetMedi aPreferredChunkSize  1 1 1-1603 
GetMedi a  Prefer redChunkSi ze  1-440 
SetMedi aShadowSync  III-1607 
GetMedi aShadowSync  1-453 
InsertMedialntoTrack  11-761 
InsertTrackSegment  11-764 
InsertMovi eSegment  11-762 
InsertEmptyTrackSegment  11-760 
InsertEmptyMovi eSegment  11-759 
Del eteTrackSegment  1-252 
Del eteMovi eSegment  1-250 
Seal eTrackSegment  III -1529 
Seal eMovi eSegment  1 1 1 -1528 
CutMovi eSel ecti on  1-166 
CopyMovi eSel ecti on  1-139 
PasteMovi eSel ecti on  11-1139 
AddMovi eSel ecti on  1-38 
ClearMovieSelection  1-90 
PasteHandl elntoMovie  11-1137 
PutMovi el ntoTyped Handle  11-1152 
IsScrapMovi e  11-775 
CopyTrackSetti ngs  1-141 
CopyMovi eSetti ngs  1-140 
AddEmptyTrackToMovie  1-23 
NewMovi eEdi tState  11-1073 
UseMovi eEdi tState  1 1 1  - 1984 
Di sposeMovi eEdi tState  1-273 
NewTrackEdi tState  11-1119 
UseTrackEdi tState  1 1 1  - 1984 
Di spos eT rack Ed i tState  1-300 
AddTrackRef erence  1-42 
Del eteTrackRef erence  1-252 
SetTrackRef erence  III -1665 
GetTrackRef erence  1-541 
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GetNextTrackReferenceType  1-503 
GetTrackReferenceCount  1-542 
ConvertFil eToMovi eFi 1 e  1-129 
ConvertMovi eToFi 1 e  1-134 
GetMovi elmporterForDataRef  1-472 
TrackTimeToMediaTime  III -1951 
GetTrackEdi tRate  1-530 
GetMovi eDataSi ze  1-465 
GetMovi eDataSi ze64  1-466 
GetTrackDataSi ze  1-525 
GetTrackDataSi ze64  1-526 
GetMedi aDataSi ze  1-429 
GetMedi aDataSi ze64  1-430 
PtlnMovie  11-1148 
PtlnTrack  11-1149 
SetMovi eLanguage  III -1620 
GetllserData  1-547 
AddUserData  1-44 
RemoveUserData  III -1459 
CountUserDataType  1-144 
GetNextUserDataType  1-503 
GetUserDataltem  1-548 
SetUserDataltem  III -1673 
AddUserDataText  1-45 
GetUserDataText  1-549 
RemoveUserDataText  1 1 1 - 1460 
NewUserData  11-1124 
Di sposeUserData  1-303 
NewUserDataFromHandl e  11-1124 
PutUserDatalntoHandl e  11-1154 
SetMovi ePropertyAtom  III -1631 
GetMovi ePropertyAtom  1-489 
GetMedi a  Next  In teres ti ngTi me  1-437 
GetT  rackNext In teres ti ngTi me  1-537 
GetMovi eNext In teres ti ngT i me  I -480 
CreateMovi eFi 1 e  1-145 
OpenMovi eFi 1 e  11-1133 
Cl oseMovi eFi 1 e  1-102 
Del eteMovi eFi 1 e  1-249 
NewMovi eFromFi 1 e  11-1080 
NewMovi eFromHandl e  11-1084 
NewMovi eFromDataFork  11-1075 
NewMovi eFromDataFork64  11-1077 
NewMovi eFromUserProc  11-1087 
NewMovi eFromDataRef  11-1078 
AddMovi eResource  1-36 
UpdateMovi eResource  1 1 1 - 1 983 
RemoveMovi eResource  1 1 1-1458 
HasMovi eChanged  1-666 
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Cl earMovi eChanged  1-89 

SetMovi eDefaul tDataRef  III-1616 

GetMovi eDefaul tDataRef  1-467 

SetMovi eAnchorDataRef  III-1610 

GetMovi eAnchorDataRef  1-458 

SetMovieColorTable  III-1613 

GetMovi eCol orTabl e  1-463 

FlattenMovie  1-372 

FI attenMovi eData  1-374 

SetMovi eProgressProc  1 1 1 - 1630 

GetMovi eProgressProc  1-488 

CreateShortcutMovi e  F i 1 e  1-149 

Movi eSearchText  11-972 

GetPosterBox  1-505 

SetPosterBox  1 1 1  - 1638 

GetMovi eSegmentDi spl ayBoundsRgn  1-490 

GetTrackSegmentDi spl ayBoundsRgn  1-542 

SetMovi eCoverProcs  III-1614 

GetMovi eCoverProcs  1-464 

GetTrackStatus  1-544 

GetMovi eStatus  1-494 

GetMovi eLoadState  1-477 

NewMovi eControl 1 er  11-1071 

Di sposeMovi eControl 1 er  1-270 

ShowMovi elnformati on  1 1 1-1826 

PutMovi eOnScrap  11-1153 

NewMovi eFromScrap  11-1085 

GetMedi aDataRef  1-427 

SetMedi aDataRef  1 1 1-1595 

Set Med i aDataRef Attri butes  III -1596 

AddMedi aDataRef  1-26 

GetMedi aDataRefCount  1-428 

QTNewAl i as  11-1202 

SetMovi ePl ayHi nts  III -1623 

SetMedi a  PI ayHi nts  III-1601 

GetMedi aPl ayHi nts  1-439 

SetT  ra c k Load Set ti ngs  III-1661 

GetTrackLoadSetti ngs  1-532 

Begi nFul 1  Screen  1-52 

EndFul 1  Screen  1-314 

AddMovi eExecuteWi redActi onsProc  1-36 

RemoveMovi eExecuteWi redActi onsProc  1 1 1-1457 

Movi eExecuteWi redActi ons  11-918 

NewSpri teWorl d  11-1114 

Di sposeSpri teWorl d  1-297 

SetSpri teWorl dCl i p  1 1 1 -1644 

SetSpri teWorldMatrix  1 1 1  - 1647 

SetSpriteWorldGraphicsMode  1 1 1-1646 

Spri teWorl dldl e  1 1 1-1908 
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InvalidateSpriteWorld  11-773 

Spri teWorl dHi tTest  1 1 1-1907 

Spri teHi tTest  III - 1885 

Di sposeAl 1 Spri tes  1-255 

SetSpri teWorl d  FI ags  III -1645 

NewSprite  11-1113 

Di sposeSpri te  1-296 

InvalidateSprite  11-772 

SetSpri teProperty  1 1 1 - 1 64 1 

GetSpri teProperty  1-512 

QTNewAtomContai ner  11-1203 

QTDi sposeAtomContai ner  11-1164 

QTGetNextChi 1 dType  11-1178 

QTCountChi 1 drenOfType  11-1160 

QTFi ndChi 1 dBy Index  11-1167 

QTFi ndChi 1 d By  I D  11-1166 

QTNextChi 1 dAnyType  11-1209 

QTSetAtomData  11-1223 

QTCopyAtomDataToHandl e  11-1158 

QTCopyAtomDataToPtr  11-1159 

QTGetAtomTypeAndID  11-1172 

QTCopyAtom  11-1158 

QTLockContai ner  11-1187 

QTGetAtomDataPtr  11-1171 

QTUnl ockContai ner  11-1316 

QTInsertChi 1 d  11-1183 

QTInsertChi 1 dren  11-1185 

QTRemoveAtom  11-1215 

QTRemoveChi 1 dren  11-1216 

QTRepl aceAtom  11-1217 

QTSwapAtoms  11-1315 

QTSetAtomI  D  11-1225 

QTGetAtomParent  11-1172 

SetMedi aPropertyAtom  1 1 1 - 1 604 

GetMedi aPropertyAtom  1-440 

QTNewTween  11-1209 

QTDi sposeTween  11-1164 

QTDoTween  11-1165 

AddSoundDescripti on  Ext en si  on  1-40 

GetSoundDescripti on  Ext en si  on  1-509 

RemoveSoundDescri pti on  Ext en si  on  1 1 1 -1459 

GetQui ckTi mePreference  1-507 

SetQui ckTi mePreference  III -1639 

QTGetEffectsLi st  11-1174 

QTCreateStandardParameterDialog  11-1161 

QTIsStandardParameterDialogEvent  11-1186 

QTDismissStandardParameterDialog  11-1163 

QTStandardParameterDial ogDoActi on  11-1313 

QTGetEffectSpeed  11-1176 
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QTGetAccessKeys  11-1168 

QTRegi sterAccessKey  11-1214 

QTUnregi sterAccessKey  11-1317 

MakeTrackTi meTabl e  11-793 

MakeMedi a  T i meTabl e  11-788 

GetMaxLoadedTimelnMovie  1-423 

QTMovi eNeedsTi meTabl e  11-1202 

QTGetDataRefMaxFileOffset  11-1173 

QTBandwi dth Request  11-1156 

QTBandwi dthRequestForT imeBase  11-1157 

QTBandwi dth Re lease  11-1155 

QTSchedul edBandwi dth Request  11-1219 

QTScheduled Bandwidth  Re  lease  11-1219 

ITextAddStri ng  11-776 

ITextRemoveStri ng  11-778 

I  Text Get St ri ng  11-777 

QTTextToNati veText  11-1315 

QTParseTextHREF  11-1210 

Vi deoMedi aResetStati sti cs  1  1  1 -2059 

VideoMedi aGetStati sti cs  1  1  1-2059 

Vi deoMedi a  Get St a  1 1  Count  1  1  1 -2058 

Vi deoMedi a SetCodec Parameter  1  1  1-2060 

Vi deoMedi a GetCodec Parameter  1  1  1-2057 

TextMedi a  Set Text P roc  1 1 1 -1947 

TextMedi aAddTESampl e  1 1 1 - 1933 

TextMedi a Add Hi  1 i teSampl e  1 1 1-1932 

TextMedi aDrawRaw  1 1 1 - 1940 

TextMedi a  Set Text  Property  1 1 1 -1948 

TextMedi a RawSet up  1 1 1 -1946 

TextMedi aRawIdl e  1 1 1 - 1945 

TextMedi a F i ndNextText  1 1 1 - 1941 

TextMedi a H i 1 i teTextSampl e  1 1 1-1944 

TextMedi a  Set Text Samp 1 eData  1 1 1-1950 

Spri teMedi a  Set  Property  1 1 1-1903 

SpriteMediaGet Property  1 1 1-1893 

Spri teMedi aHitTestSprites  III -1900 

Spri teMedi aCountSprites  1 1 1-1887 

Spri teMedi aCountl mages  1 1 1-1886 

Spri teMedi a  Get IndlmageDescri pti on  1 1 1 -1891 

Spri teMedi a  Get Di s pi ayedSampl eN umber  1 1 1-1889 

Spri teMedi a  Get Spri teName  1 1 1-1895 

SpriteMediaGetlmageName  1 1 1-1890 

Spri teMedi a  Set Spri teProperty  1 1 1 -1904 

Spri teMedi a  Get Spri teProperty  1 1 1 -1896 

SpriteMediaHitTestAllSprites  1 1 1 - 1897 

SpriteMediaHitTestOneSprite  1 1 1-1898 

Spri teMedi a Spri telndexToID  1 1 1 -1906 

SpriteMediaSpritelDToIndex  1 1 1-1906 

Spri teMedi a  Get Spri teActi onsForQT Event  1 1 1-1894 


IXF 


Inside  QuickTime:  Functions  By  Header  File 


V-3025 


Functions  By  Header  File 


Movies.h 


Spri teMedi aSetActi onVariable  1 1 1-1901 

Spri teMedi aGetActi onVariable  II 1-1888 

Spri teMedi aGetlndlmageProperty  1 1 1-1891 

Spri teMedi aNewSpri te  III -1901 

Spri teMedi aDisposeSprite  II 1-1887 

Spri teMedi aSetActi onVariableToString  1 1 1 -1902 

Spri teMedi aGetActi onVari abl eAsStri ng  II 1-1889 

FI ashMedi aSetPan  1-370 

FI ashMedi aSetZoom  1-370 

FI ashMedi aSetZoomRect  1-371 

FI ashMedi aGetRefConBounds  1-366 

FI ashMedi aGetRefCon I D  1-367 

FI ashMedi alDToRefCon  1-368 

FI ashMedi a GetDispl ay ed Frame Number  1-365 

FI ashMedi aFrameNumberToMovi eT i me  1-364 

FI ashMedi a  Frame  Label ToMovi eT i me  1-364 

Movi eMedi aGetChi 1 dDoMCActi onCallback  11-966 

Movi eMedi aGetDoMCActi onCallback  11-970 

Movi eMedi aGetCurrentMovi eProperty  11-968 

Movi eMedi aGetCurrentTrackProperty  11-969 

Movi eMedi aGetChi 1 dMovi eData Reference  11-967 

Movi eMedi aSetChi 1 dMovi eData Reference  11-971 

Movi eMedi aLoadChi 1 dMovi eFromData Reference  11-970 

Media3DGetNamed0bjectList  11-840 

Medi a3DGetRendererLi st  11-840 

Medi a3DGetCurrentGroup  11-839 

Media3DTranslateNamed0bjectTo  11-843 

Media3DScaleNamed0bjectTo  11-841 

Media3DRotateNamed0bjectTo  11-841 

Medi a3DSetCameraData  11-842 

Medi a3DGetCameraData  11-839 

Media3DSetCameraAngleAspect  11-842 

Medi a3DGetCameraAngl e Aspect  II -838 

Medi a3DSetCameraRange  11-842 

Medi a3DGetCameraRange  11-839 

Medi a3DGetVi ewObject  11-841 

MCSetMovi e  11-835 

MCGetlndMovi e  11-812 

MCRemoveAl 1 Movi es  11-827 

MCRemoveAMovi e  11-827 

MCRemoveMovi e  11-828 

MCIsPl ayerEvent  11-819 

MCSetActi onFi 1  ter  11-829 

MCDoAction  11-801 

MCSetControl 1 erAttached  11-831 

MCIsControl 1 erAttached  11-818 

MCSetControl 1 erPort  11-833 

MCGetControl 1 erPort  11-810 

MCSetVi si bl e  11-837 
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MCGetVi si bl e  11-815 

MCGetControl 1 erBoundsRect  11-806 

MCSetControl 1 erBoundsRect  11-832 

MCGetControl 1 erBoundsRgn  11-807 

MCGetWi ndowRgn  11-815 

MCMovi eChanged  11-822 

MCSetDurati on  11-834 

MCGetCurrentTime  11-810 

MCNewAttachedControl 1 er  11-823 

MCDraw  11-803 

MCActi vate  11-795 

MCIdle  11-816 

MCKey  11-821 

MCClick  11-799 

MCEnabl eEdi ti ng  11-805 

MCIsEdi ti ngEnabl ed  11-818 

MCCopy  11-800 

MCCut  11-800 

MCPaste  11-824 

MCClear  11-798 

MCUndo  11-838 

MCPositionController  11-824 
MCGetControl 1 erlnfo  11-808 
MCSetCl i p  11-830 
MCGetCl i p  11-805 
MCDrawBadge  11-804 
MCSetUpEdi tMenu  11-836 
MCGetMenuStri ng  11-814 
MCSetActi onFilterWithRefCon  11-829 
MCPtlnControl 1 er  11-826 
MCInvalidate  11-817 
MCAd justCursor  11-796 
MCGetlnterfaceEl ement  11-812 
MCGetDoActi onsProc  11-811 
NewTimeBase  11-1119 
Di sposeTimeBase  1-299 
GetTimeBaseTime  1-521 
SetTimeBaseTime  III -1653 
SetT imeBaseValue  1 1 1-1654 
GetTimeBaseRate  1-518 
SetT imeBaseRate  1 1 1-1651 
GetTimeBaseStartTime  1-518 
SetTimeBaseStartTime  1 1 1 -1652 
GetTimeBaseStopTime  1-520 
SetT imeBaseStopTime  1 1 1-1652 
GetTimeBaseFl ags  1-515 
SetTimeBaseFl ags  1 1 1  - 1648 
SetTimeBaseMasterTimeBase  1 1 1 -1650 
GetTimeBaseMasterTimeBase  1-517 
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SetTi meBaseMasterCl ock  1 1 1-1649 

GetTi meBaseMasterCl ock  1-516 

ConvertTime  1-137 

ConvertTimeScale  1-138 

AddTime  1-41 

SubtractTime  III -1915 

GetTi meBaseStatus  1-519 

SetTi meBaseZero  1 1 1-1655 

GetTi meBaseEffecti veRate  1-514 

NewCal 1  Back  11-1053 

Di sposeCal 1  Back  1-256 

GetCal 1 BackType  1-384 

GetCal 1 BackTi meBase  1-384 

CallMeWhen  1-67 

Cancel  Cal  1  Back  1-70 

AddCal 1 BackToTimeBase  1-21 

RemoveCal 1 BackFromT i meBase  1 1 1-1456 

GetFi rstCal 1  Back  1-411 

GetNextCal 1  Back  1-501 

ExecuteCal 1  Back  1-339 

Musi cMedi a Get IndexedT unePlayer  11-1004 

NewMovi eRgnCoverUPP  11-1091 

NewMovi eProgressUPP  11-1090 

NewMovi eDrawi ngCompl eteUPP  11-1072 

NewTrackTransferUPP  11-1122 

NewGetMovi eUPP  11-1060 

NewMovi ePrevi ewCal lOutUPP  11-1090 

NewTextMedi aUPP  11-1118 

NewActionsUPP  11-1053 

NewDoMCActionUPP  11-1058 

NewMovi eExecuteWi redActi onsUPP  11-1073 

NewMovi ePrePreroll Compl eteUPP  1 1-1089 

NewMovi esErrorUPP  11-1091 

NewQTCal 1 BackUPP  11-1097 

NewQTSyncTaskUPP  11-1099 

NewTweenerDataUPP  11-1123 

NewQTBandwi dthNotificationUPP  11-1096 

NewMCActi onFi 1 terUPP  11-1068 

NewMCActi onFilterWithRefConUPP  11-1069 

Di sposeMovi eRgnCoverUPP  1-277 

Di sposeMovi eProgressUPP  1-276 

Di sposeMovi eDrawi ngCompl eteUPP  1-273 

Di sposeTrackTransferUPP  1-301 

Di sposeGetMovi eUPP  1-261 

Di sposeMovi ePrevi ewCal lOutUPP  1-276 

Di sposeTextMedi aUPP  1-299 

Di sposeActi onsUPP  1-255 

Di sposeDoMCActi onUPP  1-259 

Di sposeMovi eExecuteWi redActi onsUPP  1-274 
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DisposeMoviePrePreroll Compl eteUPP  1-275 
Di sposeMoviesErrorUPP  1-277 
Di sposeQTCal 1 BackUP P  1-282 
Di sposeQTSyncTaskUPP  1-284 
Di sposeTweenerDataUPP  1-302 
Di  sposeQTBandwi  dthNoti  fi  cati  onllPP  1-282 
Di sposeMCActi onFilterUPP  1-268 
Di sposeMCActi onFilterWithRefC onUPP  1-268 


MoviesFormat.h 


No  functions  are  declared  in  Movi esFormat .  h. 


QTML.h 


IXF 


QTMLYi el dCPU  11-1200 

QTMLY i el dCPUT i me  11-1201 

Initial izeQTML  11-756 

Termi nateQTML  III-1926 

CreatePortAssoci ati on  1-148 

DestroyPortAssoci ati on  1-254 

QTMLGrabMutex  11-1195 

QTMLT  ryGrabMutex  11-1199 

QTMLReturnMutex  11-1197 

QTMLCreateMutex  11-1191 

QTMLDestroyMutex  11-1192 

QTMLCreateSyncVar  11-1192 

QTMLDestroySyncVar  11-1193 

QTMLTestAndSetSyncVar  11-1198 

QTMLWai tAndSetSyncVar  11-1200 

QTMLResetSyncVar  11-1197 

Ini ti al i zeQHdr  11-756 

Termi nateQHdr  III-1926 

QTMLAcqui reWi ndowLi st  11-1191 

QTMLRel easeWi ndowLi st  11-1196 

QTMLRegi sterlnterruptSafeThread  11-1196 

QTMLUnregi sterlnterruptSafeThread  11-1199 

Nati veEventToMacEvent  11-1049 

WinEventToMacEvent  1  1  1-2061 

IsTaskBarVisible  11-776 

ShowHideTaskBar  1 1 1 - 1825 

QTGetDDObj  ect  11-1174 

QTSetDDObj  ect  11-1225 

QTSetDDPrimarySurface  11-1226 

QTMLGetVol umeRootPath  11-1194 

QTMLSetWi ndowWndProc  11-1198 
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QTMLGetWi ndowWndProc  11-1195 
QTMLGetCanoni cal PathName  11-1193 
FSSpecToNati vePathName  1-379 
Nati vePathNameToFSSpec  11-1050 


QTSMovie.h 


QTSMedi aSetlnfo  11-1248 
QTSMedi aGetlnfo  11-1245 
QTSMedi aSetlndStreamlnfo  11-1246 
QTSMedi aGetlndStreamlnfo  1 1-1244 


QTStreamingComponents.h 


QTSFi ndReassembl erForPayloadlD  11-1234 
QTSFi ndReassembl erForPayloadName  11-1235 
RTPRssmlni ti al i ze  1 1 1-1514 
RTPRssmHandl eNewPacket  III-1512 
RTPRssmComputeChunkSi ze  1 1 1-1502 
RTPRssmAd just  Packet  Pa  rams  1 1 1-1500 
RTPRssmCopyDataToChunk  1 1 1-1503 
RTPRssmSendPacketLi st  1 1 1-1518 
RTPRssmGetT i meScal e From Packet  1 1 1-1511 
RTPRssmSetlnfo  III -1521 
RTPRssmGetlnfo  1 1 1-1507 
RTPRssmHasCharacteristic  1 1 1-1512 
RTPRssmReset  1 1 1-1516 
RTPRssmSetCapabi 1 i ti es  1 1 1-1520 
RTPRssmGetCapabi 1 i ti es  III -1505 
RTPRssmSetPayloadHeader Length  1 1 1-1523 
RTPRssmGetPayl oadHeader Length  1 1 1-1509 
RTPRssmSetTi meScal e  1 1 1-1525 
RTPRssmGetTi meScal e  1 1 1-1510 
RTPRssmNewStreamHandl er  1 1 1-1514 
RTPRssmSetStreamHandl er  1 1 1 - 1524 
RTPRssmGetStreamHandl er  1 1 1-1510 
RTPRssmSendStreamHandlerChanged  1 1 1-1520 
RTPRssmSetSampleDescription  1 1 1-1524 
RTPRssmGetChunkAndlncrRefCount  1 1 1-1506 
RTPRssmSendChunkAnd Deer Ref Count  1 1 1-1517 
RTPRssmSendLostChunk  III -1517 
RTPRssmSendStreamBufferRange  1 1 1-1519 
RTPRssmClearCachedPackets  1 1 1-1501 
RTPRssmFillPacketListParams  1 1 1-1504 
RTPRssmReleasePacketList  1 1 1-1515 
RTPRssmlncrChunkRefCount  1 1 1-1513 
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RTPRssmDecrChunkRef Count  1 1 1-1504 

QTSFindMediaPacketizer  11-1231 

QTSFindMediaPacketizerForTrack  11-1233 

QTSFindMediaPacketizerForPayloadID  11-1232 

QTSFindMediaPacketizerForPayloadName  11-1233 

RTPMPInitial ize  III - 1473 

RTPMPPref 1 i ghtMedi a  1 1 1-1474 

RTPMPIdl e  1 1 1-1472 

RTPMPSetSampl eData  III - 1480 

RTPMPF1 ush  III - 1464 

RTPMPReset  III - 1474 

RTPMPSetlnfo  1 1 1-1475 

RTPMPGetlnfo  1 1 1-1464 

RTPMPSetTimeScal e  1 1 1-1482 

RTPMPGetTimeScale  1 1 1-1470 

RTPMPSetT i meBase  1 1 1-1481 

RTPMPGetT i meBase  1 1 1-1470 

RTPMPHasCharacteristic  1 1 1-1471 

RTPMPSet Packet Bui  1 der  1 1 1-1479 

RTPMPGet Packet Bui  1 der  1 1 1-1468 

RTPMPSetMedi aType  III - 1478 

RTPMPGetMedi aType  1 1 1-1467 

RTPMPSetMaxPacketSi ze  1 1 1-1477 

RTPMPGetMaxPacketSi ze  1 1 1-1466 

RT PM PSetMaxPacket Duration  1 1 1-1477 

RT PM PGetMaxPacket Duration  1 1 1-1466 

RTPMPDoUserDi al og  1 1 1-1463 

RTPMPSet Set ti ngsFromAtomContai nerAtAtom  1 1 1 -1481 

RTPMPGet Set ti ngs IntoAtomContai nerAtAtom  1 1 1 -1469 

RTPMPGetSetti ngsAsText  1 1 1 - 1468 

RTPPBBegi nPacketGroup  1 1 1 - 1490 

RTPPBEndPacketGroup  1 1 1-1492 

RTPPBBegi nPacket  1 1 1 - 1489 

RTPPBEndPacket  1 1 1-1491 

RTPPBAdd Packet  Li teralData  II 1-1483 

RT P PBAdd Packet Samp 1 eData  1 1 1-1485 

RTPPBAdd Packet  Repea ted Data  1 1 1-1484 

RTPPB Re lease  Repeated Data  1 1 1-1497 

RT P P BSet Pa cketSequenceN umber  1 1 1 -1499 

RT P P BGet Pa cketSequenceN umber  1 1 1 -1494 

RTPPBSetCal 1  back  1 1 1-1497 

RTPPBGetCal 1  back  1 1 1-1493 

RTPPBSetlnfo  1 1 1-1498 

RTPPBGetlnfo  1 1 1-1493 

NewRTPMPDataReleaseUPP  11-1102 

NewRTPPBCallbackUPP  11-1103 

DisposeRTPMPDataReleaseUPP  1-287 

DisposeRTPPBCal 1 backUPP  1-287 
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ClockGetTime  1-95 
Cl ockNewCal 1  Back  1-96 
Cl ockDi sposeCal 1  Back  1-94 
Cl ockCal 1 MeWhen  1-91 
Cl ockCancel Cal  1  Back  1-93 
Cl ockRateChanged  1-97 
Cl ockTi meChanged  I  - 1 00 
Cl ockSetTi meBase  1-98 
Cl ockStartStopChanged  1-99 
ClockGetRate  1-95 
SCGetCompressi on  Extended  1 1 1-1544 
SCPosi ti onRect  III -1554 
SCPosi ti onDi al og  III -1553 
SCSetTestlmagePictHandle  1 1 1-1566 
SCSetTestlmagePictFile  1 1 1 -1564 
SCSetTestlmagePixMap  1 1 1 - 1 568 
SCGetBestDevi ceRect  1 1 1 - 1 542 
SCRequestlmageSetti ngs  1 1 1-1555 
SCCompress Image  1 1 1-1530 
SCCompressPi cture  1 1 1-1531 
SCCompressPi ctureFi 1 e  1 1 1-1532 
SCRequestSequenceSettings  1 1 1-1556 
SCComp r ess Sequence Beg i n  1 1 1 -1533 
SCCompressSequenceFrame  1 1 1 - 1534 
SCCompressSequenceEnd  1 1 1 - 1534 
SCDefaultPictHandleSettings  1 1 1-1540 
SCDefaultPictFileSettings  1 1 1-1540 
SCDefaultPixMapSettings  1 1 1-1541 
SCGetlnfo  1 1 1-1545 
SCSetlnfo  1 1 1-1558 
SCNewGWorl d  1 1 1-1552 
SCSetCompressFl ags  III -1557 
SCGetCompressFl ags  1 1 1-1543 
SCGetSetti ngsAsText  1 1 1-1551 
SCGetSetti ngsAsAtomContai ner  1 1 1-1551 
SCSetSetti ngsFromAtomContai ner  1 1 1 -1564 
Tweenerlni ti al i ze  1 1 1-1977 
TweenerDoTween  1 1 1-1976 
TweenerReset  III -1978 
TCGetCurrentTimeCode  1 1 1-1917 
TCGetTi meCodeAtTi me  1 1 1-1920 
TCTimeCodeToString  1 1 1-1925 
TCT i meCodeTo Frame Number  1 1 1 -1924 
TCFrameNumberToT imeCode  1 1 1-1916 
TCGetSourceRef  1 1 1-1919 
TCSetSourceRef  III -1922 
TCSetTi meCodeFl ags  III -1923 
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TCGetTi meCodeFl ags  III-1921 

TCSetDi spl ayOpti ons  1 1 1-1922 

TCGetDi spl ayOpti ons  III-1918 

NewSCModal Fi 1 terUPP  11-1103 

NewSCModal  H oo kl) P P  11-1104 

NewMovi eExportGetDataUPP  11-1074 

NewMovi eExportGet Proper tyUPP  11-1074 

Di sposeSCModal Fi 1 terUPP  1-288 

Di sposeSCModal HookUPP  1-288 

DisposeMovi eExportGetDataUPP  1-274 

DisposeMovi e Expo rtGetPr ope rtyUPP  1-275 

Movi elmportHandl e  11-950 

Movi elmportFi 1 e  11-942 

Mov i el mportSet Samp leDurat ion  11-962 

Movi elmportSetSampl eDescri pti on  11-961 

Movi elmportSetMedi aFi 1 e  11-958 

Movi elmportSetDi mens  ions  11-955 

Movi elmportSetChunkSi ze  11-954 

Movi el mportSet Progress Proc  11-961 

Movi elmportSetAuxi 1 i ary Data  11-954 

Movi elmportSetFromScrap  11-957 

Movi elmportDoUserDi al og  11-940 

Movi elmportSetDurati on  11-957 

Movi elmportGetAuxi liaryDataType  11-944 

Movi elmportVal idate  11-964 

Movi elmportGetFi 1 eType  11-946 

MovielmportDataRef  11-938 

Movi el mportGet Samp 1 eDescri pti on  11-949 

Movi elmportGetMIMETypeLi st  11-948 

Movi el mportSet Of f set And  Li  mi t  11-959 

Movi elmportGetSetti ngsAsAtomContai ner  11-949 

Movi elmportSetSetti ngsFromAtomContai ner  11-963 

Movi el mportSet Of f set And  Li mit64  11-960 

Movi elmportldl e  11-953 

MovielmportValidateDataRef  11-965 

Movi elmportGetLoadState  11-947 

MovielmportGetMaxLoadedTime  11-947 

Movie  ExportToFlandle  11-936 

Movi eExportToFi 1 e  11-934 

Movi e Export Get Auxi 1 i ary Data  11-923 

Movi e Export Set  Progress Proc  11-930 

Movi e Export Set Samp 1 eDescri pti on  11-931 

Movi eExportDoUserDi al og  11-921 

Movi eExportGetCreatorType  11-924 

Movi eExportToDataRef  11-933 

MovieExportFromProceduresToDataRef  11-922 

Movi eExportAddDataSource  11-919 

Movi eExportVal idate  11-937 

Movi eExportGet Sett i ngsAsAtomContai ner  11-925 
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Movi eExportSetSetti ngsFromAtomContai ner  11-932 

Movi eExportGetFi leName Extension  11-925 

Movi eExportGetShortFi leTypeString  11-926 

Movi eExportGetSourceMedi aType  11-927 

Movi eExportSetGetMovi ePropertyProc  11-929 

Text  Expo rtGetDi splayData  1 1 1 - 1928 

Text  Expo rtGetT i me  Fraction  1 1 1 - 1929 

Text  Expo rtSetT i me  Fraction  1 1 1-1931 

TextExportGetSetti ngs  1 1 1-1928 

TextExportSetSetti ngs  1 1 1-1930 

MI DI ImportGetSetti ngs  11-917 

MI DI ImportSetSetti ngs  11-917 

Movi eExportNewGetDataAndProperti esProcs  11-927 

Movi eExportDi sposeGetDataAndProperti esProcs  11-920 

Graphics  Image  I mportSetSequenceEnabled  1-612 

Graphics  Image  I mportGetSequenceEnabled  1-612 

Previ ewShowData  11-1146 

Previ ewMakePrevi ew  11-1145 

Previ ewMakePrevi ew Reference  11-1145 

PreviewEvent  11-1144 

DataCodecDecompress  1-170 

DataCodecGetCompressBufferSi ze  1-172 

DataCodecCompress  1-167 

DataCodecBeginlnterruptSafe  1-166 

DataCodecEndlnterruptSafe  1-172 

DataCodecDecompressParti al  1-171 

DataCodecCompressParti al  1-169 

DataHGetData  1-186 

DataHPutData  1-216 

DataHFl ushData  1-184 

DataHOpenForWri te  1-210 

DataHCl oseForWri te  1-177 

DataHOpenForRead  1-209 

DataHCl oseForRead  1-176 

DataHSetDataRef  1-224 

DataHGetDataRef  1-189 

DataHCompareDataRef  1-178 

DataHTask  1-231 

DataHSchedul eData  1-220 

DataHFi ni shData  1-182 

DataHFl ushCache  1-184 

DataHResol veDataRef  1-218 

DataHGetFileSize  1-194 

DataHCanUseDataRef  1-175 

DataHGetVol umeLi st  1-207 

DataHWri te  1-232 

DataHPreextend  1-214 

DataHSetFi 1 eSi ze  1-227 

DataHGetFreeSpace  1-198 
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DataHCreateFi 1 e  1-180 
DataHGetPreferredBlockSize  1-204 
DataHGetDevi celndex  1-193 
DataHIsStreamingDataHandler  1-208 
DataHGetDatalnBuffer  1-188 
DataHGetSchedul eAheadTime  1-206 
DataHSetCacheSi zeLimit  1-224 
DataHGetCacheSizeLimit  1-185 
DataHGetMovi e  1-202 
DataHAddMovi e  1-173 
DataHUpdateMovi e  1-231 
DataHDoesBuf fer  1-182 
DataHGetFi 1 eName  1-193 
DataHGetAvai lableFileSize  1-185 
DataHGetMacOSFi 1 eType  1-200 
DataHGetMIMEType  1-201 
DataHSetDataRefWi thAnchor  1-226 
DataHGetDataRefWi thAnchor  1-192 
DataHSetMacOSFi 1 eType  1-229 
DataHSetT imeBase  1-229 
DataHGetlnfoFl ags  1-200 
DataHSchedul eData64  1-222 
DataHWri te64  1-234 
DataHGetFi 1 eSi ze64  1-195 
DataHPreextend64  1-215 
DataHSetFi 1 eSi ze64  1-228 
DataHGetFreeSpace64  1-199 
DataHAppend64  1-174 
DataHReadAsync  1-217 
DataHPol 1  Read  1-213 
DataHGetDataAvai 1 abi 1 i ty  1-187 
DataHGetFi 1 eSi zeAsync  1-196 
DataHGetDataRefAsType  1-190 
DataHSetDataRef Extensi on  1-225 
DataHGetDataRef Extensi on  1-191 
DataHGetMovi eWi thFl ags  1-203 
DataHPl aybackHi nts  1-211 
DataHPl aybackHi nts64  1-212 
VDGetMaxSrcRect  1 1 1-2012 
VDGetActi veSrcRect  1 1 1  - 1989 
VDSetDi gi ti zerRect  III -2038 
VDGetDi gi ti zerRect  III-1999 
VDGetVBl ankRect  III -2021 
VDGetMaskPi xMap  1 1 1-2011 
VDGetPl ayThruDesti nation  III-2014 
VDUseThi sCLUT  1  1  1-2057 
VDSetlnputGammaVal ue  III -2044 
VDGetlnputGammaVal ue  1  1  1-2006 
VDSetBri ghtness  III -2032 
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VDGetBri ghtness  1 1 1-1991 
VDSetContrast  III -2036 
VDSetHue  1 1 1-2041 
VDSetSharpness  1  1  1-2053 
VDSetSaturati on  III -2053 
VDGetContrast  III -1995 
VDGetHue  1 1 1-2002 
VDGetSharpness  III -2018 
VDGetSaturati on  III -2017 
VDGrabOneFrame  III -2024 
VDGetMaxAuxBuffer  1 1 1-201 1 
VDGetDigitizerlnfo  1 1 1 - 1998 
VDGetCurrentFl ags  1 1 1-1996 
VDSetKeyCol or  1 1 1-2046 
VDGetKeyCol or  1 1 1-2008 
VDAddKeyCol or  1 1 1-1985 
VDGetNextKeyCol or  1 1 1-2013 
VDSetKeyCol orRange  III -2046 
VDGetKeyCol orRange  III -2009 
VDSetDigitizerUser Interrupt  1  1  1-2039 
VDSetlnputCol orSpaceMode  1  1  1-2043 
VDGetlnputCol orSpaceMode  1  1  1-2004 
VDSetCl i pState  III -2033 
VDGetCl ipState  1 1 1-1991 
VDSetCl i pRgn  1 1 1-2032 
VDC1 earCl i pRgn  1 1 1-1986 
VDGetCLUTInlJse  1 1 1-1992 
VDSetPLLFilterType  1 1 1-2051 
VDGetPLLFilterType  1 1 1-2015 
VDGetMaskandVal ue  III -2009 
VDSetMasterBl endLevel  III -2047 
VDSetPl ayThruDesti nation  II 1-2048 
VDSetPl ayThruOnOff  1 1 1-2050 
VDSetFi el dPreference  III -2040 
VDGetFi el dPreference  III -2001 
VDPref 1 i ghtDesti nati on  III -2026 
VDPref 1 i ghtGl obal Rect  III -2028 
VDSetPl ayThruGl obal Rect  III -2049 
VDSetlnputGammaRecord  III -2044 
VDGetlnputGammaRecord  III -2006 
VDSetBl ackLevel Val ue  III -2031 
VDGetBl ackLevel Val ue  1 1 1-1990 
VDSetWhite Level  Value  1 1 1-2055 
VDGetWhi te Level Val ue  1 1 1-2024 
VDGetVi deoDefaul ts  1 1 1-2022 
VDGetNumberOf Inputs  III -2013 
VDGetlnputFormat  III -2005 
VDSetlnput  1 1 1-2042 
VDGetlnput  1 1 1-2003 
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VDSetlnputStandard  III -2045 
VDSetupBuf f ers  1  1  1-2055 
VDGrabOneFrameAsync  1  1  1-2025 
VDDone  1 1 1-1988 
VDSetCompressi on  III -2034 
VDCompressOneFrameAsync  1 1 1 - 1988 
VDCompressDone  1 1 1 - 1986 
VDRel easeCompressBuf f er  III -2030 
VDGet ImageDescri pti on  1  1  1 -2002 
VDResetCompressSequence  III -2030 
VDSetCompressi onOnOff  III -2035 
VDGetCompressi onTypes  1 1 1 - 1994 
VDSetTimeBase  1  1  1-2054 
VDSetFrameRate  1 1 1-2041 
VDGetDataRate  1 1 1-1997 
VDGetSoundlnputDriver  1 1 1-2019 
VDGetDMADepths  1 1 1-1999 
VDGetPreferredTimeScale  III -2017 
VDRel easeAsyncBuff ers  1  1  1-2029 
VDSetDataRate  III -2037 
VDGetT i meCode  1  1  1-2020 
VDUseSaf eBuf fers  III -2056 
VDGetSoundlnputSource  III -2019 
VDGetCompressionTime  1 1 1-1993 
VDSet Preferred  Packet Size  1  1  1-2052 
VDSet Preferred  I mageDi mens  ions  1  1  1-2051 
VDGet Prefer red ImageDi mens  ions  1 1 1-2016 
VDGetlnputName  1  1  1-2007 
VDSetDesti nati onPort  III -2038 
SGInitialize  1 1 1 -1752 
SGSetDataOutput  1 1 1-1785 
SGGetDataOutput  III— 1711 
SGSetGWorl d  1 1 1-1792 
SGGetGWorl d  1 1 1-1719 
SGNewChannel  1 1 1-1753 
SGDi sposeChannel  III -1695 
SGStartPrevi ew  1 1 1-1818 
SGStartRecord  III-1819 
SGIdle  1 1 1-1751 
SGStop  1 1 1-1819 
SGPause  1 1 1 -1771 
SGPrepare  III -1772 
SGRelease  1 1 1 -1773 
SGGetMovi e  1 1 1-1724 
SGSetMaxi mumRecordT ime  1 1 1-1796 
SGGetMaxi mumRecordT ime  1 1 1-1723 
SGGetStorageSpaceRemai ning  1 1 1 - 1736 
SGGetTi meRemai ning  1 1 1 - 1739 
SGGrabPi ct  1 1 1-1748 
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SGGetLastMovi eRes I D  1 1 1-1722 

SGSetFl ags  1 1 1-1789 

SGGetFl ags  1 1 1-1718 

SGSetDataProc  1 1 1  - 1 7 87 

SGNewChannel FromComponent  1 1 1-1756 

SGDi sposeDevi ceLi st  1 1 1-1696 

SGAppendDevi ceLi stToMenu  1 1 1 -1685 

SGSetSetti ngs  III -1801 

SGGetSetti ngs  1 1 1-1731 

SGGetlndChannel  1 1 1-1720 

SGUpdate  1 1 1-1821 

SGGetPause  III -1730 

SGSettingsDialog  II 1-1808 

SGGetAl i gnmentProc  1 1 1-1698 

SGSetChannel Setti ngs  1 1 1-1781 

SGGetChannel Setti ngs  1 1 1-1707 

SGGetMode  1 1 1 -1723 

SGSetDataRef  1 1 1-1787 

SGGetDataRef  1 1 1 -1716 

SGNewOutput  III -1757 

SGDi sposeOutput  III -1696 

SGSetOutputFl ags  1 1 1-1797 

SGSetChannel Output  III -1778 

SGGetDataOutputStorageSpaceRemai ning  1 1 1-1713 

SGHandl eUpdateEvent  1 1 1-1750 

SGSetOutputNextOutput  III - 1800 

SGGetOutputNextOutput  1 1 1-1729 

SGSetOutputMaxi mumOffset  1 1 1 -1799 

SGGetOutputMaxi mumOffset  1 1 1 -1728 

SGGetOutput Data  Reference  1 1 1-1727 

SGWri teExtendedMovi eData  1 1 1 - 1822 

SGGetStorageSpaceRemai ning64  1 1 1-1737 

SGWri teMovi eData  1 1 1 - 1824 

SGAddFrameReference  III -1681 

SGGetNextFrameReference  1 1 1-1726 

SGGetTi meBase  III -1738 

SGSortDevi ceLi st  1 1 1-1817 

SGAddMovi eData  1 1 1-1682 

SGChangedSource  III -1686 

SGAdd Ext ended  Frame Reference  1 1 1-1677 

SGGet Next  Ext ended  Frame  Reference  1 1 1-1725 

SGAddExtendedMovi eData  III -1678 

SGAddOutputDataRefToMedi a  1 1 1-1683 

SGSetChannel Usage  III -1782 

SGGetChannel Usage  1 1 1-1709 

SGSetChannel Bounds  III -1774 

SGGetChannel Bounds  1 1 1-1700 

SGSetChannel Vol ume  III -1783 

SGGetChannel Vol ume  1 1 1-1710 
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SGGetChannel Info  1 1 1-1702 
SGSetChannel PI ayFl ags  III-1779 
SGGetChannel PI ayFl ags  III-1705 
SGSetChannel MaxFrames  III-1777 
SGGetChannel MaxFrames  1 1 1-1704 
SGSetChannel RefCon  III-1781 
SGSetChannel Clip  1 1 1-1775 
SGGetChannel Cl i p  1 1 1-1700 
SGGetChannel Sampl eDescri pti on  1 1 1 -1706 
SGGetChannel Devi ceList  1 1 1-1701 
SGSetChannel Device  III-1776 
SGSetChannel Matrix  III-1776 
SGGetChannel Matri x  III-1703 
SGGetChannelTi me Scale  III-1708 
SGChannel PutPi cture  1 1 1 - 1689 
SGChannel Set  Requested Data  Rate  1 1 1 -1691 
SGChannel Get  Requested Data  Rate  1 1 1 -1688 
SGChannel SetDataSourceName  1 1 1-1690 
SGChannel Get DataSourceName  1 1 1-1687 
SGChannel SetCodecSetti ngs  1 1 1 - 1689 
SGChannel GetCodecSetti ngs  1 1 1  - 1686 
SGGetChannel TimeBase  1 1 1-1708 
SGIni tChannel  1 1 1-1751 
SGWri teSampl es  1 1 1 - 1825 
SGGetDataRate  III-1715 
SGA1 i gnChannel Rect  1 1 1 - 1684 
SGPanel GetDi tl  1 1 1-1761 
SGPanel GetT i 1 1 e  1 1 1-1763 
SGPanel CanRun  III-1759 
SGPanel Instal 1  1 1 1-1764 

SGPanel Event  1 1 1-1760 
SGPanel Item  1 1 1-1765 
SGPanel Remove  III-1766 
SGPanel SetGrabber  III-1767 
SGPanel SetResFi 1 e  III-1768 
SGPanel GetSetti ngs  1 1 1-1762 
SGPanel Set Set ti ngs  III -1769 
SGPanel Val idatelnput  III-1770 
SGPanelSetEventFilter  III-1767 
SGGetSrcVideoBounds  1 1 1-1735 
SGSetVi deoRect  1 1 1-1816 
SGGetVi deoRect  1 1 1-1746 
SGGetVi deoCompressorType  1 1 1-1744 
SGSetVi deoCompressorType  1 1 1-1814 
SGSetVideoCompressor  III -1812 
SGGetVideoCompressor  1 1 1-1742 
SGGetVi deoDi gi ti zerComponent  1 1 1 -1745 
SGSetVi deoDi gi ti zerComponent  1 1 1  -1815 
SGVi deoDi git i zerC hanged  1 1 1 - 1822 
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SGSetVi deoBottl enecks  1 1 1-1811 
SGGetVi deoBottl enecks  1 1 1-1741 
SGGrabFrame  1 1 1-1747 
SGGrabFrameCompl ete  1 1 1  - 1 7 48 
SGDi spl ayFrame  1 1 1-1694 
SGCompressFrame  1 1 1-1692 
SGCompressFrameCompl ete  III -1692 
SGAddFrame  1 1 1-1680 
SGT  ran sfer Frame  For Compress  1 1 1 -1820 
SGSetCompressBuffer  III -1784 
SGGetCompressBuffer  III-1711 
SGGetBufferlnfo  1 1 1-1699 
SGSetUseScreenBuffer  1 1 1-1811 
SGGetUseScreenBuffer  1 1 1-1740 
SGGrabCompressCompl ete  1 1 1-1746 
SGDi spl ayCompress  1 1 1-1693 
SGSetFrameRate  1 1 1-1792 
SGGetFrameRate  1 1 1-1719 
SGSetPreferredPacketSize  1 1 1-1801 
SGGet Prefer  red PacketSi ze  1 1 1 -1730 
SGSetUserVi deoCompressorLi st  1 1 1 -1810 
SGGetUserVi deoCompressorLi st  1 1 1 -1740 
SGSetSoundlnputDri ver  III - 1802 
SGGetSoundlnputDri ver  III -1732 
SGSoundlnputDriverChanged  1 1 1-1817 
SGSetSoundRecordChunkSize  1 1 1-1805 
SGGet So undRecordChunkSi ze  1 1 1 -1734 
SGSetSoundlnputRate  III - 1804 
SGGetSoundlnputRate  1 1 1 - 1 734 
SGSetSoundlnputParameters  1 1 1-1803 
SGGet Sound  Input  Parameters  1 1 1-1733 
SGSetAddi tionalSound Rates  1 1 1-1774 
SGGetAddi tionalSound Rates  1 1 1 -1697 
SGSetFontName  1 1 1-1790 
SGSetFontSi ze  III -1791 
SGSetTextForeCol or  III - 1807 
SGSetTextBackCol or  III - 1806 
SGSet Justi f i cati on  III -1795 
SGGetTextReturnToSpaceVal ue  1 1 1-1737 
SGSetTextReturnToSpaceVal ue  1 1 1-1807 
SGGetlnstrument  1 1 1-1721 
SGSetlnstrument  1 1 1 - 1 7 94 
QTVi deoOutputGetDispl ay Mode  Li st  11-1326 
QTVi deoOutputGetCurrentClientName  11-1325 
QTVi deoOutputSetClientName  11-1332 
QTVi deoOutputGetClientName  11-1323 
QTVi deoOutputBegi n  11-1321 
QTVi deoOutputEnd  11-1322 
QTVi deoOutputSetDispl ay Mode  11-1332 
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QTVi deoOutput Get Di s pi  ay Mode  11-1325 

QTVi deoOutputCustomConf i gureDisplay  11-1322 

QTVideoOutputSaveState  11-1331 

QTVi deoOutput Rest o restate  11-1330 

QTVideoOutputGetGWorld  11-1327 

QTVi deoOutput Get GWorl d Parameters  11-1328 

QTVideoOutputGetlndSoundOutput  11-1329 

QTVideoOutputGetCl ock  11-1324 

QTVideoOutputSetEchoPort  1 1-1333 

NewDataHCompl eti onUPP  11-1057 

NewVdi glntUPP  11-1125 

NewSGDataUPP  11-1106 

NewSGModal Fi 1 terUPP  11-1109 

NewSGGrabBottl eUPP  11-1107 

NewSGGrabCompl eteBottleUPP  11-1108 

NewSGDi splayBottleUPP  11-1106 

NewSGCompressBottl eUPP  11-1105 

NewSGCompressCompl eteBottleUPP  11-1105 

NewSGAddFrameBottl eUPP  11-1104 

NewSGT  ransferFrameBottleUPP  11-1109 

NewSGGrabCompressCompl eteBottleUPP  11-1108 

NewSGDi spl ayCompressBottl eUPP  11-1107 

Di sposeDataHCompl eti onUPP  1-259 

Di sposeVdi glntUPP  1-303 

Di sposeSGDataUPP  1-290 

Di sposeSGModal Fi 1 terUPP  1-293 

Di sposeSGGrabBottl eUPP  1-291 

Di sposeSGGrabCompl eteBottleUPP  1-292 

DisposeSGDisplayBottleUPP  1-290 

Di sposeSGCompressBottl eUPP  1-289 

Di sposeSGCompressCompl eteBottleUPP  1-289 

Di sposeSGAddFrameBottl eUPP  1-289 

Di sposeSGTransferFrameBottl eUPP  1-293 

Di sposeSGGrabCompressCompl eteBottleUPP  1-292 

DisposeSGDispl ayCompressBottl eUPP  1-291 
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QTMIDIGetMIDIPorts  11-1188 
QTMIDIUseSendPort  11-1190 
QTMIDISendMIDI  11-1189 
QTMIDIUseRecei vePort  11-1189 
Musi cGetDescri pti on  11-986 
MusicGetPart  11-999 
MusicSetPart  1 1 - 1 0 1 0 
Musi cSet Part  Instrument Number  11-1013 
Musi cGet Part  Instrument Number  11-1002 
Musi cSt ore Part  Instrument  11-1017 
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Musi cGetPartAtomi c Instrument  1 1 -1000 

Musi cSetPartAtomi c Instrument  1 1  -101 1 

Musi cGet Inst  rumen tKnobDescri ptionObsolete  11-992 

MusicGetDrumKnobDescriptionObsolete  1 1-988 

Musi cGe tKnobDescri ptionObsolete  11-995 

Musi cGetPartKnob  11-1002 

Musi cSetPartKnob  11-1014 

MusicGetKnob  11-994 

MusicSetKnob  11-1007 

Musi cGetPartName  11-1003 

Musi cSetPartName  11-1015 

Musi cFi ndTone  11-981 

Musi cPl ayNote  11-1004 

Musi cResetPart  11-1006 

Musi cSetPartControl 1 er  11-1012 

Musi cGetPartControl 1 er  1 1 -1001 

MusicGetMIDIProc  11-998 

MusicSetMIDIProc  11-1009 

Musi cGetlnstrumentNames  11-993 

Musi cGetDrumNames  11-989 

Musi cGetMasterTune  11-997 

Musi cSetMasterTune  11-1008 

Musi cGet Inst  rumen t About  Info  11-990 

Musi cGetDevi ceConnecti on  11-987 

Musi cUseDevi ceConnecti on  11-1019 

MusicGetKnobSettingStrings  11-996 

MusicGetMIDIPorts  11-997 

MusicSendMIDI  11-1006 

MusicReceiveMIDI  11-1005 

MusicStartOffline  11-1016 

Musi cSetOff 1 i neTi meTo  11-1009 

Musi cGet Inst  rumen tKnobDescri ption  11-992 

MusicGetDrumKnobDescription  1 1-988 

Musi cGetKnobDescri pti on  11-995 

Musi cGetlnfoText  11-990 

Musi cGetlnstrumentlnfo  11-991 

MusicTask  11-1018 

Musi cSetPart Inst rument Number  Inter r up t Safe  11-1013 

MusicSetPartSoundLocalization  11-1015 

Musi cGeneri cConf i gure  11-982 

Musi cGeneri cGetPart  11-985 

Musi cGeneri cGetKnobLi st  11-984 

Musi cGeneri cSetResourceNumbers  1 1-986 

Music DerivedMIDISend  11-975 

Musi cDeri vedSetKnob  11-976 

Musi cDeri vedSetPart  11-979 

Musi cDeri vedSetlnstrument  11-976 

Musi cDeri vedSetPart Inst rument Number  11-979 

Music DerivedSetMIDI  11-978 
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Musi cDeri ved St ore Part  Instrument  11-980 

Musi cDeri vedOpenResFi 1 e  11-975 

Musi cDeri vedCl oseResFi 1 e  11-974 

InstrumentGetlnst  11-767 

InstrumentGetlnfo  11-766 

Instrumentlni ti al i ze  11-769 

InstrumentOpenComponentResFi 1 e  11-770 

InstrumentCl oseComponentResFi 1 e  11-765 

InstrumentGetComponentRefCon  11-766 

InstrumentSetComponentRefCon  11-771 

I  instrument  Get  Synthesi  zerType  11-768 

NARegi sterMusi cDevi ce  11-1038 

NAUnregi sterMusi cDevi ce  11-1051 

NAGetRegi steredMusi cDevi ce  11-1028 

NASaveMusi cConfiguration  11-1039 

NANewNoteChannel  11-1030 

NADi sposeNoteChannel  11-1020 

NAGetNoteChannel Info  11-1026 

NAPrerol 1 NoteChannel  11-1037 

NAUnrol 1 NoteChannel  11-1051 

NASetNoteChannel Vol ume  11-1047 

NAResetNoteChannel  11-1039 

NAPlayNote  11-1036 

NASetControl 1 er  11-1042 

NASetKnob  11-1045 

NAFi ndNoteChannel Tone  11-1021 

NASetlnstrumentNumber  11-1044 

NAPi ck Instrument  11-1035 

NAPi ckArrangement  11-1032 

NASetDefaul tMIDI Input  11-1043 

NAGetDefaul tMIDI Input  11-1023 

NAUseDefaul tMIDI Input  11-1052 

NALoseDefaul tMIDI Input  11-1029 

NAStuf fToneDescri pti on  11-1048 

NACopyri ghtDi al og  11-1019 

NAGetlndNoteChannel  11-1023 

NAGetMIDIPorts  11-1025 

NAGetNoteRequest  11-1027 

NASendMIDI  11-1040 

NAPi ckEdi t Instrument  11-1033 

NANewNoteChannel FromAtomi c Instrument  11-1031 

NASetAtomi clnstrument  11-1041 

NAGetKnob  11-1024 

NATask  11-1049 

NASetNoteChannel Bal ance  11-1046 
NASetlnstrumentNumber Interrupt Safe  11-1044 
NASetNoteChannel SoundLocalization  11-1047 
NAGetControl 1 er  11-1022 
TuneSetHeader  1 1 1-1967 
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TuneGetTi meBase  1 1 1-1961 
TuneSetTi meScal e  1 1 1-1973 
TuneGetTi meScal e  1 1 1-1962 
TuneGetlndexedNoteChannel  1 1 1-1958 
TuneQueue  1 1 1  - 1 964 
Tunelnstant  1 1 1-1963 
TuneGetStatus  1 1 1-1961 
TuneStop  III -1975 
TuneSetVol ume  1 1 1-1974 
TuneGetVol ume  1 1 1-1963 
TunePreroll  1 1 1 - 1964 
TuneUnroll  1 1 1-1976 
TuneSetNoteChannel s  1 1 1-1969 
TuneSetPartTranspose  1 1 1-1971 
TuneGetNoteAl 1 ocator  1 1 1-1959 
TuneSetSofter  1 1 1-1972 
TuneTask  1 1 1-1975 
TuneSetBal ance  1 1 1-1966 
TuneSetSound Localization  1 1 1-1972 
TuneSetHeaderWi thSi ze  1 1 1  - 1 968 
TuneSetPartMix  1 1 1-1970 
TuneGetPartMix  1 1 1-1960 
NewMusi cMIDISendUPP  11-1094 
NewMusi cMI DI ReadHookUPP  11-1093 
NewMusi cOffl i neDataUPP  11-1094 
NewTuneCal 1 BackUPP  11-1122 
NewTunePl ayCallBackUPP  11-1123 
DisposeMusicMIDISendUPP  1-280 
DisposeMusicMID I ReadHookUPP  1-279 
Di sposeMusi cOffl i neDataUPP  1-280 
Di sposeTuneCal 1 BackUPP  1-302 
Di sposeTunePl ayCal 1 BackUPP  1-302 
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Initiali zeQTS  11-758 
TerminateQTS  1 1 1-1927 
QTSNewPresentati on  11-1250 
QTSDi sposePresentati on  11-1221 
QTSPresIdl e  11-1284 
QTSPres Inval i dateRegi on  11-1284 
QTSPresSetFl ags  11-1291 
QTSPresGetFl ags  11-1268 
QTSPresGetTi meBase  11-1281 
QTSPresGetTi meScal e  11-1282 
QTSPresSetlnfo  11-1293 
QTSPresGetlnfo  11-1272 
QTSPresHasCharacteri sti c  11-1283 
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QTSPresSetNotificationProc  11-1296 
QTSPresGetNotificationProc  11-1275 
QTSPresPrerol 1  11-1285 

QTSPresPrerol 1 64  11-1286 

QTSPresStart  11-1303 
QTSPresSki pTo  11-1302 
QTSPresSki pTo64  11-1302 
QTSPresStop  11-1304 
QTSPresNewStream  11-1284 
QTSDi sposeStream  11-1222 
QTSPresGetNumStreams  11-1277 
QTSPresGetIndStream  11-1271 
QTSGetStreamPresentation  11-1239 
QTSPresSetPref erredRate  11-1297 
QTSPresGetPreferredRate  11-1278 
QTSPresSetEnable  11-1290 
QTSPresGetEnable  11-1267 
QTSPresSetPresenti ng  11-1298 
QTSPresGetPresenti ng  11-1279 
QTSPresSetActi veSegment  11-1288 
QTSPresGetActi veSegment  11-1265 
QTS Pres  Set  PI ayHi nts  11-1296 
QTSPresGetPlayHints  11-1278 
QTSPresSetGWorl d  11-1292 
QTSPresGetGWorl d  11-1270 
QTSPresSetCl ip  11-1289 
QTSPresGetCl ip  11-1266 
QTSPresSetMatri x  11-1295 
QTSPresGetMatri x  11-1275 
QTS P res  Set Di mens  ions  11-1290 
QTS Pres  Get Di men si  on s  11-1266 
QTSPresSetGraphi csMode  11-1292 
QTSPresGetGraphicsMode  11-1269 
QTSPresGetPi cture  11-1277 
QTSPresSetVol umes  11-1301 
QTSPresGetVol umes  11-1282 
QTSSetNetworkAppName  11-1305 
QTSGetNetworkAppName  11-1237 
QTSNewStatHel per  11-1255 
QTSDi sposeStatHel per  11-1221 
QTSStatHel perGetStats  11-1310 
QTSStatHel perResetlter  11-1312 
QTSStatHel perNext  11-1311 
QTSStatHel perGetNumStats  11-1310 
QTSGetOrMakeStatAtomForStream  11-1238 
QTSInsertStati sti c  11-1239 
QTSInsertStati sti cName  11-1241 
QTSInsertStatisticUnits  11-1242 
QTSPref sAddProxySetti ng  11-1257 
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QTSPrefsFi ndProxyByType  11-1260 
QTSPrefsAddConnectionSetting  11-1257 
QTSPrefsFi ndConnecti on  By Type  11-1259 
QTSPrefsGetActi veConnection  11-1262 
QTSP refs Get No  Proxy URLs  11-1263 
QTSP refs Set No  Proxy URLs  11-1263 
QTSNewPtr  11-1253 
QTSNewHandl e  11-1249 
QTSA1 1 ocMemPtr  11-1218 
QTSRel easeMemPtr  11-1304 
QTSA1 1 ocBuffer  11-1218 
QTSFreeMessage  11-1236 
QTSDupMessage  11-1223 
QTSCopyMessage  11-1220 
QTSF1 attenMessage  11-1235 
QTSMessageLength  11-1249 
QTSGetErrorStri ng  11-1236 
NewQTSNoti f i cati onUPP  11-1098 
DisposeQTSNotificationUPP  1-283 


QuickTime  VR.h 


NewQTVRLeavi ngNodeUPP  1 1 -1101 
NewQTVREnteri ngNodeUPP  1 1 - 1 100 
NewQTVRMouseOverHotSpotUPP  11-1102 
NewQTVRImagi ngCompl eteUPP  1 1  - 1 1 00 
NewQTVRBackBufferlmagi ngUPP  11-1099 
Di sposeQTVRLeavi ngNodeUPP  1-286 
Di sposeQTVREnteri ngNodeUPP  1-285 
Di sposeQTVRMouseOverHotSpotUPP  1-286 
Di sposeQTVRImagi ngCompl eteUPP  1-285 
Di s pos eQTVRB a ck Buffer  I  magi ngUPP  1-284 
NewQTVRInterceptUPP  1 1 -1101 
Di sposeQTVRInterceptUPP  1-286 
Initial izeQTVR  11-758 
Termi nateQTVR  1 1 1-1927 
QTVRGetQTVRT  rack  11-1375 
QTVRGetQTVRInstance  11-1373 
QTVRSetPanAngl e  11-1431 
QTVRGetPanAngl e  11-1373 
QTVRSetT i 1 tAngl e  11-1434 
QTVRGetT i 1 tAngl e  11-1377 
QTVRSetFi el dOfVi ew  11-1420 
QTVRGetFi el dOfVi ew  11-1360 
QTVRShowDef aul tVi ew  11-1442 
QTVRSetVi ewCenter  11-1437 
QTVRGetVi ewCenter  11-1378 
QTVRNudge  11-1402 
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QTVRInteracti onNudge  11-1389 
QTVRGetVRWorl d  11-1385 
QTVRGetNodelnfo  11-1371 
QTVRGoToNodelD  11-1386 
QTVRGetCur rent Node  ID  11-1359 
QTVRGetNodeType  11-1372 
QTVRPtToHotSpotID  11-1405 
QTVRGet Hot Spot Type  11-1364 
QTVRTri ggerHotSpot  11-1443 
QTVRSetMouseOverHotSpotProc  11-1429 
QTVREnabl eHotSpot  11-1340 
QTVRGet Vi  si bl eHot Spots  11-1384 
QTVRGetHotSpotRegi on  11-1363 
QTVRSetMouseOverT racking  11-1431 
QTVRGet Mou seOverT  racking  11-1370 
QTVRSetMouseDownTracki ng  11-1429 
QTVRGet Mou seDownT  racking  11-1370 
QTVRMouseEnter  11-1392 
QTVRMouseWi thin  11-1401 
QTVRMouseLeave  11-1394 
QTVRMouseDown  11-1391 
QTVRMouseSti 1 1  Down  11-1395 
QTVRMouseUp  11-1398 
QTVRMouseSti 1 1  Down  Ext ended  11-1396 
QTVRMouseUpExtended  11-1399 
QTVRInstal 1 InterceptProc  11-1387 
QTVRCal 1 InterceptedProc  11-1336 
QTVRGetCurrentMouseMode  11-1358 
QTVRSetFrameRate  11-1421 
QTVRGetFrameRate  11-1362 
QTVRSetVi ewRate  11-1439 
QTVRGetVi ewRate  11-1381 
QTVRSetViewCurrentTime  11-1438 
QTVRGetViewCurrentTime  11-1379 
QTVRGetCur rent Vi ewDuration  11-1360 
QTVRSetVi ewState  11-1440 
QTVRGetVi ewState  11-1382 
QTVRGetVi ewStateCount  11-1383 
QTVRSetAni mati onSetti ng  11-1409 
QTVRGetAni mati onSetti ng  1 1-1344 
QTVRSetControl Setti ng  11-1416 
QTVRGetControl Setti ng  11-1355 
QTVREnabl eFrameAni mati on  11-1339 
QTVRGetFrameAnimati on  11-1361 
QTVREnabl eVi ewAni mati on  11-1342 
QTVRGetViewAnimation  11-1377 
QTVRSetVi si bl e  11-1441 
QTVRGetVi si bl e  11-1384 
QTVRSetlmagi ngProperty  11-1422 
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QTVRGetlmagi ngProperty  11-1365 

QTVRUpdate  11-1445 

QTVRBegi nUpdateStream  11-1335 

QTVREndUpdateStream  11-1343 

QTVRSetT ransiti on  Property  11-1435 

QTVREnabl eTransi ti on  11-1341 

QTVRSetAngul arUni ts  11-1408 

QTVRGetAngul arUni ts  11-1344 

QTVRPtToAngles  11-1404 

QTVRCoordToAngl es  11-1338 

QTVRAngl esToCoord  11-1334 

QTVRPanToCol umn  11-1403 

QTVRCol umnToPan  11-1337 

QTVRTi 1 tToRow  11-1443 

QTVRRowToTi 1 t  11-1407 

QTVRWrapAndConstrai n  11-1446 

QTVRSetEnteri ngNodeProc  11-1419 

QTVRSetLeavi ngNodeProc  11-1428 

QTVRSet Interact i on  Property  11-1425 

QTVRGet I n ter act i on  Property  11-1368 

QTVRRepl aceCursor  11-1407 

QTVRGetVi ewi ngLi mi ts  11-1379 

QTVRGetConstrai ntStatus  11-1353 

QTVRGetConstrai nts  11-1352 

QTVRSetConstrai nts  11-1415 

QTVRGetAvai lableResolutions  11-1346 

QTVRGetBackBufferMemlnfo  11-1347 

QTVRGet BackBufferSetti ngs  11-1350 

QTVRSetBackBufferPref s  11-1412 

QTVRSet Prescreen  I  magi ngCompl eteProc  11-1432 

QTVRSetBackBufferlmagi ngProc  11-1411 

QTVRRef reshBackBuffer  11-1406 


QuickTime  VRFormat.h 

No  functions  are  declared  in  Qui  ckT i  meVRFormat .  h. 
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NewSndCal 1 BackUPP  1 1 -1111 
Di sposeSndCal 1 BackUPP  1-294 
NewSndDoubl eBackUPP  11-1111 
Di sposeSndDoubl eBackUPP  1-295 
NewSoundParamUPP  11-1112 
NewSoundConverterFi 1 1 BufferDataUPP  11-1112 
NewSI InterruptUPP  1 1 - 1 1 10 
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NewSICompl eti onUPP  1 1  - 1 1 1 0 

Di sposeSoundParamUPP  1-296 

DisposeSoundConverterFillBufferDataUPP  1-295 

Di sposeSI InterruptUPP  1-294 

Di sposeSICompl eti onUPP  1-293 

NewFi 1 ePl ayCompl eti onUPP  11-1059 

DisposeFilePl ayCompl eti onUPP  1-261 

SysBeep  1 1 1-1915 

SndDoCommand  1 1 1 - 1831 

SndDoImmedi ate  1 1 1 - 1832 

SndNewChannel  1 1 1 - 1839 

SndDi sposeChannel  1 1 1 - 1830 

SndPlay  1 1 1-1842 

SndAddModi f i er  1 1 1 - 1828 

SndControl  1 1 1 - 1829 

SndSoundManagerVersion  1 1 1-1847 

SndStartFilePlay  1 1 1 - 1847 

SndPauseFi 1 ePl ay  1 1 1 - 1841 

SndStopFi 1 ePl ay  1 1 1 - 1848 

SndChannel Status  1 1 1-1829 

SndManagerStatus  1 1 1 - 1839 

SndGetSysBeepState  1 1 1 - 1833 

SndSetSysBeepState  1 1 1 - 1846 

SndPl ayDoubl eBuf fer  1 1 1 - 1843 

MACEVersion  11-784 

Comp3tol  1-104 

Explto3  1-342 

Comp6tol  1-106 

Explto6  1-343 

GetSysBeepVol ume  1-514 

SetSysBeepVol ume  1 1 1  - 1647 

GetDef aul tOutputVol ume  1-408 

SetDef aul tOutputVol ume  1 1 1  - 1582 

GetSoundHeaderOf f set  1-510 

UnsignedFixedMulDiv  1 1 1  - 1980 

GetCompressi onlnfo  1-398 

SetSoundPreference  1 1 1-1641 

GetSoundPref erence  1-512 

OpenMi xerSoundComponent  11-1132 

Cl oseMi xerSoundComponent  1-102 

SndGetlnfo  1 1 1-1833 

SndSetlnfo  1 1 1-1845 

GetSoundOutputlnfo  1-511 

SetSoundOutputlnfo  1 1 1 - 1640 

GetCompressi onName  1-400 

SoundConverterOpen  1 1 1-1867 

SoundConverterCl ose  1 1 1 - 186 1 

SoundConve rterGet Buffers izes  1 1 1-1866 

SoundConverterBeginConversion  1 1 1-1861 
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SoundConverterConvertBuffer  1 1 1 -1862 

SoundConverterEndConversion  1 1 1-1863 

SoundConverterGetlnfo  III - 1867 

SoundConverterSetlnfo  III - 1868 

SoundConverterFill Buffer  1 1 1-1864 

SoundManagerGetlnfo  III - 1869 

SoundManagerSetlnfo  III - 187  0 

SoundComponent Ini tOutputDevice  1 1 1-1852 

SoundComponentSetSource  III - 1858 

SoundComponentGetSource  III - 1850 

SoundComponent Get Source Data  1 1 1-1851 

SoundComponentSetOutput  III - 1857 

SoundComponentAddSource  III - 1848 

SoundComponent Remo veSource  1 1 1 -1855 

SoundComponentGetlnfo  III - 1849 

SoundComponentSetlnfo  III - 1856 

SoundComponentStartSource  1 1 1-1859 

SoundComponentStopSource  1 1 1 -1860 

SoundComponentPauseSource  1 1 1-1853 

SoundComponent PI  ay Source Buffer  1 1 1 -1854 

Audi oGetVol ume  1-49 

Audi oSetVol ume  1-52 

AudioGetMute  1-48 

Audi oSetMute  1-51 

Audi oSetToDefaul ts  1-51 

AudioGetlnfo  1-48 

AudioGetBass  1-47 

AudioSetBass  1-50 

Audi oGetTrebl e  1-49 

Audi oSetTrebl e  1-51 

Audi oGetOutputDevi ce  1-49 

Audi oMuteOnEvent  1-50 

SPBVersi on  1 1 1-1884 

SndRecord  1 1 1 - 1843 

SndRecordToFi 1 e  III -1845 

SPBSignlnDevice  III - 1882 

SPBSi gnOutDevi ce  III - 1883 

SPBGetlndexedDevi ce  1 1 1 - 1873 

SPBOpenDevi ce  III - 187  6 

SPBC1 oseDevi ce  1 1 1-1871 

SPBRecord  1 1 1-1878 

SPBRecordToFi 1 e  1 1 1-1880 

SPBPauseRecordi ng  1 1 1 - 1877 

SPBResumeRecordi ng  III -1881 

SPBStopRecordi ng  III - 1883 

SPBGetRecordi ngStatus  III -1874 

SPBGetDevi celnfo  III - 187 1 

SPBSetDevi celnfo  III - 1881 

SPBMi 1 1 i secondsToBytes  III - 187  5 
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SPBBytesToMi 11 i seconds  1 1 1-1870 
SetupSndHeader  III-1672 
SetupAI FFHeader  1 1 1-1670 
ParseAIFFHeader  11-1136 
ParseSndHeader  11-1136 
SndlnputReadAsync  1 1 1 - 1836 
SndlnputReadSync  1 1 1 - 1837 
SndlnputPauseRecordi ng  1 1 1 - 1836 
SndlnputResumeRecordi ng  1 1 1 -1837 
Snd Input St op Recording  1 1 1-1838 
SndlnputGetStatus  1 1 1 - 1835 
Snd I nputGet Deviceinfo  1 1 1-1834 
SndlnputSetDevi celnfo  1 1 1 - 1838 
Sndlnputlni tHardware  1 1 1 -1835 
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All  the  volumes  of  QuickTime  API  developer  documentation  are  available 
online  for  download  from  Apple's  QuickTime  Technical  Publications  website  at 

http :/ /devel oper. appl e. c om/techpubs /qu ickti me /qtdevdocs/RM /frames et2.htm 

This  website  is  the  most  current  and  up-to-date  source  for  all  QuickTime 
developer  documentation.  A  complete  roadmap  of  topics  and  functions  is 
provided  for  developers  who  want  to  build  applications  using  the  QuickTime 
API.  The  QuickTime  technical  documentation  suite  totals  more  than  7,000 
pages. 


QuickTime  Programming  Books  in  PDF 

QuickTime  developer  documents  are  also  available  in  Adobe  Portable 
Document  format  (PDF).  PDF  files  can  be  opened  and  viewed  online,  as  well  as 
downloaded  from 

http :/ /devel oper. apple. com/techpubs /qu ickti me /qtdevdocs/RM/ PDF. htm 

From  this  site  you  can  download  the  following  books,  cited  in  this  reference: 

•  Inside  Macintosh:  QuickTime 

•  Inside  Macintosh:  QuickTime  Components 

•  Programming  with  QuickTime  VR  2.1 

•  Inside  QuickTime:  QuickTime  File  Format 

Other  useful  books  that  you  can  download  include: 

•  What's  New  in  QuickTime  4.1 :  documents  the  new  features  of  QuickTime  4.1. 

•  Mac  OS  for  QuickTime  Programmers :  documents  the  Mac  OS  system  calls  and 
data  structures  that  are  included  in  QuickTime  4  for  Windows  and  used  by 
QuickTime  developers.  This  material  is  also  documented  in  various  volumes  of 
Inside  Macintosh.  It  is  brought  together  here  primarily  for  the  convenience  of 
Windows  programmers. 

•  QuickTime  Wired  Movies  And  Sprite  Animation:  Describes  and  documents  the 
API  for  creating  interactive  movies  and  sprites,  including  HREF  Tracks  and 
wired  sprites. 
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•  QuickTime  Streaming:  Documents  the  features  and  API  for  QuickTime 
Streaming  over  RTP. 

•  QTSS  Streaming  Server  API:  Documents  the  API  for  adding  modules  to  the 
QuickTime  Streaming  Server. 

•  QuickTime  For  Java  Summary:  An  overview  of  and  introduction  to  the 
QuickTime  for  Java  API. 

•  QuickTime  for  Windozvs  Programmers:  Describes  the  features  of  QuickTime 
programming  that  are  unique  to  Windows. 

•  QuickTime  Music  Architecture  for  Macintosh  and  Windozvs:  Provides  information 
for  Mac  and  Windows  developers  who  are  adding  QuickTime  music  support  to 
their  applications. 

•  Mac  OS  Sound,  Including  Sound  Manager  3.3:  Documents  all  aspects  of  using 
sound  for  QuickTime  developers. 

•  3D  Graphics  Programming  zvith  QuickDrazv  3D:  Programming  guide  to 
QuickDraw  3D,  version  1.5.4 

•  Improvements  in  QuickDrazv  3D  1.6:  Documents  changes  and  additions  to 
QuickDraw  3D,  version  1.6.  You  also  need  to  read  3D  Graphics  Programming  zvith 
QuickDrazv  3D. 

•  Making  Cool  QuickDrazv  3D  Applications:  Programming  hints  for  3D 
developers. 


The  QuickTime  Developer  Series 

Three  overview  books  are  currently  available  in  the  QuickTime  Developer 
Series.  These  books  are  published  by  Morgan  Kaufmann;  they  are  available 
from  online  booksellers  and  most  computer  bookstores. 

•  Discovering  QuickTime  (ISBN  0-12-059640-7),  515  pp.  This  is  the  official  guide 
to  programming  QuickTime  in  C.  It  includes  working  demos  and  code  samples 
on  its  CD-ROM. 

•  QuickTime  for  Java  (ISBN  0-12-305440-0),  655  pp.  This  is  the  official  guide  for 
Java  programmers  who  want  to  use  QuickTime.  It  includes  a  full  description  of 
the  Java  interface  to  QuickTime  and  a  CD-ROM  with  working  examples. 

•  QuickTime  for  the  Web  (ISBN  0-12-471255-X),  720  pp.  This  is  the  most 
comprehensive  book  available  for  authoring  QuickTime  movies  on  the  Web. 
The  CD  includes  QuickTime  4  Pro  for  both  Macintosh  and  Windows. 
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Inside  Macintosh 

The  original  25  volumes  of  Inside  Macintosh,  covering  all  aspects  of  Mac  OS 
programming,  were  published  by  Addison- Wesley.  The  following  books,  cited 
in  this  reference,  are  available  online  at 

http://developer. apple. com/ techpubs/macos8/ Indexes /document i ndex.html: 

•  Advanced  Color  Imaging  on  the  Mac  OS 

•  Files 

•  Imaging  With  QuickDraw 

•  Memory 

•  More  Macintosh  Toolbox 

•  PowerPC  System  Software 

•  Sound 

•  Text 

Of  these  books,  the  following  titles  are  available  in  printed  editions  from 

http : //www .fatbrain.com/: 

•  Imaging  With  QuickDraw 

•  More  Macintosh  Toolbox 

Some  Useful  QuickTime  Websites 

•  Ftere  is  Apple's  official  site  for  information,  demos,  sample  code,  online 
documentation,  and  the  latest  software: 

http : //www . appl e . com/qui cktime/ 

•  QuickTime  Live!  is  an  Apple-sponsored  conference  for  both  content  providers 
and  Macintosh  and  Windows  application  developers: 

http : //www . appl e . com/qui cktime 1 i ve/ 

•  QuickTime  terms  and  definitions  current  in  the  industry,  plus  a  good  set  of 
links  to  other  QuickTime  sites: 

http : //www . pcwebopedi a . com/Qui ckTime . htm 

•  Channel  QuickTime,  an  Apple  home  page  with  links  to  FAQs,  forums,  and 
the  latest  news  about  QuickTime: 

http : //www .quicktimefaq.org/ 
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•  The  entry  point  for  a  variety  of  announcements  and  discussion  forums  about 
QuickTime,  multimedia,  and  other  topics  of  interest  to  QuickTime  developers: 

http  :  //www .1 ists. apple. com/ 

•  A  site  with  lots  of  goodies,  maintained  by  the  authors  of  the  MoviePlayer 
documentation  and  updated  frequently  A  useful  resource: 

http : //www .bmug.org/quicktime/ 

•  The  International  QuickTime  VR  Association  website,  a  professional 
association  that  promotes  and  supports  the  use  of  QuickTime  VR  and  related 
technologies  worldwide: 

http : //www .iqtvra.org/ 
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alias 


An  object  in  the  Mac  OS  file  system  that  represents  a  file,  directory,  or  volume. 

band 

A  horizontal  strip  from  an  image.  QuickTime  may  break  an  image  into  bands  if  a 
codec  cannot  process  the  whole  image  at  one  time. 

base  graphics  exporter 

A  component  that  handles  most  of  the  tasks  of  a  graphics  exporter.  You  can  build 
on  the  base  component  to  reduce  the  amount  of  work  required  to  create  a  custom 
graphics  exporter. 

base  graphics  importer 

A  component  that  handles  most  of  the  tasks  of  a  graphics  importer.  You  can  build 
on  the  base  component  to  reduce  the  amount  of  work  required  to  create  a  custom 
graphics  importer. 

big-endian 

Data  formatting  in  which  multibyte  fields  are  addressed  by  pointing  to  their  most 
significant  bytes. 

blacklining 

A  technique  in  which  every  other  horizontal  line  of  an  image  is  displayed. 


callback  event 

A  scheduled  invocation  of  a  callback  function.  Your  application  establishes  the 
criteria  that  determine  when  the  callback  is  to  be  invoked. 


CarbonLib 

The  main  API  library  for  Carbon,  the  currently-supported  Mac  OS  system 
software. 


color  lookup  table 

A  data  structure  that  maps  QuickDraw  color  indexes  into  actual  RGB  color  values. 

dither 

To  mix  existing  colors  together,  by  alternating  their  pixels,  creating  the  illusion  of 
a  third  color  that  is  otherwise  unavailable. 
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HFS 

Hierarchical  File  System,  the  file  system  used  in  current  versions  of  the  Mac  OS. 

interlace 

A  video  mode  that  updates  alternate  scan  lines  on  succeeding  screen  refreshes. 

key  frame 

A  sample  in  a  sequence  of  temporally  compressed  samples  that  does  not  rely  on 
other  samples  for  any  of  its  information.  Also  called  a  sync  sample. 

little-endian 

Data  formatting  in  which  multibyte  fields  are  addressed  by  pointing  to  their  least 
significant  bytes. 

MACE 

Macintosh  Audio  Compression  and  Expansion,  an  audio  compression  format  that 
QuickTime  supports  but  which  is  not  recommended  for  new  applications. 

blend  matte 

A  pixel  map  that  defines  the  blending  of  video  and  digital  data  for  a  video  digitizer 
component.  The  value  of  each  pixel  in  the  matte  determines  the  relative  intensity 
of  the  corresponding  video  pixel  in  the  resulting  image. 

modifier  key 

In  Macintosh  computers,  any  of  the  Option,  Command,  Caps  Lock,  Control,  or 
Shift  keys. 

picture  file 

A  file  of  QuickDraw  drawing  commands. 

poster 

A  frame  shot  from  a  QuickTime  movie  that  is  used  to  represent  its  content  to  the 
user. 

preview 

A  short,  potentially  dynamic,  visual  representation  of  the  contents  of  a  file.  File 
dialog  boxes  present  previews  to  the  user. 

progress  function 

An  application-defined  function  that  you  can  use  to  track  the  progress  of  an 
operation  and  keep  the  user  informed. 

region  code 

A  constant  that  defines  a  geographical  region  for  purposes  of  localization. 
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resource 

In  Mac  OS  programming,  any  data  stored  as  a  defined  structure  in  the  resource 
fork  of  a  Macintosh  file.  The  data  in  the  resource  is  interpreted  according  to  its 
resource  type. 

shadow  sync 

A  self-contained  sample  that  is  an  alternate  for  an  already  existing  frame  difference 
sample.  During  certain  random-access  operations,  a  shadow  sync  sample  is  used 
instead  of  a  normal  key  frame,  which  may  be  very  far  away  from  the  desired 
frame. 

sprite 

An  animated  image  that  is  managed  by  QuickTime.  A  sprite  is  defined  once  and  is 
then  animated  by  commands  that  change  its  position  or  appearance. 

Standard  File  Package 

Part  of  the  Mac  OS  system  software  that  manages  the  user  interface  for  naming, 
choosing,  and  identifying  files. 

sticky  error 

One  of  two  error  values  maintained  by  the  Movie  Toolbox.  The  sticky  error  is 
updated  only  when  an  application  directs  the  Movie  Toolbox  to  do  so.  The  other 
error  value,  the  current  error,  is  updated  by  every  Movie  Toolbox  function. 

sync  sample 

A  sample  in  a  sequence  of  temporally  compressed  samples  that  does  not  rely  on 
other  samples  for  any  of  its  information.  Also  called  a  key  frame. 

32-bit  clean 

A  programming  environment  in  which  the  OS  manages  all  bits  of  32-bit  addresses 
and  applications  do  not  use  any  high  bits  for  non-addressing  purposes. 

ticks 

Sixtieths  of  a  second.  QuickTime  often  measures  time  intervals  in  ticks. 

time  structure 

A  TimeRecord  data  structure,  which  contains  a  time  value,  a  time  scale  in  units  per 
second,  and  a  reference  to  a  time  base. 

tween 

To  interpolate  new  data  between  given  values  in  conformance  to  an  algorithm.  It 
is  an  efficient  way  to  expand  or  smooth  a  movie's  presentation  between  its  actual 
frames. 
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Unicode 

An  international  standard  that  encodes  written  language  marks  as  16-bit  values.  It 
covers  Chinese,  Japanese,  and  Korean  characters  plus  all  the  world's  current 
alphabets. 

Universal  Procedure  Pointer 

In  the  Mac  OS,  a  680x0  procedure  pointer  or  the  address  of  a  routine  descriptor  that 
can  route  calls  to  a  PowerPC  processor. 

user  data  list 

A  QuickTime  data  structure  that  contains  readable  text  information  about  a  movie. 

vector  data  stream 

An  ordered  series  of  QuickTime  atoms  that  contain  information  about  vector  paths 
and  their  characteristics. 
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